kgames

fire_truck_plan.md (11058B)

---

 # Fire Truck Implementation Plan
 
 ## Goal
 
 Implement a new `fire-truck` game from a clean slate as a simple top-down Phaser game for young kids.
 
 The first shipped version should support:
 
 1. Loading from the portal as a live game.
 2. Rendering a top-down city with roads and placeholder buildings.
 3. Automatically driving a fire truck along streets.
 4. Prompting the player at intersections to press the correct arrow key:
    - left arrow = turn left
    - up arrow = go straight
    - right arrow = turn right
 5. Stopping the truck on wrong or late input.
 6. Playing a fail sound and showing a clear visual warning on failure.
 7. Resuming once the correct arrow is pressed.
 8. Continuing indefinitely through newly generated turns and intersections.
 
 Out of scope for this phase:
 
 - Fires, destinations, scoring, timers, lives
 - Traffic, pedestrians, collisions
 - Detailed art assets
 - Complex audio/music systems
 - Multiple levels or difficulty settings
 
 ## Repo Constraints
 
 Follow existing project conventions:
 
 1. Static HTML, CSS, and JavaScript only.
 2. No build tooling.
 3. Phaser loaded from CDN.
 4. Optional audio via Web Audio API or Tone.js loaded from CDN.
 5. No external image assets. Use Phaser graphics / generated textures only.
 6. Browser tests expect `preserveDrawingBuffer: true`.
 7. No `console.log` in production code.
 8. Expose `window.__FT_SCENE__ = this` in `create()` for browser test inspection.
 
 ## Current State
 
 The repository currently has stale fire-truck tests referencing an older pseudo-3D implementation:
 
 - `tests/unit/route.test.js`
 - `tests/unit/projection.test.js`
 - fire-truck-specific cases in `tests/browser/runner.js`
 
 The `games/fire-truck/` directory does not currently exist.
 
 The portal already has a placeholder tile for `fire-truck` in `js/main.js`, but it is marked `coming-soon`.
 
 This implementation should treat the game as a fresh top-down design and replace all outdated fire-truck assumptions.
 
 ## Deliverables
 
 Create or update these files:
 
 1. `games/fire-truck/index.html`
 2. `games/fire-truck/lib.js`
 3. `games/fire-truck/game.js`
 4. `js/main.js`
 5. `tests/unit/route.test.js`
 6. `tests/unit/projection.test.js`
 7. `tests/browser/runner.js`
 
 ## High-Level Architecture
 
 Split the implementation into two layers:
 
 1. Pure logic in `lib.js`
 2. Phaser scene and rendering in `game.js`
 
 ### `lib.js` responsibilities
 
 `lib.js` should contain all pure, deterministic logic that can be unit tested in Node without Phaser.
 
 Keep it small and focused on:
 
 1. Road network generation
 2. Intersection classification
 3. Move legality
 4. Heading transitions
 5. Prompt selection
 6. Path extension for infinite driving
 
 ### `game.js` responsibilities
 
 `game.js` should contain:
 
 1. Phaser scene setup
 2. World generation bootstrapping
 3. Rendering of roads, buildings, and truck
 4. Camera follow behavior
 5. Automatic movement
 6. Intersection detection
 7. Prompt UI
 8. Input handling
 9. Failure/recovery behavior
 10. Minimal SFX
 11. Debug state exposure for browser tests
 
 ## Core Design Decisions
 
 ### 1. World representation
 
 Use a grid-based city.
 
 Each cell should be one of:
 
 1. road cell
 2. building cell
 
 Road cells should store exits in cardinal directions:
 
 - `N`
 - `E`
 - `S`
 - `W`
 
 A road cell can therefore represent:
 
 1. straight
 2. corner
 3. T intersection
 4. four-way intersection
 
 This keeps generation and movement simple and testable.
 
 ### 2. Truck movement model
 
 The truck should move automatically from cell center to cell center along the road network.
 
 Use a heading enum:
 
 - `north`
 - `east`
 - `south`
 - `west`
 
 The truck should always be aligned to one heading and centered in its lane/path.
 
 Movement loop:
 
 1. truck moves along current road segment
 2. when nearing next intersection, prompt appears
 3. player must press correct arrow before reaching the center
 4. if correct, truck commits the move and continues
 5. if wrong or late, truck stops
 6. while stopped, only the correct key resumes movement
 
 ### 3. Prompt timing
 
 The correct key must be pressed before the truck reaches the center of the intersection.
 
 ### 4. Infinite play model
 
 Do not generate an infinite full map up front.
 
 Instead:
 
 1. generate an initial connected city chunk around the start
 2. track the route ahead
 3. extend the network / route ahead as needed
 
 The simplest reliable version is route-first generation with local filler roads/buildings around it.
 
 ## Recommended Implementation Strategy
 
 Implement in this order:
 
 1. Create the HTML shell.
 2. Implement pure logic functions in `lib.js`.
 3. Replace the old unit tests with tests for the new logic.
 4. Implement the Phaser scene in `game.js`.
 5. Update `js/main.js` so the portal tile is live.
 6. Replace old browser tests with new top-down gameplay tests.
 7. Run `npm test` and fix issues.
 
 ## Acceptance Criteria
 
 The feature is complete when all of the following are true:
 
 1. The `Fire Truck` tile on the portal is live and opens the game.
 2. The game loads without console or runtime errors.
 3. A top-down road/building city renders clearly.
 4. The truck starts driving automatically after load.
 5. A prompt appears before intersections.
 6. Left/right/up arrows correspond to left/right/straight.
 7. Wrong input stops the truck and shows fail feedback.
 8. Missing the prompt before the intersection center also stops the truck.
 9. Pressing the correct arrow while stopped resumes movement.
 10. The route continues indefinitely without obvious dead ends.
 11. The fire-truck unit tests reflect the new design, not the old pseudo-3D one.
 12. Browser smoke tests reflect the new top-down gameplay.
 13. `npm test` passes.
 
 ## Next Steps
 
 The first version is now implemented and passing tests. The next development pass should focus on feel and city quality rather than adding unrelated features.
 
 ### 1. Raise runtime frame rate and remove the low-FPS workaround path
 
 Current issue:
 
 - The scene currently includes extra wall-clock stepping to keep Playwright stable under headless throttling.
 - That keeps tests reliable, but it is a workaround rather than the ideal runtime architecture.
 - The visual update rate and motion smoothness should be improved in normal play.
 
 Goals:
 
 1. Keep gameplay smooth at interactive frame rates in the browser.
 2. Reduce dependence on duplicate movement stepping paths.
 3. Preserve browser test reliability without degrading real gameplay.
 
 Recommended work:
 
 1. Profile the current render/update path and simplify anything done every frame that can be precomputed.
 2. Keep static city drawing on cached graphics or render textures rather than redrawing dynamic content unnecessarily.
 3. Ensure only the truck, prompt UI, and transient effects are changing each frame.
 4. Revisit the Playwright compatibility path so test stability does not force a slower-feeling runtime.
 5. Prefer one canonical movement/update pipeline if possible, with test timing adapted around it rather than maintaining two divergent timing behaviors long-term.
 
 Acceptance criteria for this step:
 
 1. Motion looks smoother during normal play.
 2. Prompt timing remains correct.
 3. Browser tests still pass.
 4. No new console warnings or errors are introduced.
 
 ### 2. Make street grid generation much more connected and realistic
 
 Current issue:
 
 - The current generation is route-first with local side branches.
 - It is good enough for v1 gameplay, but it does not yet feel like a believable dense city.
 - Connectivity is limited and the road network is too obviously centered around the active route.
 
 Goals:
 
 1. Produce a city grid that feels more like real urban blocks.
 2. Increase cross-connectivity between nearby streets.
 3. Include many more plausible T intersections and 4-ways.
 4. Reduce the feeling of isolated decorative branches.
 
 Recommended generation direction:
 
 1. Start from a coarse block plan instead of only the truck route.
 2. Build a connected backbone of horizontal and vertical streets across a rectangular neighborhood.
 3. Add secondary streets that connect existing roads rather than ending as stubs.
 4. Use sparse omissions to create T intersections intentionally, instead of relying on ad hoc branch placement.
 5. Maintain short-to-medium block lengths so intersections occur often enough for the teaching loop.
 
 Recommended concrete algorithm changes:
 
 1. Generate several north-south avenues spanning the neighborhood.
 2. Generate several east-west streets spanning the neighborhood.
 3. Use probabilistic gaps at selected crossings to convert some full crossings into T intersections.
 4. Add short connector streets only when they join two existing streets or complete a block edge.
 5. Run a connectivity pass to ensure the playable component is highly connected.
 6. Keep the truck route embedded inside this broader street graph rather than serving as the primary source of roads.
 
 Recommended test additions for this step:
 
 1. Verify the generated road graph has a large connected component.
 2. Verify the graph contains both T intersections and 4-ways in realistic proportions.
 3. Verify the average road-cell degree is above a minimum threshold.
 4. Verify there are multiple alternate neighboring connections around the active route.
 
 Acceptance criteria for this step:
 
 1. The visible city looks denser and more grid-like.
 2. Roads feel mutually connected rather than decorative.
 3. The active route still supports infinite driving.
 4. Prompt opportunities remain frequent and readable.
 
 ### 3. Smooth turn animation instead of heading snap
 
 Current issue:
 
 - Heading changes are mechanically correct but visually abrupt.
 
 Goals:
 
 1. Make turns feel more natural.
 2. Preserve the simple teaching gameplay.
 
 Recommended work:
 
 1. Interpolate truck rotation during the intersection-to-exit transition.
 2. Optionally move along a short corner arc rather than a strict two-segment snap.
 3. Keep the implementation small; do not add full path spline complexity unless required.
 
 Acceptance criteria for this step:
 
 1. Left and right turns read clearly.
 2. Straight movement remains centered and stable.
 3. Prompt timing and fail timing do not regress.
 
 ### 4. Add positive feedback for correct input
 
 Current issue:
 
 - Failure is communicated clearly.
 - Success currently lacks an equally clear but gentle reward cue.
 
 Goals:
 
 1. Reinforce correct arrow input for young kids.
 2. Keep audio short and non-intrusive.
 
 Recommended work:
 
 1. Add a brief success chirp or two-note chime on correct input.
 2. Optionally add a small visual confirmation such as a soft flash or badge.
 3. Keep success feedback lighter than failure feedback so the screen stays calm.
 
 Acceptance criteria for this step:
 
 1. Correct input is immediately rewarding.
 2. Feedback does not obscure the next prompt.
 3. Audio still respects browser autoplay constraints.
 
 ### Recommended implementation order for the next pass
 
 1. Improve the street graph generator first.
 2. Rework runtime update/render flow for smoother frame rate.
 3. Add turn smoothing.
 4. Add success feedback.
 5. Update tests where necessary and rerun `npm test`.