# basic1 Lua Games Implementation Plan

## Overview
Build a collection of games for the basic1 homemade console, implementing them sequentially based on complexity and learning value.

## Game List & Priority

### Tier 1: Foundational (Start Here)
These teach core mechanics and are quick wins.

1. **Flappy Bird** ✅ DONE
   - Mechanics: Gravity, collision, scrolling obstacles
   - Complexity: Low
   - Time Estimate: 1-2 hours
   - Learning: Gravity physics, obstacle spawning, game states
   - API Usage: Circle/rect drawing, gravity math, simple event handling

2. **Breakout/Brick Breaker** ✅ DONE
   - Mechanics: Ball physics, paddle control, grid destruction
   - Complexity: Low-Medium
   - Time Estimate: 2-3 hours
   - Learning: Collision detection, grid management, ball reflection angles
   - API Usage: Rect grids, ball physics (similar to Pong), score tracking

3. **Simon Says** ✅ DONE
   - Mechanics: Color sequence memory, pattern growing
   - Complexity: Low
   - Time Estimate: 1-2 hours
   - Learning: State management, sequence arrays, timing
   - API Usage: Rect drawing, button input, frame timing

### Tier 2: Medium Difficulty (Build After Tier 1)
These combine mechanics and add complexity.

4. **Tetris** ✅ DONE
   - Mechanics: Falling pieces, rotation, line clearing, gravity
   - Complexity: Medium
   - Time Estimate: 4-5 hours
   - Learning: Grid-based movement, rotation matrices, collision
   - API Usage: Rect grid system, complex state tracking, rapid updates

5. **Asteroids** ✅ DONE
   - Mechanics: Spaceship control, rotation, projectiles, spawning
   - Complexity: Medium
   - Time Estimate: 3-4 hours
   - Learning: Vector math, object pooling, spawn waves
   - API Usage: Line drawing, rotation math, multiple entity management

### Tier 3: Advanced (Polish & Challenge)
These build on previous learnings.

6. **Memory/Matching Game** ✅ DONE
   - Mechanics: Tile flipping, pair matching, timer
   - Complexity: Medium
   - Time Estimate: 2-3 hours
   - Learning: Hidden state management, animations
   - API Usage: Grid layout, simple animations

7. **Air Hockey** ✅ DONE
   - Mechanics: 2-player, ball physics, faster pace than Pong
   - Complexity: Medium
   - Time Estimate: 2-3 hours
   - Learning: Improved physics, AI paddle (optional)
   - API Usage: Ball physics refinement, smooth controls

### Tier 4: Polish & Variants
Once core games work, extend with variants or features.

8. **2048** ✅ DONE
   - Mechanics: Grid merging, swipe logic, exponential growth
   - Complexity: Medium
   - Time Estimate: 3-4 hours
   - Learning: Swipe detection, grid animation, merge logic
   - API Usage: Grid rendering, touch gesture interpretation

9. **Tic-Tac-Toe** ✅ DONE
   - Mechanics: Grid selection, AI opponent (minimax)
   - Complexity: Low-Medium
   - Time Estimate: 2-3 hours
   - Learning: Game tree search, AI logic
   - API Usage: Grid UI, event handling, win detection

10. **Lunar Lander** ✅ DONE
    - Mechanics: Thrust, rotation, gravity, soft landing
    - Complexity: Medium-High
    - Time Estimate: 3-4 hours
    - Learning: Advanced physics, control feel
    - API Usage: Vector math, acceleration, fuel management

## Implementation Strategy

**Per Game:**
1. Write game file in `/Users/adolforeyna/Projects/basic1/games/lua_examples/`
2. Test locally if possible, or prepare for SD card deployment
3. Document key mechanics in comments
4. Update this plan with completion status
5. Save daily progress to `memory/YYYY-MM-DD.md`

**Patterns to Reuse:**
- State machine (MENU → PLAYING → GAME_OVER)
- `game.vars` for all state
- `game.set_frame_updates(true)` for animation
- Touch input handling (left/right screen halves for 2-player, center for single)

**Testing Checklist (per game):**
- [ ] Initializes without crashes
- [ ] Main gameplay loop works
- [ ] Input is responsive
- [ ] Collision detection accurate
- [ ] Score/state tracking correct
- [ ] Game over condition triggers
- [ ] Restart from menu works

## Notes

- Monochrome display = simple visuals, focus on mechanics
- Touch controls are the primary input
- Frame-based animation keeps things smooth
- Each game builds on previous learnings
- Start simple, layer complexity progressively

---

**Current Status:** All 10 games complete. Ready for SD card deployment.