Technical design

Runtime architecture #

The active project uses TypeScript, Three.js, Vite, and plain DOM screens. Supabase supplies private co-op transport, room coordination, and optional accounts. The preserved Phaser/Vue project is a separate legacy reference and is not imported by the active game.

Input becomes player commands. A fixed-step deterministic simulation advances rules, returns snapshots, and queues semantic events. Rendering interpolates snapshots, while audio and effects consume events. Presentation must not alter simulation state or consume its randomness.

• src/content/: stable definitions, balance, models, and presentation catalogs.
• src/simulation/: combat, state, seeded randomness, collision, pickups, economy, checkpoints.
• src/ThreeCombatRenderer.ts and presentation modules: 3D scene, interpolation, effects, lighting.
• src/network/: transport, private rooms, ordered commands, checkpoints, and recovery.
• src/ui/: DOM screens and UI lifecycle. src/main.ts coordinates the application.

Source reference: ARCHITECTURE.md · src/main.ts · src/simulation/MissionSimulation.ts

Determinism and compatibility #

Content, simulation, and network identifiers are stable strings rather than display names. Seeded simulation and independent scenery generation allow reproducible scenarios. Network changes must preserve command ordering and ownership, and deterministic state must survive checkpoint restoration.

The host applies store commands using per-pilot sequence tracking and bounded receipts so delayed or duplicated purchases cannot charge twice. Run identity, stage identity, mission preparation, and readiness are tracked through transitions. New deterministic systems need explicit state, snapshot, event, and restoration behavior.

Protocol and checkpoint versions are separate. A feature that changes message compatibility or restored state must update the relevant version and account for co-op clients on older builds.

Source reference: src/simulation/types.ts · src/network/contracts.ts · src/simulation/RunState.ts · ARCHITECTURE.md

Blender models and presentation #

Editable Blender projects and reproducible Python builders live in art/. Runtime assets live in public/assets/. Models use glTF/GLB, meters, Y-up coordinates, and forward -Z. Named mounts, collision objects, and animation clips form an asset contract.

Player hulls expose muzzle, thruster, and collision nodes; enemies expose Muzzle, Thruster, Collision, and role-specific nodes such as launch bays. The unit reference names the runtime model for each craft. Thumbnails are generated from the actual models and copied into this snapshot so future replacements do not alter this reference.

Silhouette, readable attack windups, visible weapon aim, hit reactions, damage panels, explosions, and debris communicate game state. The browser renderer uses bounded effect pools and reduced-motion alternatives. A large visual blast is not automatically evidence of a matching damage volume.

Source reference: src/content/actorModels.ts · src/content/crucible.ts · src/ThreeCombatRenderer.ts · art/ · ARCHITECTURE.md

Audio and cinematic presentation #

Audio is routed through event definitions, category controls, and per-mission sound sets that combine recorded, generated, and synthesized sounds. Source recipes and third-party credits are maintained alongside the asset pipeline.

Mission introductions and promotional media are presentation layers. They remain skippable or optional and must not delay reliable control.

Source reference: src/AudioDirector.ts · src/audio/catalog.ts · src/audio/foundryCues.ts

Constraints for new ideas #

• Keep combat rules independent of Three.js, DOM, audio, and transport.
• Budget active enemies, projectiles, summons, explosions, lights, and transparent effects. More simultaneous effects can hurt readability before they exhaust hardware.
• Treat player count, overlapping abilities, boss phases, ground/air restrictions, and energy depletion as core design cases.
• Telegraph enemy attacks on the unit, not with floor lanes or sweep fans that predict movement.
• Provide visual cues beyond color alone, keyboard focus, readable contrast, and reduced-motion behavior.
• New hulls and enemy families need model mounts, animations, tuning, collision, UI, audio, VFX, and co-op behavior.
• The current main application and simulation modules are large. Prefer bounded modules and clear ownership when adding new systems.

Source reference: PRODUCT.md · ARCHITECTURE.md · CONTEXT_MAP.md

Development labs and tuning #

The admin library contains unit comparisons and model inspection, audio review, the Graphics, HUD, Orb, and Garmo labs. These tools make visual and balance review possible without repeatedly editing presentation code by hand.

This knowledge base is a separate, manual reference snapshot. It has no connection to live lab saves, player accounts, or gameplay state.

Source reference: src/ui/DevHub.ts · src/ui/OrbLab.ts · src/ui/HudLab.ts

Versions and simulation dimensions #

Source reference: src/simulation/types.ts · src/content/combat.ts · src/content/upgrades.ts

Specialized ability parameters #

The following are named configuration fields for implementation discussion. Ms suffixes mean milliseconds; distances and speeds use meters and meters/second, angles use radians, and fractions are dimensionless. Capacity and pool fields are bounds, not damage values. Only ability families used by ships in rotation are included.

Source reference: src/content/combat.ts: CLASS_ABILITIES, HOLY_BOLT · src/content/garmo.ts · src/content/michen.ts