1️⃣ Main Components

a) Player

• Controlled via arrow keys or A/D for movement, SPACE/UP for jump.

• Has physics: vel_y, GRAVITY, on_ground.

• Animations:

  • Idle

  • Jump

• Jump mechanics currently support fixed jump velocity, with potential for variable height (hold-to-jump feature).

• Collision detection with: ground, answer cubes, coins.

b) Answer Cubes

• Float above the ground using sinusoidal offset.

• Correct/incorrect flags determine score and lives.

• Flashes on correct answer collision.

• Text rendered above the cube shows the value.

• Can adjust vertical position (base_y) to be lower or higher.

c) Coins

• Float slightly above ground with sinusoidal motion.

• Increase score when collected.

• Removed on collision with player.

d) Floating Text

• Displays score changes, combo, or penalties.

• Fades and moves upwards over time.

e) Particles / Puffs

• Small circular effects when player jumps.

• Radius grows and fades over time.

2️⃣ Game Loop

• FPS capped at 60.

• Each frame:

  1. Event handling (key presses, quit).

  2. Player movement update.

  3. Update puffs, cubes, coins, floating texts.

  4. Collision detection (cubes, coins).

  5. Timer update per level.

  6. Combo logic with decay.

  7. Drawing:

     • Backgrounds (sky, far ground, clouds)

     • Ground tiles

     • Player

     • Cubes

     • Coins

     • Particles

     • HUD

• Level intro overlay is displayed for 1 second at start.

• Game over or win overlay appears when the game ends.

3️⃣ Level System

• Levels are simple math equations: addition, subtraction, multiplication.

• Each level has:

  • Correct answer cube

  • Several wrong answer cubes

  • 3 floating coins randomly positioned

• Cubes are shuffled horizontally across the screen.

4️⃣ Assets 

• Player: Idle and jump animations, currently using PNG sprite sheets.

• Backgrounds:

  • Sky (sky.png) – back layer

  • Far ground (far_ground.png) – second layer

  • Clouds (clouds.png) – first layer

• Ground tiles: platform1.png

• Coins: Procedurally drawn ellipses if image missing

• Particles: Procedurally drawn circles

Known issues:

• Player jump is fixed; variable jump height is partially implemented but not finalized.

• Some assets may need resizing and alignment fixes for smooth visuals.

• Walking sfx is not final.

5️⃣ Score / Combo System

• Correct answer: SCORE_CORRECT = 10 × combo multiplier

• Wrong answer: SCORE_WRONG = -5

• Coin: SCORE_COIN = 5

• Combo: Resets after 3 seconds of no correct hits.

6️⃣ Controls

7️⃣ Current Build / Code Status

• Fully functional game loop and level progression.

• Player, cubes, coins, floating text, and particles all implemented.

• Background layering system coded but asset loading fails.

• HUD and overlays for level intro, win, and game over implemented.

• Variable jump and parallax backgrounds in progress.