Iron Litany — design and production foundation

Working title. October 5, 2026. Deliberate implementation plan, not a completion report.

This describes intended systems; only tested deliverables may later be marked implemented.

The first implementation follows work/simulation-contract.md; expand that contract explicitly rather than silently inventing API/state fields.

Source/style recovery is in work/reference-inventory.md; lore findings belong in the separate source research.

Current implemented revision, v0.3.0

INTERIOR_AND_INCURSIONS_V030.md records the implemented narrow hull, eleven local areas with staggered surveyed elevations, current-hall lighting, short direct outdoor cones, loaded-bearing service and frequent physical Chaos wounds. Small then larger manifestations require actual first-person aim; their sources need early binding, post-kill purification or a costly ammunition expedient. Existing crew, personal and signal duties continue independently. PLAYTHROUGH_V7.md distinguishes actual control evidence from the eight synthetic campaign experiments.

This implements part of the larger plan below. Authored crew art/contact, walkable religious refuges, space journeys, politics and final campaign expansion remain future work. New exact rites, creatures and custody rules are original campaign invention. The latest request deliberately relaxes the overhead eye/facing restriction for more continual slit context; first person keeps physical eye admission. The new mechanisms preserve the same tank body, live time, resource costs and fail states.

1. Promise and boundaries

• You inhabit a massive, ancient Imperial tank as its fourth crew member and ordained technical custodian.
• The commander drives and issues tactical orders; gunner traverses/aims/fires; loader handles ammunition; you preserve function, rite and purity.
• Your campaign warrant grants spiritual veto and machinery authority, including authority over the commander: make this local narrative premise explicit, not universal lore.
• The machine spirit is a priceless inherited charge. Crew survival matters, but sacrificing the vessel for one unreliable person is an unacceptable campaign outcome.
• The world is the grim darkness of the 41st millennium; researched canon, campaign interpretation and invented liturgy remain separately identified.
• Primary play is walking through a cutaway tank in an isometric-like overhead view; first person shares the same body, stations and time.
• First person reveals detail and enables close handling; it must never teleport the player or reset dangerous conditions.
• The intended experience is tactile, oppressive and sometimes rhythmically satisfying: earned routine can become catastrophe through understandable links.
• Correct procedure protects equipment but cannot solve every simultaneous demand within the available time and materials.
• Cleverness means diagnosis, route planning, sequencing, prevention, load management and acceptable risk—not unexplained button exploits.
• This is a playable foundation followed by a reviewed demo; neither is automatically a finished game.

2. Core loop and pacing

1. Read instruments, crew behavior, sound and partial outside evidence while moving through your habitual inspection route.

2. Distinguish normal operating strain, material fault, human misconduct and possible intrusion.

3. Choose a priority, reach the physical station, isolate danger if needed, and commit time/materials.

4. Perform a rite correctly, apply a temporary repair, issue a binding correction, or veto an unsafe order.

5. Observe the real response: pressure steadies, a shell seats, a crew member resumes work, a suspicious signal persists.

6. Reassess the opportunity cost: the tank kept moving and other systems continued to change during that intervention.

7. Reach a repair stop, document condition and crew, requisition scarce supplies, replace unsuitable people, then face a changed route.

• A healthy tank has a sustainable inspection rhythm; perfect uninterrupted maximum speed is not sustainable.
• Typical maintenance creates 8–20-second local tasks and 30–70-second planning horizons; tune after real play, not by assumption.
• Serious faults announce themselves before escalation through at least two accessible cues.
• A crisis has an actionable recovery window; it is not a random instant loss disguised as difficulty.
• Initial protected instruction prevents destructive accumulation while teaching one complete rite and one physical route.
• Normal difficulty then keeps simulation live during menus that represent in-world work; explicit Pause freezes it clearly.
• Inactivity/hidden tab pauses and saves safely. A suspended browser must not quietly destroy the tank.
• First playable campaign target: three approximately 150-second mission legs with a depot after each, including final report.
• Mission distance follows actual travel speed; halting buys working time while increasing exposure and consuming supplies.
• Longer campaign pacing remains planned until the short route is readable, repeatable and interesting.

3. Coupled simulation and physical causality

Use a seeded fixed-step simulation, independent of frame rate, DOM, renderer and sound.

Foundation UI values are normalized 0–100; later calibrated units may be introduced without pretending these are engineering predictions.

Define clamp, explicit thresholds, bounded coefficients and event cooldowns; test zero/invalid/extreme inputs.

