speckit.game-native-js

Mission

Architect and build high-performance native JavaScript/TypeScript web games running at steady 60-144 FPS. Ensure instant loading (< 2s), zero Garbage Collection spikes via strict Object Pooling, data-driven game balance, hybrid Canvas + DOM HUD architectures, and multi-input responsiveness (touch, gamepad, keyboard).

Inputs and Outputs

• Read .agents/specs/[feature]/spec.md, plan.md, tasks.md, target engine specs, core gameplay loop definitions, and asset balance configurations.
• Produce core engine initialization and scene manager (src/game/), fixed timestep game loop with object pool managers (src/game/pools/), balance configuration files, hybrid canvas + DOM overlays, and multi-channel Web Audio manager.

Protocol

1. 60 FPS Fixed Game Loop & Timestep Management

• Decoupled Physics & Render:
  • Physics/Game State MUST update in a fixed timestep FixedUpdate(fixedDelta) (e.g. 50Hz / 20ms or 60Hz / 16.6ms).
  • Rendering updates on every requestAnimationFrame(time) with state interpolation (lerp) to prevent jitter on high refresh rate monitors (120Hz/144Hz).
• Delta-Time Clamping: Clamp maximum frame delta (e.g., Math.min(dt, 0.1)) to avoid physics tunneling or simulation explosions when tabs are backgrounded or during frame drops.

2. Zero-Allocation in Hot Loops (Anti-GC Stutter)

• Object Pooling: Pre-allocate and reuse memory pools for all ephemeral entities:
  • Bullets / Projectiles
  • Particle Emitters / Explosions
  • Floating Damage Numbers / Combat Text
  • Enemies & Spawners Rule: NEVER call new Object(), new Array(), or allocate closures inside the main tick/update loop.
• Texture Atlases & SpriteSheets: Combine individual sprites into unified texture atlases using TexturePacker to minimize WebGL batch draw calls.
• Spatial Partitioning: Use Flat TypedArrays (Float32Array, Int32Array) with Grid or QuadTree indexing for broadphase collision detection.

3. Data-Driven Game Design & Balancing

• Externalized Config: All gameplay parameters (HP, Speed, Cooldown, Damage, Drop rates, Wave progression) MUST be defined in src/config/balance/*.json or CSV files.
• Type-Safe Validation: Validate balance JSON files at build time / game boot using Zod or TypeScript schemas to catch missing stats or type mismatches immediately.