Gravity Dots

A physics-based puzzle game built on HTML5 Canvas 2D. Place gravity wells on a canvas, launch a particle, and manipulate its trajectory to hit targets using gravitational forces. Seven levels introduce progressively complex mechanics with wall obstacles and multi-well puzzles.

Delivered as a single self-contained HTML file with zero external dependencies. Includes procedural audio via Web Audio API.

Quick Start

No installation, build step, or server required.

Installation

Prerequisites

• Modern web browser (Chrome, Firefox, Safari, Edge, latest versions)
• No Node.js or npm required for gameplay
• Optional: Node.js 18+ to run tests

Verification

Open src/gravity-dots.html in your browser. You should see:

• Level select screen with 7 buttons in a grid layout
• Each level shows: number, par (ideal well count), earned stars
• Clicking a level loads gameplay with space background, stars, nebula, and grid

Usage

Controls

Level Select Screen

Click any level button to load that level. All 7 levels are always available — no locks.

Gameplay

Star Rating

• 3 stars: Wells used <= par
• 2 stars: Wells used = par + 1
• 1 star: Wells used > par + 1

Audio

All audio is generated procedurally via Web Audio API — no external audio files.

Examples

Level 1 — Tutorial (Par: 1)

Target: Right side at (1100, 400)
Strategy: Place one blue well (0.5 mass) below the horizontal center.
          The particle curves downward and hits the target.
Result: 3 stars (1 well used <= 1 par)

Level 3 — Intermediate (Par: 2)

Target: Bottom-right at (1100, 600)
Strategy: Place first well (blue, 0.5) to start curving particle down.
          Place second well (purple, 1.0) to accelerate toward target.
Result: 3 stars (2 wells used <= 2 par)

Level 6 — Expert (Par: 3)

Target: Right at (1000, 300) with wall obstacles
Strategy: Use all three wells to navigate around walls:
          1st (blue, 0.5) — initial curve
          2nd (purple, 1.0) — mid-path correction
          3rd (red, 2.0) — strong final pull to target
Result: 3 stars (3 wells used <= 3 par)

Level Design

Architecture

Dual-File Pattern

Pure-Function Logic Modules (src/*.js):

• physics.js — Gravity, collision detection, particle movement
• game-state.js — State management, well placement, star ratings
• particles.js — Trail points, spark particles
• audio.js — Web Audio API sound generation
• levels.js — Level configurations (source of truth)
• game-logic.js — Re-exports all modules

• Contains identical game logic inlined in <script> block
• Adds Canvas rendering, input handling, animation loop
• Integrates all audio with mute toggle
• Pure HTML/CSS/JS — no build step, no dependencies

Physics Model

• Gravity constant (G): 50,000
• Effect radius: 150 px (gravity only within this distance)
• Formula: Force = (G x mass) / distance^2
• Particle speed: 400 px/sec initial horizontal velocity
• Timestep: Fixed 1/60 sec (60 FPS)
• Target hitbox: 32 px radius

Testing

Run All Tests

node --test tests/*.test.js

159 tests across 5 test files, all passing:

Browser-Only Test Scenarios

These require manual verification in a browser:

• Level select screen renders 7 buttons with correct layout
• Well animations: pulsing ring, spiral distortion, vortex dots
• Particle trail: 3 overlapping semi-transparent lines
• Spark emission: 5-10 particles per frame
• Audio plays at correct events (well, launch, hit, miss)
• Screen shake on wall/miss collision
• Mute toggle works and persists
• Background: stars twinkle, nebula visible, vignette at edges
• Target: golden bullseye with pulsing animation
• 60 FPS performance during gameplay

File Structure

projects/010-canvas-game/3-development/
├── src/
│   ├── gravity-dots.html   (Deployable game — open in browser)
│   ├── game-logic.js       (Re-exports all modules)
│   ├── physics.js          (Gravity, collisions)
│   ├── game-state.js       (State management)
│   ├── particles.js        (Trails, sparks)
│   ├── audio.js            (Web Audio API sounds)
│   └── levels.js           (Level configurations)
├── tests/
│   ├── physics.test.js
│   ├── game-state.test.js
│   ├── particles.test.js
│   ├── audio.test.js
│   └── levels.test.js
├── docs/
│   ├── README.md           (This file)
│   └── lint-output.txt     (Lint diagnostic output)
├── package.json
└── DELIVERABLES.md

Error Messages

Browser Compatibility

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Credits

Development Team

• Jordan Cruz (TDD, test suite)
• Taylor Singh (implementation, physics engine, audio integration)
• Riley Okafor (documentation)