For expansion equations, u is throttle, v speed, T heat, p pressure, P available power, H hull integrity and dt timestep.

drawbar_force = engine_torque * gear_ratio * drivetrain_efficiency / sprocket_radius
traction_limit = ground_grip * supported_weight
drive_force = min(drawbar_force, traction_limit)
resistance = rolling_drag(terrain) + mud_sinkage + slope_load + track_damage_drag
dv/dt = (drive_force - resistance) / effective_mass
slip = max(0, requested_drive_force - traction_limit) / max(traction_limit, epsilon)
dT/dt = engine_load + slip_heat + firing_heat + friction_heat - coolant_heat_removal
dp/dt = pump_flow - useful_flow - leak_flow - relief_flow
P_available = generation(engine_health, rpm) - pump_load - traverse_load - auxiliary_load
reload_time = base_reload * fatigue_factor * breech_friction * discipline_factor
aim_error = recoil_recovery + terrain_motion + traverse_fault + gunner_condition
dH/dt = -(incoming_impact + overpressure_damage + heat_damage + internal_fire)

• Do not implement all equations at once; the foundation contract represents their gameplay effects with heat, pressure, power, speed and health.
• Add explicit coolant volume, fuel, slope, slip and ammo temperature only when their readings and interventions are visible.
• Mechanical damage persists until repaired; chanting alone does not refill coolant or replace a broken coupling.
• Rite quality influences cooperation/reliability and contamination resistance; physical action handles real material needs.
• A temporary bypass changes a named tradeoff: restored circulation now, increased leak probability or spirit debt later.
• Recoil is a brief state impulse affecting sight alignment, unsecured tools, traverse stability and nearby physical presentation.
• Ground impacts are coherent with outside scenery and motion; avoid camera shake disconnected from simulation.
• Damage propagation is thresholded with hysteresis so the system does not chatter repeatedly at one boundary.

Mud / gradient -> engine load -> heat -> coolant demand -> pressure / power strain
Low coolant health -> inadequate cooling -> engine wear -> reduced generation
Reduced power -> slow traverse / pump starvation -> poor firing window / further heat
Breech friction + tired loader -> longer reload -> threat survives -> more incoming impacts
Impact -> leak / damaged seal -> pressure loss + exposed intrusion route
Uncorrected breach -> repeated misconduct -> weakened warding -> localized contamination
Hidden intrusion -> misleading reading / harmful order -> wrong repair -> further damage
Player taint -> tempting shortcuts / suspect interpretation -> verification burden
Correct diagnosis + controlled speed + preventive route -> fewer simultaneous emergencies

4. Religious work as embodied procedure

• Every rite identifies a purpose, precondition, ordered steps, duration, cost, valid interruption points and observable result.
• Engine: isolate the distressed feed, apply measured sacred oil, pronounce an original litany, restore load and watch response.
• Coolant: secure the circuit, vent under controlled pressure, replace/anoint the seal, test circulation.
• Breech: secure firing authority, clear and inspect the chamber, oil the bearing, reseat the mechanism, return it to service.
• Shrine: inspect seals/reliquary, replace spent incense, reconcile the vessel's ledger, perform a restorative invocation.
• Vox: isolate the carrier, compare the challenge response, purge the compromised path, restore the correct channel.
• Foundation implements three ordered steps per system; richer physical steps remain expansion work.
• Present original short phrases in full, with audible cadence and captions; do not require memorizing undocumented franchise passages.
• Correct step order is learnable from a physical manual and tool arrangement; feedback names what was endangered when wrong.
• Avoid reflex rhythm scoring as the sole rite mechanic; timing matters because the situation changes, not because chanting is an arbitrary minigame.
• A rite may be safely interrupted at a known boundary; abruptly opening an active pressure line has a specific consequence.
• Oil, incense, replacement seals and spare parts have distinct roles. One generic mana pool would flatten the loop.
• An expedited mechanical repair is faster and consumes parts; it carries deferred spirit debt that must later be reconciled.
• A completed rite cannot be spammed for unlimited benefit; condition, cooldown, material use and diminishing need limit it naturally.
• The manual records verified sequence and hazard; the status display records actual progress beside the station.

5. Diagnosis and intrusion

