Skip to content

agents.md

Latest commit

 

History

History
74 lines (60 loc) · 3.96 KB

agents.md

File metadata and controls

74 lines (60 loc) · 3.96 KB
Raw

Baby Bouncing Ball Game - Agent Guide

Welcome to the Baby Bouncing Ball Game project! This document provides essential context and guidelines for AI agents working on this codebase.

👶 Project Overview

A simple, responsive HTML5 game built with Phaser 3 designed for babies and toddlers. The goal is gentle interaction: bouncing a ball, moving clouds, and hitting the sun with realistic but soft physics.

🛠 Tech Stack

  • Engine: Phaser 3.80.1 (Arcade Physics)
  • Language: Vanilla JavaScript (ES6+)
  • Styling: CSS3 (Vanilla)
  • Deployment: GitHub Pages (PWA enabled)
  • Assets: SVG-based vector graphics for infinite scaling.

📂 Project Structure

  • index.html: The entry point. Contains the game container, UI overlays (mute button, counters), and PWA metadata.
  • game.js: The heart of the project. Contains the BabyBallGame class (extending Phaser.Scene). Logic for physics, input, resizing, and sound.
  • styles.css: Custom styles for the UI, including the glassmorphism effects and responsive layout.
  • service-worker.js: Handles caching and offline support for the PWA.
  • assets/:
    • audio/: MP3 sound effects for collisions and throws.
  • svg/: SVG source files for game objects (ball, cloud, sun).
  • phaser/: Local copies of the Phaser library for offline development.

🧠 Key Logic & Patterns

1. Responsive Design (screenMode)

The game scales dynamically based on screen width:

  • xxlargeScreen (≥1200px)
  • xlargeScreen (≥1024px)
  • largeScreen (≥750px)
  • mediumScreen (≥600px)
  • smallScreen (<600px) Object sizes and cloud counts adjust automatically based on these modes.

2. Physics & Interaction

  • Ball: The only object with gravity (this.physics.world.gravity.y = 300).
  • Clouds/Sun: No gravity by default (allowGravity = false). They become movable when hit or dragged.
  • Draggable: All objects are interactive and can be "thrown" using a flick gesture (drag and release).
  • Centrifuge Aiming: A custom input system where holding anywhere (not on an object) shows a rotating arrow for throwing the ball.

3. Audio System

  • Autoplay Policy: Audio context is unlocked on the first user interaction (pointerdown, click, etc.).
  • Mute State: Persisted in localStorage as babyBallGameMuted.
  • Immediate Play: Sounds play immediately on collision (the previous priority system was removed to allow simultaneous sounds).

4. Hitboxes

  • Most objects use circular hit areas for cleaner collisions:
    • Ball: Full radius.
    • Sun: ~20% of width (centered).
    • Clouds: ~16% of width (centered).
  • Visual debug mode can be toggled by enabling this.physics.world.drawDebug (usually disabled).

🎨 Design Philosophy (Vibe)

  • Aesthetics: Premium, vibrant, and "soft".
  • Borders: SVG assets should have soft, anti-aliased edges (check svg/ files for filter implementations).
  • Feedback: Every interaction should provide visual (bounce/rotation) and auditory (sound) feedback.

🚀 Development Workflow

  1. Local Testing: Run a local server (e.g., npx http-server -c-1) to view the game and test PWA features.
  2. Debugging: Use console.log for physics events and check the Phaser debug drawer if hitboxes seem off.
  3. Resizing: Always test the "responsive" behavior by resizing the browser window; the game handles resize events to reposition objects within bounds.

📝 Recent Focus Areas

  • Refining physics "nudge" values to prevent objects from getting stuck.
  • Improving Safari/iOS audio reliability.
  • Softening SVG asset borders for a more premium "baby-friendly" look.
  • Ensuring the PWA manifest and service worker are correctly configured for offline play.

Generated by Antigravity for the Baby Bouncing Ball Game.