iron-requiem/PHASER_IMPLEMENTATION_PLAN.md

Iron Requiem — Phaser.io Implementation Plan

1. Technical Architecture

• Framework: Phaser 3 (JS/TS)
• Internal Resolution: 640x360 (Pixel-perfect integer scaling to 1280x720 / 1920x1080)
• Rendering: Phaser.CANVAS or Phaser.WEBGL (with pixelArt: true and roundPixels: true) to preserve pixel-art crispness.

2. Core Systems Specification

2.1 Physics: The "25-Ton" Feel

• Hull Movement: Implementation of a linear acceleration model to simulate inertia.
  • accel = (input * power) - (velocity * friction)
• Turret Rotation: Capped rotation speed (15°/sec) using Phaser.Math.Angle.RotateTo.
• Constraints: Hull and Turret are separate entities; the Turret is anchored to the Hull's center.

2.2 Vision: The Periscope Mask

• The Mask: A full-screen Graphics layer with a rectangular hole.
• Unbuttoning: An E key toggle that slides the mask off-screen.
• Death State: While "Unbuttoned", the CommanderHatch hit-box is active. Any single projectile hit = Game Over.

2.3 Combat: Bullet Hell Logic

• Pooling: Phaser.Physics.Arcade.Group for all projectiles to avoid GC spikes.
• Patterns:
  • Horizontal Walls: Coordinated emitter arrays synchronized via a PatternManager class.
  • Artillery Rings: Phaser.Geom.Circle markers → 2s delay → radial explosion.
• Audio Telegraphs: Bugle/Whistle sounds triggered 1.5s prior to pattern start.

2.4 UI: Diegetic HUD

• Instruments: All UI elements are sprites located in the "interior" layer.
• Needle Gauges: Rotational logic for Fuel and Temperature needles.
• Ammo Tracker: Shell-sprite replacement (Full \rightarrow Spent).

3. Development Roadmap

Sprint 1: Prototype 0 (The Machine)

• Implement hull acceleration/friction.
• Implement turret rotation lag.
• Basic tank sprite integration.

Sprint 2: Prototype 1 (The Vision)

• Create the periscope mask overlay.
• Implement the "Unbutton" transition (Tween).
• Add "Unbuttoned" vulnerability hit-box.

Sprint 3: Prototype 2 (The Hell)

• Create PatternManager for bullet pools.
• Implement "Infantry Wall" pattern.
• Implement "Artillery Ring" telegraphs and impacts.

Sprint 4: Prototype 3 (The Interface)

• Link engineTemp and fuel variables to analog needle sprites.
• Implement ammo selection (1-4) and sprite-based count.
• Add radio scanning visual/audio loop.