• Keep underlying cause hidden until evidence is gathered; expose symptoms honestly from the start.
• Each incident stores cause, target, onset, evidence, discovery state, escalation clock, resolution condition and lasting consequence.
• Diagnosis uses at least one direct examination plus corroboration when the stakes warrant it.
• Example: jerking turret can mean low power, mechanical fouling, gunner exhaustion, or a corrupted command pathway.
• The same visual symptom must not always map to one button; independent clues distinguish causes.
• Physical faults respond to repair; contamination requires identifying and isolating its route plus appropriate purification.
• Intrusion routes: damaged hull seal, compromised vox, contaminated reagent, crew breach, shrine neglect, trophy/relic, or the player's own perception.
• Introduce routes in a controlled sequence. Do not begin with all possible causes and no learned baseline.
• Purging the wrong target wastes a finite seal, consumes time and damages confidence; it does not secretly solve everything anyway.
• Concealed causes must be reconstructable in the debrief from evidence the player could have perceived.
• Accessibility duplicates semantic sound clues with captions/visual tells without converting every mystery into a numeric truth meter.
• Optional diagnostics/developer overlays reveal causes for tests, never replace player-facing evidence during acceptance runs.

6. Crew correction, authority and replacement

• Crew have competence, discipline, fatigue, corruption, response to correction, enduring suitability and a current work state.
• A breach is a specific observed act with location/time, not an arbitrary morality score tick.
• Loader example: muttered blasphemy precedes repetition and contaminated handling; delaying correction creates a real escalating opening.
• Immediate strong correction stops the behavior and lowers immediate intrusion risk, but occupies your attention and may interrupt the station.
• The user-requested difficulty contract is firm: persistent uncorrected serious breaches are a rapid losing strategy.
• Harshness means clear enforceable authority, binding penance, restricted duties or removal; gratuitous cruelty need not become an efficiency minigame.
• Correct witnessed behavior promptly; avoid rewarding blind punishment of every person when no evidence exists.
• A normally reliable exhausted crew member needs enforced rest/load relief as well as correction; an enduringly unsuitable member needs replacement.
• Repeated correction can suppress immediate symptoms without curing unsuitability. Show the pattern in the personnel ledger.
• Commander veto is explicit: order shown, objection reason, amended order, resulting delay and crew acknowledgment.
• Quarantine prevents further misconduct/contamination from that person but removes their labor and may force cautious movement or halted firing.
• Replacement occurs at an appropriate stop, carries requisition/relationship cost, and permanently preserves the departed record.
• First campaign phase is designed for at least two and commonly three replacements, introduced across three depot opportunities.
• Initial crew each has a documented enduring weakness; one recovery demonstration teaches temporary correction before removal becomes the sensible choice.
• Replacement candidates disclose a useful competence/discipline tradeoff and have distinct names/identities; do not reroll endlessly for perfection.
• Recruits are better suited but require a brief handover; maintain needed role coverage and never silently duplicate a crew role.
• Early replacement pressure must emerge from repeated observable incidents, not a hidden mandatory quota that fails an otherwise successful player.
• Balance test: keeping every unsuitable starter should be measurably harder; replacing two or three should reliably improve sustainable operation.

7. The player's own corruption

• Contact, forbidden shortcuts, tainted reagents and prolonged exposure can raise personal contamination separately from vessel contamination.
• Early tells are restrained and specific: altered repeated words, reflection inconsistency, a suspect instrument reading, involuntary rite variation.
• Preserve player trust: authoritative pause/settings/save controls never lie, and critical accessibility channels remain usable.
• A suspect perception has a cross-check: independent gauge, crew witness, physical pressure response or written canonical procedure.
• Self-examination and a shrine rite cost travel/time/incense; severe cases require intermission supervision and limits on ritual authority.
• Temptation may offer immediate speed/resource relief with a disclosed or discoverable long-term price.
• Do not seize movement or execute irreversible actions without clear presentation; altered perceptions create decisions rather than random stolen agency.
• Final failure explains the contamination chain and the missed opportunities to detect and contain it.

8. Outside-world fragments and portholes

