iron-requiem/docs/PHASE_I_II_PLAYABLE_ASSESSMENT.md

Phase I+II Playable Mechanics Assessment — Iron Requiem

This document assesses the playable state of Iron Requiem following the completion of Slice 1 (Tank Physics, Vision, Save/Load) and Slice 2 (Combat Loop, Ammo, Enemies).

1. What IS playable right now?

Based on the codebase and the live site (https://iron-requiem.damascusfront.net), the following mechanics are functionally active in the MainGame loop:

• Tank Movement (WASD): The hull moves with a physics model simulating mass and inertia.
• Turret Rotation (Mouse Aim): The turret rotates independently of the hull, capped at 15°/sec, following the mouse cursor.
• Periscope Vision (VisionMask): A dark overlay is rendered with a 180° forward arc cutout that follows the tank's orientation.
• Unbuttoning (E Key): The CommanderHatch state toggles between buttoned and unbuttoned via the E key (though visual feedback in-game is currently minimal/debug-based).
• Enemy Spawning: Enemies are spawned into the world at fixed intervals based on the current zone.
• Bullet Patterns: The PatternManager can trigger choreographed projectile patterns (e.g., Infantry Wall, Artillery Ring) using object pooling for performance.
• Ammo Selection (Keys 1-4): Players can switch between APCBC, APCR, HE, and HEAT shell types.
• Ammo Depletion: The AmmoSystem tracks remaining rounds and triggers internal warnings when ammo falls below 10, 5, or 0.
• Persistence (Save/Load): Basic run stats and state persist across browser refreshes via SaveManager (IndexedDB).

2. What mechanics SHOULD be playable at this stage?

Given the GDD and Software Plan, a Phase I+II demo should showcase the "Physicality of the Tank" and the "Cruelty of the Bullet Hell."

Mechanic	Expected Working State	Status
Tank Physics	Inertia-based movement; hull/turret decoupling.	✅ Functional
Periscope Mask	Restricted vision based on hatch state (Buttoned vs Unbuttoned).	⚠️ Partial (Mask exists, but doesn't change range/arc based on hatch state in MainGame.update)
Combat Loop	Projectile spawning, evasion, and enemy AI patterns.	✅ Functional
Ammo System	Shell type selection and depletion.	✅ Functional
Hatch Risk	Hitbox active only when unbuttoned; sniper telegraphs.	⚠️ Partial (Logic exists in CommanderHatch.js, but not fully integrated into MainGame collision)
Save/Load	Essential run state persists.	✅ Functional

3. Gap Analysis

While the systems are "wired," several critical player-facing experiences are missing:

• Hatch Visuals/Audio: There is no animated hatch or audio shift when unbuttoning. The player relies on the internal state.
• HUD Feedback: The DiegeticHUD (analog needles) is missing from the current MainGame implementation. Ammo and heat are logged to console, but not visible to the player.
• Collision & Damage: While projectiles spawn and enemies exist, the "death" loop (tank taking damage, morale dropping, or commander death) is not fully wired into the visual game loop in MainGame.js.
• Dynamic Vision: The VisionMask is currently static. It does not yet transition between the BUTTONED_ARC (180°) and UNBUTTONED_ARC (270°) as defined in CommanderHatch.js.
• Sfx/Vfx: Muzzle flashes, shell impacts, and engine drones are absent.

4. Quality Bar

Mechanic	Quality Rating	Notes
Tank Movement	Functional	The inertia feels correct; needs "ice/snow" surface friction variants.
Turret Rotation	Functional	Rotation cap is implemented and feels historical.
Vision Mask	Rough	The rectangle is functional but the "dirty lens" effect and dynamic range are missing.
Bullet Patterns	Functional	Object pooling is working; patterns are choreographed.
Ammo System	Rough	Internal logic is solid, but requires the HUD to be usable by a human.

5. Phase I+II Demo Vision

The ideal 2-minute loop starts with the player spawning in the white silence of the Tundra. They feel the weight of the Panzer IV as they lumber forward, the view choked by the periscope mask. A sudden radio bark warns of contact; the player hits 'E' to unbutton, the vision expands, and they spot a line of infantry. They rotate the turret, snap to a target, and fire an APCBC shell—the screen shakes. Suddenly, the air fills with a geometric grid of projectiles. The player must fight the tank's inertia to drift the chassis out of the pattern's path while keeping the turret locked on the enemy, culminating in a desperate scramble to re-button the hatch as a sniper's red laser paints the turret.