Files

Kay Kayyali 36262a6174 Initial commit: GDD, implementation plan, reviews, diagrams, assets

2026-05-23 05:27:58 +00:00

20 KiB

Raw Permalink Blame History

IRON REQUIEM: GAME DESIGN DOCUMENT

"The engine screams, the tracks grind, and the horizon is a wall of white silence. We are not retreating from the Soviets. We are retreating from a ghost of a future that should not exist." — Hauptmann Erich Voss

1. EXECUTIVE SUMMARY

Iron Requiem is a grim, oppressive 2D top-down pixel-art "tank bullet hell." Players pilot a lone Panzer IV through a frozen, alternate-history 1944 Russia. The gameplay focuses on the claustrophobic experience of tank warfare, where the vehicle is not just a tool, but the player's entire world.

Engine & Rendering: Framework: Phaser 3 (JavaScript, 2D Canvas only). NOT Babylon.js, NOT Three.js, NOT any 3D engine.

The game blends high-stakes resource management (fuel, heat, ammo) with the precise movement and dodging of the bullet-hell genre. The psychological tension scales from the suffocating interior of a "buttoned-up" tank to the terrifying vulnerability of "unbuttoning" to see the enemy.

Core Hook: The "Tank-as-Character" experience. The player manages a complex machine—fighting inertia, overheating engines, and crew panic—while navigating dense, choreographed patterns of Cold War-era Chinese weaponry.

2. STORY TREATMENT

2.1 Premise

Hauptmann Erich Voss and the remnants of the 6th Panzer Division were retreating through the frozen wastes of northern Russia in late 1944. Under the influence of a sudden, catastrophic temporal fracture, the division was displaced across geography and time. They now find themselves cut off and hunted in a landscape that no longer matches any known map. Their enemy is not the Red Army, but a displaced, alternate-reality People's Liberation Army from the Cold War era. Voss is fighting a desperate retreat against enemies who possess technology that contradicts the laws of his time.

2.2 3-Act Structure

Act I: The White Silence. Voss awakens to a shattered command structure. The first encounters are skirmishes with infantry and light armor. The horror is atmospheric—ghostly radio transmissions and the realization that the maps no longer match the terrain.
Act II: The Iron Corridor. The retreat leads through abandoned Soviet industrial hubs. The enemies evolve into Type 59 and Type 62 tanks. The scale of the invasion becomes clear; the landscape is littered with the wreckage of both German and Soviet forces, all crushed by the same anachronistic invader.
Act III: The Ruins of the Old World. The final push toward a captured European city. The atmosphere shifts from frozen waste to urban nightmare. A final confrontation occurs with the high command of the invading force, revealing the nature of the temporal fracture.

2.3 Bleak Endings

The Eternal Retreat: Voss survives the combat but runs out of fuel in the tundra. The game ends with a slow fade to white as the crew freezes in silence.
The Last Transmission: Voss manages to send a final, distorted signal back to a dying Germany, only to realize the response he receives is from a world that has already forgotten him.
The Iron Grave: A pyrrhic victory. Voss destroys the enemy commander but is immobilized. He chooses to overload the engine, taking the enemy and himself in a final, blinding explosion.
The Silent Witness: Voss survives and reaches the city, only to find it empty—a ghost city where the invaders have already moved on to the next continent.

3. CORE MECHANICS

3.1 Tank-as-Character (The Machine)

Unlike standard bullet-hell ships, the Panzer IV has significant mass.

Hull/Turret Decoupling: The hull moves independently of the turret. The player must manage the momentum of the 25-ton chassis while rotating the turret to face threats.
Inertia & Momentum: Acceleration is gradual; braking takes time. The tank "drifts" slightly on ice and snow.
Limited Visibility: The player's view is constrained by the tank's physical structure and the periscope mask.
Historical Specs: Panzer IV Ausf H, 25 tonnes combat loaded, 7.5 cm KwK 40 L/48 (long-barreled high-velocity anti-tank gun — NOT a short gun), Maybach HL 120 TRM 300 PS engine, crew of 5, ~87 rounds capacity. Real turret traverse: 26°/sec (electric) or 1.9°/sec (manual hand-crank).