• The outside world is coherent but incomplete: multiple slits reveal portions of one moving world, not unrelated random clips.
• Maintain a route-space event timeline indexed by distance, direction and elapsed time; use seeded generation plus authored landmarks.
• World-piece manifest fields: id, biome, dimensions, silhouette, material set, route distance, lateral lane, facing, velocity and lifetime.
• Additional fields: event role, threat/civilian/debris tag, occlusion layers, audio cue, collision relevance, variation seed, art provenance and review status.
• Piece families: broken masonry, trenches, burning wrecks, infantry silhouettes, enemy armor, fleeing civilians, shattered monuments and restrained grisly aftermath.
• Foundation geometry can prove placement/occlusion; it must be labeled placeholder until replaced by reviewed material-rich assets.
• Author a small reusable kit with consistent ground scale and light direction; variation changes arrangement and damage rather than merely tint.
• Pool meshes/sprites/materials, cap active counts and recycle behind the tank. Bound every spawn list and particle emitter.
• Coarse distant silhouettes and a few near detailed pieces establish parallax without rendering a full open-world battlefield.
• Use the same exterior transforms in overhead and first person. Adjacent portholes must agree on timing, direction and the identity of a passing vehicle.
• Each opening has its own field of view, hull thickness, shutter, grime, fracture, smoke and visibility state.
• Dust/condensation/impact can partially obscure a slit; wiping costs time and exposes the player to a new useful observation.
• Aim/fire/loading remain visible inside even when outside vision is poor; external silhouettes add uncertainty rather than swallowing the core loop.
• Passing events sometimes predict incoming danger: a rushing infantry group, rival muzzle flash, floodwater or changing ground texture.
• Do not make distant civilian fragments endlessly loop in place; give them coherent travel and humane, serious presentation.

9. Camera, interaction and information design

• Overhead is the default work view: visible walkable route, recognizable stations, moving crew and outside ground at hull edges.
• Cut away roof and camera-facing obstruction while retaining enough hull thickness to make the tank feel enclosed.
• First person uses the same collision body and location; instrument/hand/detail readability is a separate art gate.
• Transition preserves facing or offers a brief orientation cue; exit returns to the same position and station context.
• Desktop baseline: WASD movement, pointer selection, E interaction, F view switch, Escape pause/back, and visible equivalents. F matches the implemented foundation controls.
• First-person look uses pointer lock only after a clear gesture; Escape releases it and does not trap the user.
• One nearby target has a name, distance/availability and the current interaction; avoid stacking overlapping floating labels.
• Remote status can be read, but physical rites/inspection/correction require proximity unless explicitly designed as an order.
• HUD priorities: current hazard, underway action, concise machinery/crew states, supplies, mission progress; detailed logs remain secondary.
• Keep a stable instrument order and position. State changes alter color, needle, motion and wording rather than moving controls.
• Use named severity plus shape/icon, not color alone. Captions identify speaker and urgent sounds without covering the task.
• Orders announce the concrete consequence: reduced travel, firing suspension, pump priority or crew station interruption.
• Support pause, volume/bus controls, reduced motion, screen-shake control, readable text scale and keyboard focus.
• First foundation is desktop-targeted. Mobile can have a responsive reading/page shell without claiming complete touch gameplay.
• Touch support becomes a separate milestone: virtual movement/look, large reachable actions, no hover dependency, landscape/portrait constraints tested on device-size viewports.
• Autosave at safe boundaries; manual save preserves actual mission state and rite progress. Validate versions and malformed data.
• A protected training session and a real mission are distinct saves; exit training restores the real campaign rather than overwriting it.

10. Intermissions and campaign growth

• Depot: repair bay, supply counter, personnel review and report lectern, initially a compact readable interface or walkable chamber.
• Mission report separates facts, suspicions, confirmed intrusion routes, parts consumed, doctrinal deviations, casualties and disciplinary action.
• Leaders/teachers/peers respond to accumulated records; approval is not a generic reputation meter disconnected from decisions.
• Requisitions distinguish common oil/parts from blessed seals, approved incense, rare relic components and crew allocations.
• Stock shortages force a route/loadout choice; always display what the next known journey requires and what remains uncertain.
• Religious attendance, instruction and audits can unlock more efficient legitimate procedures rather than merely bigger numerical buffs.
• Long voyages across space allow inspection, doubt, cross-training, dreams and competing institutional demands; their dedicated play is later scope.
• Replace compromised crew, perform rites outside the vehicle, meet peers and protect the vessel's history across transfers.
• Campaign persistence includes tank damage/history, repaired scars, veteran crew bonds, personnel records and recognized machine-spirit preferences.
• Novel missions add an environmental rule and one intrusion pattern at a time: ash storm, mud/flood, frozen seals, irradiated dust, siege debris.

11. Technical foundation and content contracts