3.2 Bullet Hell Patterns

Combat is a dance of survival against overwhelming firepower.

Infantry Walls: Densely packed waves of infantry that fire coordinated bursts of small arms and RPGs.
Artillery Rings: Large circular markers appear on the ground; after 2 seconds, a radial explosion occurs, forcing the player to move immediately.
Tank Destroyer Beams: High-velocity, linear projectiles from focused enemy armor that require precise "pixel-perfect" dodging.

3.3 Resource Management

The tank is a ticking clock of depletion.

Fuel: Constantly consumed. Low fuel reduces acceleration and turret rotation speed.
Ammo Types:
- APCBC (Pzgr 39): High penetration for enemy tanks. Standard anti-tank round. 6.8 kg, 750 m/s, 87 rounds max typical load.
- APCR (Pzgr 40): Tungsten-cored, rare. Higher penetration (930 m/s) but extremely limited supply — 5-8 rounds per run.
- HE (Sprgr 34): Splash damage for infantry clusters. 5.74 kg, 550 m/s.
- HEAT (Gr.Patr. 38 HL): Shaped charge, useful when AP is scarce or at extreme range. 450 m/s.
Secondary Weapons: Nahverteidigungswaffe (close-defense smoke launcher, limited charges) for breaking line-of-sight. Bow MG-34 (infinite ammo, low damage, forward arc only).
Scavenging: Players must exit the tank (high risk) or use crew members to recover fuel and shells from wreckage during brief lulls.

3.4 The Heat & Freeze-Thaw Cycle

Engine Temperature: High speeds and prolonged combat increase heat. Overheating causes speed penalties and increases the tank's thermal signature, making it easier for enemies to track.
Freeze-Thaw: In extreme cold, the engine can stall. The player must balance heat generation with the risk of thermal detection.

3.5 Crew Morale — Buff System

The crew is not a liability — they are your greatest asset, and morale is a resource to cultivate.

Baseline (0-100 scale): Fresh crew starts at 50. There are NO penalties at any morale level. Low morale (<30) adds atmospheric effects (vignette, muffled audio, tense crew barks) but never steals control.
High Morale Buffs (70+): Faster reload speed, crew warning shouts ("Enemy on your left!"), subtle reticle assist. These are rewards for keeping the crew alive and effective, not crutches.
Stress Factors: Taking hull damage (-5), crew injury (-15), long isolation without radio contact.
Recovery: +2 points/second when no damage taken. Iron Ledger entries during downtime provide a morale boost. Zone survival grants +20 one-time bonus.
Quantified: Scale 0-100. Buffs at >70. Atmospheric effects at <30. Never punitive. No "panic over-rotation" RNG.

3.6 Fog of War & Radio

Ghost Transmissions: The radio picks up fragments of historical broadcasts and distorted screams from the alternate timeline.
Interception: Players can tune the radio to intercept enemy commands, providing early warning of incoming bullet patterns.

4. SHOWCASE MECHANICS

4.1 The Unbuttoning (Hatch Mechanic) — Graduated Risk

The player toggles the tank's hatch between two states. This is the most frequent physical interaction with the tank — a contextual decision, not a binary gamble.

Buttoned Up: Hatch closed. Safe from snipers and shrapnel. Vision restricted to the periscope mask (180° forward arc, ~200px range). Muffled, claustrophobic audio.
Unbuttoned: Hatch open. Commander (Voss) exposed. Vision expands (270° arc, ~350px range). Earlier enemy detection, terrain hazard visibility. Open-world ambient audio.
Suppression (hit while unbuttoned): Hatch forced closed, morale penalty (-20), commander cooldown (10 seconds before unbuttoning again). NOT instant death.
Sniper Death: Death occurs ONLY from a direct Line-of-Sight Sniper shot — distinct laser sight telegraph, 2-second charge-up, crew bark ("Sniper! Get down!"). Skilled players can react and button up in time.
Visual: Animated pixel art hatch opening/closing, tiny commander head sprite when unbuttoned. Animated open/close cycles with key poses.
Audio: Ambient soundscape shifts — exterior wind/engine roar when unbuttoned; muffled interior drone when sealed. Sniper detection audio cue.

4.2 Side-View Cutscenes

Narrative is delivered via diegetic side-view profiles of the Panzer IV.

Visuals: Pixel art side-view with character portraits.
Function: Used between zones and after boss fights to show crew interactions, Voss's exhaustion, and the gradual decay of the tank's exterior.

4.3 The Last Transmission

A recurring mechanic where the player attempts to tune a radio to a specific frequency. Success reveals fragments of the plot; failure attracts enemy signal-trackers.

4.4 The Iron Ledger

A log of the crew's experiences. Writing in the ledger during downtime stabilizes morale and unlocks deeper character backstories.

4.5 Parasite Run

The ability to "leech" fuel or ammo from a disabled enemy tank, requiring the player to remain stationary and vulnerable for several seconds.

5. ENEMY ROSTER

Type 59 (Heavy Opponent): Main battle tanks. They heavily outclass the Panzer IV in armor and gun power. Victory requires ambush and flanking.
Type 62 (Fast Flankers): Light, agile tanks that attempt to get behind the Panzer IV to hit the thinner rear armor.
Artillery Emplacements: Static enemies that create the "Artillery Ring" patterns.
Helicopter Gunships: Aerial threats that introduce verticality to the bullet hell, raining down rockets in sweeping arcs.
Named Commanders: Bosses with unique dialogue in Mandarin and specialized bullet patterns that reflect their personality (e.g., "The Architect" uses geometric, oppressive grids).

6. PROGRESSION & WORLD

6.1 Zones

The Frozen Tundra: White-out conditions, deep snow slowing movement, sparse cover.
Abandoned Soviet Industrial: Rust-streaked metal, narrow corridors, combat in factories and warehouses.
Captured European City Ruins: Gothic architecture interspersed with futuristic Chinese fortifications.

6.2 Upgrades

Armor Plating: Increases hull HP and reduces morale loss from hits.
Engine Tuning: Reduces overheat rate and increases top speed.
Optics: Improves the periscope mask visibility range.
Crew Training: Permanent buffs to reload speed and panic resistance.

7. ART & SOUND DIRECTION

7.1 Pixel Art

Aesthetic: Gritty, weathered, and oppressive. Avoid "clean" pixel art.
Palette: 10-color bleak palette (Winter Whites, Steel Blues, Deep Greys, Dark German Grey).
Accents: High-contrast Orange for muzzle flashes and Red/Gold for Chinese markings.
Visual Cues: Animated hatch opening, screen-shake on shell impact, and a "dirty" lens effect for the periscope.

7.2 Sound Design

Atmosphere: A constant, low-frequency engine drone.
Audio Telegraphs: Distinct PLA bugles and whistles signal the start of bullet patterns 1.5s in advance.
Voice: German crew barks (subtitled) for urgent status updates; distorted Mandarin chatter over the radio.
Music: A blend of dark ambient industrial and mourning orchestral pieces.

8. TECHNICAL SPECIFICATION (PHASER 3)

ENGINE LOCK: Phaser 3 (JavaScript, 2D Canvas). NOT Babylon.js, NOT Three.js, NOT any 3D engine. This is a 2D pixel-art game — no 3D rendering pipeline, no WebGPU, no WebGL unless needed as a CANVAS fallback for performance.