• New independent repository; reuse only verified reusable code/assets with provenance and license preservation.
• Runtime: local Three.js modules, DOM interface, deterministic simulation module, content definitions, save adapter, sound buses and bounded asset manifest.
• Contract exports: createState, tick, command, STATIONS, RITES, CREW_CANDIDATES; commands return explicit success/message.
• Foundation stations: engine, coolant, shrine, vox, breech, loader, gunner, commander; geometry and UI share their coordinates.
• Renderer reads state and emits intent; it does not secretly advance simulation or resolve rites itself.
• Commands validate phase, costs, target and sequence; spatial adapter validates actual proximity before physical actions.
• Effects/audio subscribe to discrete event ids so render refresh cannot replay a shot, correction or reward.
• Save versioning excludes GPU/audio objects, bounds event/log history and rejects impossible values with understandable recovery.
• Distinguish committed source from generated distributables and ephemeral QA; avoid duplicate builds and unbounded recordings.
• New large work checks real system/destination capacity and peak temporary/final size; retain at least 100 GB reserve on each affected filesystem.

12. Milestones and acceptance

• Foundation tests cover fixed-step determinism, bounded meters, correct rite order/cost, damaged-system consequences, incident resolution and role replacement.
• Behavior tests compare unattended, rote maximum-speed, and deliberate efficient strategies using fixed seeds; do not only assert implementation details.
• Browser tests walk through visible controls, move between stations, switch cameras, complete work, respond to a real incident, reach depot and replace a crew member.
• Verify load after pause/mid-rite, malformed save recovery, hidden-tab freeze, pointer-lock release and responsive reading.
• Visual evidence captures actual runtime at native intended footprint and enlarged display; include quiet operation and crisis, not only a flattering title image.
• Sound tests prove signal, mute, bus control, cooldown and cleanup; human listening assesses atmosphere, clarity and performance.
• Use bounded browser lifecycle and sequential GPU-heavy capture; retain a compact evidence set with timestamps/commit identity.

13. Art production and drift prevention

• Freeze a small reviewed reference board: Diablo I room, creature close-up, inventory, industrial cockpit support, material/lighting samples.
• Each asset ticket names its function, physical size, gameplay footprint, camera distances, palette identity and exact source references.
• First build one finished tank sector: riveted hull, conduit, gauge, shrine detail and crew hand/tool contact under final lighting.
• Review materials together; bright local steel, dull iron, cloth, wax, parchment, oil and glass need different responses.
• Validate silhouette, construction and contact before microdetail; no amount of generated grime approves wrong proportions.
• Generate/rasterize new images with recorded prompts and manifests; original-era screenshots remain reference only, never shipped textures.
• Approve clean still, normal-size runtime still, short motion, then integrated scene in that order.
• A rejection names the cause: soft form, wrong material, excess fill, absent contact, lost pixel footprint, generic UI or unresolved source fidelity.
• Keep canonical approved exemplars and changed assets together in review. Never quietly replace an approved style target with an easier reference.
• Require renewed review after camera, light, palette, material pipeline or postprocess changes; those can invalidate previous asset acceptance.

14. Model allocation and continuity

• Keep strongest reasoning for premise/lore tensions, coupled-systems design, architecture, visual critique and milestone acceptance.
• Once interfaces, examples and tests are stable, delegate bounded implementation to an efficient model appropriate to the task.
• Every handoff packet includes purpose, exact owned files, API, data schema, approved visual references, prohibitions, acceptance actions and known limitations.
• Require a concrete diff, test evidence and uncertainty report; inspect output against the same gates used for stronger-model work.
• Return to stronger review when coupling changes, ambiguity emerges, visual results drift or tests expose an unexplained failure.
• Smaller context, targeted assets and independent tasks reduce usage without lowering acceptance standards.
• Do not guarantee mathematically identical quality across models; preserve quality requirements through review, measurement and rejection of inferior output.
• Never authorize an unsupervised broad rewrite because a handoff model can satisfy a few superficial tests.

15. Cassette, page and later films

• Prepare an original cassette cover and game page with working title, premise, truthful build status, controls and current playable entry.
• Separate concept art, actual gameplay and future promises in labels. A cassette can exist before a trailer does.
• Integrate through the existing Kadabra catalog/shelf/player conventions while preserving other games, film routes, edge functions and downloads.
• The user's explicit gate is demo done and approved before cinematic and narrated gameplay production.
• After approval, capture real successful/failed maintenance sequences with readable causes, crew activity and a view transition; script narration from those verified events.
• Cinematic direction uses deliberate approach, revelation, contact and consequence, with tank/machine-spirit identity established through material and sound.
• Keep cinematic dramatization distinct from gameplay footage; original score/voices/effects require documented provenance and applicable release permissions.
• Review short picture/sound passages before a full render; estimate space including master, encoded output and validation copy.
• Final publication checks the whole deployment and actual player route, not merely a new card or a downloadable file.