Resolution: 640x360 (Integer scale to 1280x720 / 1920x1080).
Rendering: CANVAS mode default for crisp pixel edges. Fallback to WEBGL with roundPixels: true and nearest-neighbor filtering if CANVAS performance degrades with mask + bullet patterns.
Physics: Linear acceleration model (accel = (input × power) - (velocity × friction)) for the "25-ton" feel; Phaser.Math.Angle.RotateTo for turret rotation cap (15°/sec).
Hull/Turret Architecture: Hull = Arcade.Sprite with physics body. Turret = Arcade.Sprite positioned at hull center each frame, body disabled (rotation only). Hull collision = AABB (acceptable for top-down bullet hell).
UI: Diegetic HUD. Gauges for fuel and heat are analog needle sprites; ammo is tracked via shell sprites.
Vulnerability: The CommanderHatch hit-box is only active when the tank is "Unbuttoned."
Save System: IndexedDB for ghost crew data, run stats, and settings (3 save slots). Client-side only — no server storage. Assets hosted on server, all player data lives on their machine.

9. EDGE CASES & DESIGN RESOLUTIONS

These are definitive game design decisions. No mechanic is left to "the developer will figure it out."

9.1 Zero Fuel

The tank enters Last Stand mode: hull immobile, turret rotation at 50% speed (hand-cranked, ~1.9°/sec historically accurate). Crew barks reflect desperation. Player can still fight but cannot dodge — a dramatic moment, not a softlock. Emergency fuel reserve consumable (1 per run). "Prime the engine" desperation action: spend hull HP for one last-ditch burst of movement.

9.2 Crew Death

Driver dead: No hull movement.
Gunner dead: No turret rotation.
Loader dead: No firing.
Radio operator dead: No radio / early warning.
Commander death while unbuttoned: Instant game over (unchanged).
Commander death while buttoned: (Rare — requires armor penetration + precise hit) Bleak cutscene of remaining crew attempting retreat.
Role reassignment: Surviving crew can fill empty roles at 50% effectiveness (e.g., commander loads = 50% reload speed).

9.3 Zero Ammo (All Types)

Tank becomes a battering ram: can still move and ram enemy infantry for low damage. Crew can fire personal weapons (pistols) from the hatch — minimal damage, infinite ammo, but requires unbuttoning. Warnings: flash at <10 rounds total, <5 rounds, and at 0 with "FIND AMMO" prompt.

9.4 Scavenging

Post-combat only. After clearing a wave, debris fields become interactive zones. 3-second hold-E action with resource display. Use crew member keys — crew portrait greys out for 10 seconds while scavenging; if hit during that window, crew member is injured/killed. Guaranteed minimum yield per zone. Exit is always reachable with minimum starting fuel — softlock impossible by design.

9.5 Overlapping Bullet Hell Patterns

Pattern governor: Max N active patterns by difficulty — Zone 1: max 2, Zone 2: max 3, Zone 3: max 4. Offset timing by ≥0.5s between overlapping patterns. Every pattern has a provable safe zone — tank hitbox must fit within the gap. Procedural validation script tests all pattern combinations for dodgeability.

9.6 Periscope Mask Fairness

Enemies outside the periscope view do not fire — or fire with dramatically reduced accuracy (slow, telegraphed suppressing fire). Crew barks indicate off-screen threat direction ("Contact! 4 o'clock!"). Projectile telegraphs (Artillery Ring markers, beam charge-up glows) always visible even when firing enemy is off-screen. Radar ping: periodic sweep shows enemy positions as dots on minimap.

9.7 Save System Failure Modes

Browser clears data: Export/import save as JSON file. Warning on first launch.
Private/incognito mode: Detect and warn at main menu.
Storage quota exceeded: Catch error, alert player, offer to delete old saves.
Save corruption: Write to temp key, atomic rename, checksum validation on load.
Multi-tab: Session-scoped lock token — only active tab saves.
Auto-save: At every checkpoint (zone transition, boss defeated) + manual save option.
3 save slots for different runs/endings. Save format: IndexedDB, schema versioned, including zone, resources, crew state, story flags, settings, playtime stats.

9.8 Tutorial (Zone 1)

Zone 1 is the tutorial zone. Systems introduced progressively:

Start buttoned — hull movement only.
Add turret rotation + 2-3 static infantry targets.
Introduce unbuttoning (and risk) against a single enemy at range.
Ammo types introduced as they're acquired.
Heat, morale, radio introduced with on-screen prompts as they become relevant. No system dumps. The player learns each mechanic before the next is added.

9.9 Difficulty Modes

Endurance Mode (Easy): Slower heat buildup, more forgiving morale, wider periscope view, 1 extra crew "life," reduced enemy projectile density.
Requiem Mode (Normal): As described in this GDD.
Iron Mode (Hard): Graduated unbuttoning death (as below), no auto-save, permadeath (one save slot, deleted on death).

9.10 Quality of Life

Pause menu: Resume, Save, Load, Settings, Quit to Menu. Auto-pause on browser tab blur.
Controller support: Twin-stick (left = move hull, right = aim turret). Keyboard: WASD + arrow keys or mouse aim.
Key rebinding: Full rebinding for all actions.
Sound settings: Master, Music, SFX, Radio, Voice volume sliders.
Accessibility: Color blind options, screen shake toggle, flashing light warnings.
Death screen: Reload checkpoint or restart zone. Death recap. Clear distinction: runs are checkpoint-based (not permadeath) in Endurance/Requiem modes.

APPENDIX A: DESIGN PHILOSOPHY — WHAT CHANGED AFTER REVIEW

A.1 Morale: Buff System, Not Debuff

Before: Morale penalties made the tank feel unresponsive (slower reload, command delay, panic over-rotation). After: Morale is a buff system. Baseline = normal (no penalties). High morale = faster reload, crew warning shouts ("Enemy on your left!"), reticle assist. Morale starts low and builds through survival, scavenging, and Iron Ledger entries. Recovery rate: +2 points/second with no damage taken. Maximum 100. Buffs activate at >70. Low morale (<30) adds visual/audio effects (vignette, muffled sound) but never steals control. Removed: "Turret over-rotation" panic errors — frustrating RNG has no place in a precision game.

A.2 Unbuttoning: Graduated Risk, Not Binary Death

Before: Any projectile hitting the CommanderHatch = Game Over. Russian roulette. After: Hit while unbuttoned = Suppression: hatch forced closed, morale penalty (-20), commander cooldown (10 seconds before unbuttoning again). Death occurs ONLY from a direct Line-of-Sight Sniper shot (distinct laser sight telegraph, 2-second charge-up). Skilled players can react and button up. Audio cue: "Sniper! Get down!" crew bark.

A.3 Historical Corrections

Gun: "Short 75mm KwK 40" corrected to 7.5 cm KwK 40 L/48 (long barrel). The KwK 40 was ALWAYS a long-barreled high-velocity anti-tank gun. The short-barreled 75mm was the KwK 37 L/24 (infantry support howitzer, phased out by 1943).
Ammo types: "Smoke" and "Canister" rounds did not exist for the 75mm KwK 40. These are replaced by: APCBC (Pzgr 39), APCR (Pzgr 40, rare/limited), HE (Sprgr 34), and HEAT (Gr.Patr. 38 HL). Smoke is now delivered via the real-world Nahverteidigungswaffe (close-defense launcher) with limited charges. Canister is replaced by the bow MG-34 (infinite but low damage, forward arc only).
Division history: The 6th Panzer Division never operated in Arctic Russia — they were in Hungary in 1944 under Army Group South. This is now explained in-universe as part of the alternate-history "Temporal Fracture" event that displaced both the Chinese forces AND Voss's unit.

20 KiB Raw Permalink Blame History Unescape Escape