dota_factory/docs/requirements.md

Requirements

Config Files

Config files use the TOML format. The following config files drive game parameters:

• world.toml — world dimensions, region widths, expansion amounts, building refund percentage, wave timing, boss wave timing, enemy ship level formula, belt speed, starting building blocks, departure interval, ship orbit factor, rally orbit radius, and combat target-selection parameters (target score formula, overclaim penalty formula, target hysteresis).

• buildings.toml — building block cost and construction time per building type.

• recipes.toml — crafting recipes: inputs, outputs, quantities, durations, and reprocessing plant probabilities. Assembler recipe entries may optionally define unlock_at_station_level (integer): -1 means the recipe is explicitly unlocked at game start; a value ≥ 0 means the recipe starts locked and a schematic for it can be awarded via defence station destruction (see REQ-LOCK-EXPLICIT, REQ-DEF-SCHEMATIC-DROP).

• ships.toml — per schematic: a human-readable display name (used in the UI), hull stats (HP, max linear speed, sensor range, main acceleration, maneuvering acceleration, angular acceleration, max rotation speed) as formulas of ship level, required build materials, player production level, the station level at which the schematic becomes available for unlock (unlock_at_station_level; -1 means the player starts with the schematic already unlocked), a layout grid defining the ship's module slots, a scrap_drop loot value, and a default_modules list used for enemy wave ships (see REQ-WAV-DEFAULT-MODULES).

• modules.toml — per module type: id, surface mask, materials list, initial player production level, production time, fill color, glyph, the station level at which the schematic becomes available for unlock (unlock_at_station_level; -1 means the player starts with the module schematic already unlocked), and an optional capability section and/or stat modifier formulas. A module with a capability section ([module.weapon], [module.salvage], or [module.repair]) containing base stat formulas is a capability module that grants the ship a weapon, salvage bay, or repair tool per instance (see REQ-MOD-CONFIG for the full list of formulas per capability type). A module with only added_*/multiplied_* formulas is a passive module that modifies stats on the ship or on capability module instances (see REQ-MOD-STAT-CALC).

• stations.toml — HP, damage, range, fire rate, and scrap drop for player and enemy defence stations, defined as formulas of station level.

• visuals.toml — rendering-only config (not game parameters): fill and outline colors and glyphs for every building type, item type, ship schematic, and station type; beam color and width; overlay and toast colors. Loaded by the UI at startup; the simulation does not read it.

• ship_layouts.toml — named layout blueprints per ship type; written and read by the application to persist the layout blueprint panel (REQ-MOD-UI-BLUEPRINT-PANEL through REQ-MOD-UI-BLUEPRINT-FILE-LOAD). Not a game parameter file; the simulation does not read it.

• REQ-CFG-RELOAD: When the player triggers a Restart (REQ-UI-GAME-MENU), all config files are reloaded from disk before the simulation is reset to its initial state. Formula strings are recompiled at that point. This allows config edits made while the application is running to take effect without a full application restart.

Surface Mask Format

Buildings in buildings.toml define a surface_mask — a list of strings that describes the building's tile footprint and output port(s). Each character occupies one cell in the grid:

• A — building tile that must be placed on an asteroid tile.
• S — building tile that must be placed on a space tile.
• (space) — empty cell; not part of the building footprint.
• > — output port indicator: the building tile immediately to its left has a rightward-facing output port (items push right).
• < — output port indicator: the building tile immediately to its right has a leftward-facing output port (items push left).
• ^ — output port indicator: the building tile immediately below it has an upward-facing output port (items push up).
• v — output port indicator: the building tile immediately above it has a downward-facing output port (items push down).

Output port indicators are not building tiles themselves. A building may have more than one output port (e.g. a splitter uses <A> to declare both a left and a right output on the same tile).

Ship Layout Format

Ships in ships.toml define a layout — a list of strings that describes the ship's module grid. Each character occupies one cell:

• O — buildable cell; modules can be placed here.
• X — non-buildable cell; not part of the ship's interior.

The layout grid determines which cells are available for module placement in the layout configuration dialog.

Layout Blueprint TOML Format

Each entry in ship_layouts.toml represents a named layout blueprint:

[[blueprint]]
name = "Heavy Shields"          # display name; must be unique within a ship type
ship_type = "fighter"           # matches a schematic id in ships.toml
modules = [
  {type = "shield_module", x = 0, y = 0, rotation = 0},
  {type = "cannon_module", x = 2, y = 1, rotation = 90},
]

• name — human-readable display name. Must be unique within a ship type; need not be globally unique.
• ship_type — the schematic id this blueprint belongs to. Must match a schematic defined in ships.toml.
• modules — array of placed module instances. Each entry: type (module id from modules.toml), x and y (zero-based column/row in the ship's layout grid), rotation (0, 90, 180, or 270 degrees clockwise). If modules is absent or empty, the blueprint represents an empty layout.

The modules array format is reused verbatim in balancing.toml ship entries (see REQ-BAL-TEAM).

Module Surface Mask Format

Modules in modules.toml define a surface_mask — a list of strings that describes the module's tile footprint within the ship layout grid. Each character occupies one cell:

• O — module cell: must be placed on an unoccupied buildable cell (O) of the ship's layout.
• X — ignored cell: may overlap any cell (non-buildable, unoccupied buildable, or occupied buildable) or extend outside the layout grid entirely.

Game World

• REQ-GW-COORDS: Tile coordinates are integer (x, y). The origin (0, 0) is the first column of space — the tile immediately to the right of the asteroid's right edge at game start, at the top of the world. X grows right; Y grows down. All asteroid tiles have x < 0; asteroid left-expansions add tiles at increasingly negative X. The origin never shifts.
• REQ-GW-TILE-SIZE: Tiles are square. The tile size in pixels is derived automatically so that the world height (in tiles) exactly fills the game world view's height in pixels. Items on belts are rendered at half-tile size; when multiple items occupy the same tile they are spaced quarter-tile apart along the direction of travel and overlap, rendered in ascending order of progress — the least-progressed item is drawn first (bottom) and the furthest-progressed item is drawn last (on top).
• REQ-GW-BELT-CAPACITY: Belt tiles and tunnel entry/exit tiles each hold up to four items simultaneously, queued one behind the other in the direction of travel. Splitter tiles hold up to four items: two unassigned items (progress < 0.5, not yet routed to an output) and one item per output slot (progress ≥ 0.5, committed to a specific output direction). Output-slot items are rendered on top of unassigned items; when both output slots are occupied, their rendering order follows the clockwise port order starting from East.
• REQ-GW-BELT-SPEED: Items on belts move at world.toml [world].belt_speed_tiles_per_second tiles per second (default 2).
• REQ-GW-HEIGHT: The world height (in tiles) is read from world.toml [world].height_tiles.
• REQ-GW-REGIONS: The world is divided into horizontal regions whose widths (in tiles) are read from world.toml [regions]:
  • Asteroid — the player's build area (asteroid_width).
  • Player buffer zone — space between the asteroid and the player's defence stations (player_buffer_width).
  • Contest zone — space between the player's and enemy's defence stations. This is where combat happens (contest_zone_width).
  • Enemy buffer zone — space between the enemy's defence stations and the enemy spawn boundary (enemy_buffer_width).
• REQ-GW-SCROLL-LIMIT: The player can scroll the view horizontally from the asteroid's left edge to the current set of enemy defence stations (the enemy buffer zone is not visible).
• REQ-GW-PUSH-EXPAND: When the player destroys a set of enemy defence stations, the scrollable area is extended by world.toml [push].push_expand_columns tiles. A new enemy buffer zone of world.toml [regions].enemy_buffer_width tiles is added beyond the new enemy defence stations.
• REQ-GW-ASTEROID-EXPAND: When the player unlocks an asteroid expansion, world.toml [expansion].columns_per_expansion tile columns are added to the left of the asteroid.

HQ & Game Over

• REQ-HQ-PLACEMENT: The HQ is pre-placed at the asteroid's right edge at game start.
• REQ-HQ-BELT-INPUT: The HQ has a belt input port. Building blocks delivered to it are added to the global building blocks stock.
• REQ-HQ-STATS: HQ stats (HP) are read from stations.toml [hq].
• REQ-HQ-STARTING-BLOCKS: At game start, the global building blocks stock is initialized to world.toml [world].starting_building_blocks (default 100).
• REQ-HQ-GAME-OVER: If the HQ is destroyed, the game ends. A game-over screen shows the final survival time and offers "Restart" and "Quit" buttons.
• REQ-HQ-INVULNERABLE: Factory buildings (other than the HQ) are never targeted or destroyed by enemies.

Building Placement & Management

• REQ-BLD-COST: The player places buildings from a build menu. Placement costs building blocks from the global stock. The cost per building type is read from buildings.toml [[building]].cost.
• REQ-BLD-QUEUE: Placed buildings enter a construction queue and are built one at a time. Each building takes a duration defined in buildings.toml [[building]].construction_time_seconds to construct.
• REQ-BLD-ASTEROID-ONLY: Buildings can only be placed on asteroid tiles (per surface_mask; tiles marked S may extend into space).
• REQ-BLD-BUILDER-MODE: Clicking a build button activates builder mode for that building type. Builder mode is exited by right-clicking in the game world or clicking the same build button again.
• REQ-BLD-GHOST: While in builder mode, a ghost of the building is rendered at the tile under the cursor, showing where it would be placed.
• REQ-BLD-ROTATE: While in builder mode, pressing E rotates the ghost 90° clockwise and Q rotates it 90° counter-clockwise. Rotation affects the direction of the output port.
• REQ-BLD-PLACE: Clicking a valid tile in builder mode places a construction site and adds it to the build queue, consuming building blocks from the global stock.
• REQ-BLD-PLACE-VALID: A placement position is valid only if (a) every footprint cell in the rotated surface_mask is satisfied by the underlying terrain — A cells coincide with asteroid tiles, S cells coincide with space tiles — (b) no footprint cell overlaps an existing placed building or construction site, except as allowed by REQ-BLD-ROTATE-IN-PLACE, and (c) the player has enough building blocks to afford the building. The ghost (REQ-BLD-GHOST) is rendered in a distinct "invalid" color when the current cursor position fails any of these conditions.
• REQ-BLD-ROTATE-IN-PLACE: If the ghost's footprint exactly coincides with the footprint of an existing placed building or construction site of the same building type, clicking places no new construction site and consumes no building blocks. Instead, the existing building or site is rotated to match the ghost's rotation. If the target is a construction site, its construction progress is preserved. This applies in both normal builder mode and blueprint placement mode; in blueprint placement mode it is evaluated per building in the blueprint independently — buildings in the blueprint whose footprint coincides with an existing same-type building or site are rotated in place, while the remaining buildings in the blueprint are placed as normal construction sites (subject to the usual validity checks and total cost).
• REQ-BLD-BELT-DRAG: For belts, the player can click and drag across multiple tiles to place a construction site on each tile in one gesture.
• REQ-BLD-TUNNEL-AUTO-SWITCH: After the player successfully places a Tunnel Entry construction site, builder mode automatically switches to Tunnel Exit (and vice versa), preserving the current ghost rotation. This makes it easy to immediately place the paired end without manually selecting the complementary type.
• REQ-BLD-DEMOLISH: The player can demolish a placed factory building. Demolition returns world.toml [world].refund_percentage percent of the original building block cost (default 75%) to the global stock. Exception: if the building is still in the construction queue (not yet fully built, including the one currently being constructed), it is removed from the queue and the full building block cost is refunded. The HQ and player defence stations cannot be demolished.

Building Types

• REQ-BLD-MINER: Miner (2×2): The player selects which ore type it extracts. Each ore type corresponds to a recipes.toml [[recipe]] entry with building = "miner", defining the output item and duration_seconds. Every asteroid tile is equivalent for mining — any miner can produce any ore type based solely on its selected recipe. Ore never depletes. Only implicitly unlocked ore-type recipes are available for selection (REQ-LOCK-UI-RECIPE).
• REQ-BLD-SMELTER: Smelter (2×2): Converts ore or scrap into basic materials. No recipe selection required. Inputs, outputs, and rates are defined in recipes.toml [[recipe]] entries with building = "smelter".
• REQ-BLD-ASSEMBLER: Assembler (3×3): The player selects a recipe from the config-defined crafting tree. Produces the selected output item at the rate defined in the corresponding recipes.toml [[recipe]] entry with building = "assembler". Only implicitly unlocked recipes are available for selection (REQ-LOCK-UI-RECIPE).
• REQ-BLD-REPROCESSING: Reprocessing Plant (3×3): Consumes scrap per cycle and produces exactly one higher-level intermediate product per cycle via weighted random pick. The input quantity, possible output items, per-output weights, and amounts are defined in recipes.toml [[recipe]] entries with building = "reprocessing_plant" (inputs, outputs[].item, outputs[].amount, outputs[].weight). Weights are normalized at load time; their sum does not need to equal 1. The output is rolled at cycle start (see REQ-MAT-CYCLE); the pool of eligible outputs is restricted to implicitly unlocked item types (REQ-LOCK-REPROCESSING-POOL). The output buffer holds at most one cycle's output — see REQ-MAT-OUTPUT-BUFFER-REPROCESSING.
• REQ-BLD-SHIPYARD: Shipyard (4×2): The player selects a schematic. When all required materials — the ship's base materials ([ship.schematic].materials) plus the materials of all modules in the configured layout (REQ-MOD-MATERIALS) — are present in its input buffer, the shipyard consumes them and begins a production cycle lasting the ship's base [ship.schematic].production_time_seconds plus the sum of production times contributed by all module instances in the configured layout (REQ-MOD-PRODUCTION-TIME). One ship of that type is spawned at ships.toml [ship.schematic].player_production_level (initial value 5, incremented by duplicate schematic drops per REQ-DEF-SCHEMATIC-DROP) with the configured modules when the cycle completes. The shipyard cannot start a new cycle while one is in progress. If the player confirms a layout change (REQ-MOD-UI-DIALOG) while a production cycle is in progress, the current cycle is cancelled and all consumed materials are discarded; the shipyard returns to idle with the new layout configuration.
• REQ-BLD-SALVAGE-BAY: Salvage Bay (3×2): A dedicated drop-off point for salvage ships. Scrap delivered here is placed onto connected output belts.
• REQ-BLD-BELT: Belt (1×1): Transports items. A belt tile has one direction (N, S, E, W) set at placement (modified by rotation). Curved belts are auto-derived: when a belt tile's outgoing direction leads into another belt whose direction is orthogonal, the downstream belt is rendered and behaves as a curve. Belt speed is defined in world.toml [world].belt_speed_tiles_per_second (REQ-GW-BELT-SPEED).
• REQ-BLD-SPLITTER: Splitter (1×1): Distributes incoming items between two output directions. Each output can optionally have a filter (a list of item types), configurable via the selected building panel; only implicitly unlocked item types are available as filter options (REQ-LOCK-UI-SPLITTER). Routing rules:
  • An item matching only one output's filter is routed to that output.
  • An item matching both outputs' filters is distributed by strict alternation between those outputs.
  • An item matching neither output's filter is routed to the unfiltered output. If both outputs have a filter and the item matches neither, the splitter stalls and moves no items until the situation is resolved.
  • If neither output has a filter, items are distributed by strict alternation.
  • In all alternation cases, if one output is blocked the item goes to the other output until it unblocks.
• REQ-BLD-TUNNEL-ENTRY: Tunnel Entry (1×1): The sending end of a tunnel pair. The player sets a direction (N, S, E, W) at placement, rotatable with Q/E. Items arriving from an adjacent belt tile whose direction points into the entry are forwarded through the tunnel to the paired Tunnel Exit (see REQ-BLD-TUNNEL-PAIR, REQ-BLD-TUNNEL-TRANSIT). If the entry is unpaired, or if the paired exit's output is blocked, the entry blocks like a full belt tile.
• REQ-BLD-TUNNEL-EXIT: Tunnel Exit (1×1): The receiving end of a tunnel pair. The player sets a direction at placement, rotatable with Q/E. Items received from the paired Tunnel Entry emerge from the output side of the exit tile — the tile adjacent in the exit's facing direction — continuing in that direction. If the exit is unpaired or its output is blocked, it holds received items until they can advance.
• REQ-BLD-TUNNEL-PAIR: Tunnel pairing rules. Pairing is re-evaluated for all Tunnel Entries whenever any Tunnel Entry or Tunnel Exit is placed or demolished.
  • A Tunnel Entry searches tile-by-tile in its facing direction for a partner. Any tunnel building (entry or exit) that faces a different direction is ignored and skipped. The search stops at the first tunnel building that faces the same direction as the searching entry.
  • If that first same-direction tunnel building is a Tunnel Exit, is within tunnel_max_distance tiles of the entry, and is not already paired with a closer entry, the two form a pair.
  • Otherwise the entry is unpaired.
  • Pairing is one-to-one: each Tunnel Entry pairs with at most one Tunnel Exit, and vice versa. A Tunnel Exit is claimed by the nearest Tunnel Entry that can validly reach it; all other entries for which it would otherwise qualify are unpaired.
  • When one end of a pair is demolished, the pair is dissolved and any items currently in transit are discarded.
• REQ-BLD-TUNNEL-TRANSIT: Tunnel transit. Items inside a tunnel are not rendered (they travel invisibly). Transit time equals the tile-coordinate distance between entry and exit divided by world.toml [world].belt_speed_tiles_per_second, matching the time a chain of belt tiles of equivalent length would take. Multiple items may be in transit simultaneously, spaced as they would be on a belt chain of the same length. Clearing a tunnel entry or exit tile (REQ-UI-BELT-CLEAR) also discards all items currently in transit through that tunnel.

Material Transport & Buffers

• REQ-MAT-BELT-ONLY: Materials are transported exclusively via belts, splitters, and tunnels.
• REQ-MAT-INPUT-PORTS: A building accepts items from any adjacent belt tile on any edge of its footprint (excluding cells occupied by output port(s)) whose direction points toward the building, provided the item is an input required by the currently selected recipe and the matching per-material input buffer has free space.
• REQ-MAT-OUTPUT-PORT: Each building has one or more fixed output port(s) defined by its surface_mask (direction determined by rotation). Produced items are placed onto the belt at the output port tile regardless of that belt's direction.
• REQ-MAT-INPUT-BUFFER: Each building has one input buffer per required input material. Each per-material buffer holds up to twice that material's per-cycle requirement. When the player selects a new recipe or schematic, all items in all input buffers are cleared.
• REQ-MAT-OUTPUT-BUFFER: Each building has an output buffer that holds up to twice the quantity produced by one production cycle. If the output buffer is full, production stops until space is available. When the player selects a new recipe or schematic, all items in the output buffer are cleared (relevant when the adjacent belt is jammed and items have accumulated).
• REQ-MAT-OUTPUT-BUFFER-REPROCESSING: Exception to REQ-MAT-OUTPUT-BUFFER — the Reprocessing Plant's output buffer holds at most one cycle's output. This prevents exploits where the player stalls the output belt to force the plant to reroll.
• REQ-MAT-CYCLE: Production cycle lifecycle. When a building is idle, it attempts to start a new cycle: (a) all required inputs must be present in the per-material input buffers, and (b) the cycle's output must fit in the output buffer. For the Reprocessing Plant, the output is picked at cycle start (weighted pick); the cycle only starts if that chosen output fits. On cycle start, inputs are consumed immediately and the production timer begins. On cycle completion, the (already-decided) output is deposited into the output buffer and the building returns to idle.
• REQ-MAT-GLOBAL-STOCK: The building blocks stock is the only global inventory. All other materials exist only in building buffers or on belt tiles.

Resources

• REQ-RES-SCRAP-DROP: Destroyed ships (both player and enemy) and destroyed defence stations (both player and enemy) drop scrap at their location. The scrap amount per ship is defined in ships.toml [ship.loot].scrap_drop; for stations it is defined as stations.toml [player_station].scrap_drop_formula and [enemy_station].scrap_drop_formula. Scrap despawns after world.toml [world].scrap_despawn_seconds seconds if not collected.
• REQ-RES-SCRAP-COLLECT: Scrap is collected by salvage ships and delivered to a Salvage Bay on the asteroid. From there it can be fed via belt into a smelter (same output as ore) or a Reprocessing Plant.

Ships

• REQ-SHP-AUTONOMOUS: Ships are produced by shipyards and are fully autonomous once produced.

• REQ-SHP-STATS: Base hull stats are defined as formulas of ship level in ships.toml: HP ([ship.health].hp_formula), max linear speed ([ship.movement].speed_formula), sensor range ([ship.sensors].range_formula), main acceleration ([ship.movement].main_acceleration_formula, tiles/s²), maneuvering acceleration ([ship.movement].maneuvering_acceleration_formula, tiles/s²), angular acceleration ([ship.movement].angular_acceleration_formula, rad/s²), max rotation speed ([ship.movement].max_rotation_speed_formula, rad/s). Required build materials ([ship.schematic].materials) and the station level at which the schematic becomes available for unlock ([[ship]].unlock_at_station_level; -1 = player starts with the schematic already unlocked) are also defined there. Combat, salvage, and repair capabilities are provided by modules (see REQ-MOD-CONFIG). Final hull stats incorporate passive module modifiers per REQ-MOD-STAT-CALC.

• REQ-SHP-SPAWN-PLAYER: A ship produced by a shipyard spawns centered on the shipyard's output port tile.

• REQ-SHP-SPAWN-ENEMY: Enemy ships spawn at a uniformly random position within the current enemy buffer zone — random X across the buffer's width and random Y across the world height.

• REQ-SHP-MOVEMENT: Ships move using a physics-based model. Each ship has a velocity and a facing direction, both updated each tick. The main acceleration (main_acceleration_formula) is applied along the ship's current facing direction only. The maneuvering acceleration (maneuvering_acceleration_formula) can be applied in any direction independently of the facing direction, enabling lateral or braking movement without rotating. The angular acceleration (angular_acceleration_formula) controls how quickly the ship rotates. Linear speed is capped at the ship's speed_formula value; rotation rate is capped at the ship's max_rotation_speed_formula value. Ship position refers to the ship's center for all range, sensor, and attack checks.

• REQ-SHP-ORBIT: Several behaviors keep a ship circling its target at a fixed standoff distance (an orbit) rather than approaching a fixed point. The orbit radius depends on the behavior:

  • Combat engagement (REQ-SHP-COMBAT, REQ-SHP-ENEMY-AI): world.toml [world].orbit_factor multiplied by the maximum weapon attack_range across the ship's weapon module instances.
  • Repair (REQ-SHP-REPAIR): orbit_factor multiplied by the maximum repair_range across the ship's repair module instances.
  • Salvage (REQ-SHP-SALVAGE): orbit_factor multiplied by the maximum collection_range across the ship's salvage module instances.
  • Rally (REQ-SHP-RALLY): world.toml [world].rally_orbit_radius_tiles — a fixed radius in tiles, independent of any tool range (the rally point is a position, not a tool-bearing target).

  All tool ranges incorporate passive module modifiers (REQ-MOD-STAT-CALC). While orbiting, the ship navigates to maintain the orbit radius from the target's current center (REQ-SHP-MOVEMENT) while moving tangentially around it: if it is farther than the orbit radius it closes in, if it is nearer it backs off, and at the radius it circles. The orbit direction (clockwise or counter-clockwise) is fixed for the duration of orbiting a given target. Orbiting uses the standard physics movement model (REQ-SHP-MOVEMENT) and introduces no new movement constraints. Orbiting does not by itself trigger tool use — weapons, repair tools, and salvage bays still fire/heal/collect strictly per their own range and rate checks (REQ-SHP-FIRING, REQ-SHP-REPAIR, REQ-SHP-SALVAGE). With orbit_factor ≤ 1 the orbit lies within the maximum tool range, so the longest-range tool of that type remains in range while the ship orbits.

• REQ-SHP-NO-COLLISION: Ships do not collide with each other or with defence stations; they may visually overlap.

• REQ-SHP-SENSOR: A ship perceives only entities within its sensor range. Behavior is driven by what is in sensor range; entities outside sensor range are ignored.

• REQ-SHP-FIRING: All weapons — on ships and on defence stations — fire when off cooldown and the target is within attack range. Firing emits a fire event and starts a 0.15-second damage delay (half the beam duration). When that delay expires, damage is applied to the target — unless the target has already been destroyed, in which case the damage is silently dropped. If the shooter is destroyed before the delay expires, damage is still applied when the delay expires. There is no projectile entity and no intervening collision. The weapon's cooldown begins at the moment of firing, not at damage application.

• REQ-SHP-FIRING-BEAM: Each fire event produces a visual laser beam drawn from the shooter's position to the target for 0.3 seconds. The beam endpoint is not the target's center but a point randomly offset from it: the offset direction is uniformly random and the offset magnitude is uniformly random up to half the target's visual size (for ships: half their rendered radius; for buildings/stations: half the shorter side of their tile footprint, in world units). The offset is chosen once per fire event and held fixed for the beam's lifetime. The beam is a pure rendering effect and has no simulation state (does not block movement, does not re-apply damage over its lifetime). Beams follow the shooter and target positions if either moves during the 0.3-second window. The beam is rendered for its full 0.3-second duration even if the shooter or target is destroyed before it expires.

• REQ-SHP-COMBAT: Ships with at least one weapon module (player) — engage enemy ships within sensor range. When engaging an enemy, the ship orbits it at the combat orbit radius (REQ-SHP-ORBIT) rather than approaching its center. The player can configure the following per shipyard (applied to all ships produced by that shipyard):

  • Stance: aggressive (advance toward enemies) / defensive (hold position near asteroid).
  • Target priority: closest / highest HP / structures first.

• REQ-SHP-RALLY: After spawning, aggressive-stance ships with weapon modules move to and orbit the rally point — the midpoint between the two player defence stations (center of their Y-span, at the player defence stations' X position) — at the rally orbit radius (REQ-SHP-ORBIT). While orbiting the rally point, ships still engage any enemy that enters sensor range (switching to the combat orbit per REQ-SHP-COMBAT). Every world.toml [world].departure_interval_seconds seconds (default 20), all ships with weapon modules currently at the rally point depart simultaneously and begin their normal aggressive advance toward the enemy. The departure timer is global and shared across all shipyards; it is not reset by individual ship arrivals at the rally point.

• REQ-SHP-SALVAGE: Ships with at least one salvage module (player) — patrol by moving forward (rightward, away from the asteroid) while searching sensor range. If scrap enters sensor range, navigate toward it by orbiting it at the salvage orbit radius (REQ-SHP-ORBIT); when it is within a module's collection_range, that module collects it (consuming the scrap entity). Once all cargo is full, fly to a Salvage Bay and deliver (a direct approach, not an orbit — the ship must reach the bay); after delivery, resume patrol. If an enemy ship enters sensor range, the ship retreats (REQ-SHP-RETREAT) until no enemy is in sensor range, then resumes patrol — this applies regardless of whether the ship is targeting or carrying scrap. Ships with salvage modules are vulnerable to enemy ships while operating.

  Each salvage module instance operates independently: it has its own cargo hold (cargo_capacity), collection range (collection_range), and collection rate (collection_rate, in collections per second). After collecting a piece of scrap, the module cannot collect again until 1 / collection_rate seconds have elapsed. A ship with multiple salvage modules can therefore collect multiple pieces of scrap per tick (one per ready module), and installs of different module types may have different ranges and rates. The ship navigates based on the maximum collection range across all installed salvage modules.

  Salvage collection and delivery are world-state changes performed every tick regardless of which behavior the ship is currently executing; the salvage behavior only governs where the ship navigates (toward scrap, toward a Salvage Bay, or — when retreating — toward the rally point).

• REQ-SHP-REPAIR: Ships with at least one repair module (player) — patrol by moving forward (rightward, away from the asteroid) while searching sensor range. If a damaged player defence station or player ship enters sensor range, navigate toward it by orbiting it at the repair orbit radius (REQ-SHP-ORBIT) and repair. If an enemy ship enters sensor range, the ship retreats (REQ-SHP-RETREAT) until no enemy is in sensor range, then resumes patrol. The player can configure the target priority per shipyard:

  • Defence stations first / ships first / nearest target.

  Each repair module instance operates independently: it has its own repair rate (repair_rate) and repair range (repair_range). On each tick, a module first attempts to heal the ship's current behavior-level navigation target if that target is within the module's repair_range and is damaged (HP above zero and below maximum HP). If those conditions are not met — because the target is out of the module's repair_range, already at full health, or destroyed — the module independently searches for the nearest damaged friendly (player ship or player defence station) within its own repair_range and heals that instead. If no valid target is found within range, the module idles. A ship with multiple repair modules can therefore heal different targets simultaneously. Navigation is driven solely by the behavior-level target; individual module fallback targets do not affect which direction the ship moves. Repair healing is a world-state change applied every tick regardless of which behavior the ship is currently executing.

• REQ-SHP-RETREAT: Player ships retreat to the rally point (REQ-SHP-RALLY) when threatened. A ship retreats while either condition holds: (a) its HP is below a low-HP threshold (currently 30% of its maximum HP); or (b) it has no weapon modules and an enemy ship is within its sensor range. Retreating takes priority over the ship's other behaviors and moves it toward the rally point; the ship resumes its normal behavior once neither condition holds. Enemy ships never retreat (REQ-SHP-ENEMY-AI).

• REQ-SHP-ENEMY-AI: Enemy ships — engage the closest valid target (player defence station, HQ, or player ship) within their sensor range, orbiting the engaged target at the combat orbit radius (REQ-SHP-ORBIT). If no target is in sensor range, they move toward the asteroid (leftward in world coordinates).

• REQ-SHP-TARGET-SELECT: Combat target selection. Both player combat ships (REQ-SHP-COMBAT) and enemy ships (REQ-SHP-ENEMY-AI) pick which hostile to engage by scoring every valid target (an opposing-faction ship, defence station, or HQ) within sensor range and engaging the highest-scoring one. A target's score is the product of a base desirability and an overclaim penalty (REQ-SHP-TARGET-CLAIM). The base desirability is world.toml [targeting].target_score_formula evaluated with x set to the target's distance from the ship divided by the ship's maximum weapon attack_range (falling back to sensor range for a ship with no weapon), clamped to a minimum of 0. The default formula 1 / (1 + x) decreases with distance, so — absent any claims — the nearest target is chosen, realizing the closest-target priority referenced by REQ-SHP-COMBAT and REQ-SHP-ENEMY-AI. A ship engages at most one target at a time; all of its weapons fire on that target subject to their own range and rate checks (REQ-SHP-FIRING).

• REQ-SHP-TARGET-CLAIM: Overclaim penalty. To stop every ship from dogpiling the same hostile, each target a ship is currently engaging counts as a claim on that target. When scoring a candidate, its base desirability (REQ-SHP-TARGET-SELECT) is multiplied by world.toml [targeting].overclaim_penalty_formula evaluated with x set to the number of ships currently claiming that candidate — a ship never counts its own claim against the target it already holds — clamped to the range [0, 1]. The penalty is 1 (no reduction) at zero claims and decreases as claims accumulate, so heavily-claimed targets become less attractive and ships spread across the available hostiles. The default formula max(0.5, 1 - 0.1*x) reduces desirability by 0.1 per claim down to a floor of 0.5. Because claims reflect the previous tick's engagements, target distribution converges over successive ticks rather than instantaneously.

• REQ-SHP-TARGET-HYSTERESIS: Target stickiness. A ship keeps engaging its current target as long as that target remains valid and within sensor range, switching to a different target only when the best alternative's score exceeds the current target's score by more than the fractional margin world.toml [targeting].target_hysteresis (default 0.10). This prevents ships from rapidly oscillating between targets of near-equal score and preserves focus fire.

• REQ-SHP-SCHEMATICS: The player selects a schematic per shipyard by clicking it. New schematics are unlocked by destroying enemy defence station sets (REQ-DEF-SCHEMATIC-DROP) — there is no physical loot to collect.

Ship Modules

Module Configuration

• REQ-MOD-CONFIG: Module types are defined in modules.toml. Each module entry specifies:

  • id — unique identifier, also used as the display name in the UI.
  • surface_mask — footprint within the ship layout grid (see Module Surface Mask Format).
  • materials — list of materials required per instance (added to the ship's build cost).
  • player_production_level — initial level for this module type; used as x in its stat formulas. Incremented by 1 on each duplicate schematic drop (REQ-DEF-SCHEMATIC-DROP).
  • unlock_at_station_level — the enemy defence station level at which this module's schematic becomes available for unlock; -1 means the player starts with the module schematic already unlocked.
  • production_time_seconds — time added to the ship's production cycle per instance.
  • fill_color — fill color used to render this module's cells in the layout grid.
  • glyph — single character rendered on this module's cells in the layout grid and preview widget.
  • An optional capability section ([module.weapon], [module.salvage], or [module.repair]) containing base stat formulas. A module with base stat formulas is a capability module — each placed instance grants the ship an independent weapon, salvage bay, or repair tool with its own state (cooldown, target, cargo). A ship may have multiple capability module instances of the same or different types. Base stat formulas per capability type:
    • Weapon ([module.weapon]): damage_formula, attack_range_formula, attack_rate_formula.
    • Salvage ([module.salvage]): collection_range_formula (tiles), cargo_capacity_formula (integer scrap units), collection_rate_formula (collections per second).
    • Repair ([module.repair]): repair_rate_formula (HP/s), repair_range_formula (tiles).
  • Zero or more passive stat modifier formulas (added_*/multiplied_*) that boost stats on the ship hull or on capability module instances (see REQ-MOD-STAT-CALC). A single module may be both a capability module and provide passive modifiers.

• REQ-MOD-LAYOUT: Each ship in ships.toml defines a layout — a list of strings representing the ship's module grid (see Ship Layout Format). All ships define a layout.

Module Placement

• REQ-MOD-PLACEMENT: In the layout configuration dialog (REQ-MOD-UI-DIALOG), the player places modules onto the ship's layout grid. Clicking a module button in the module selection grid enters module placement mode for that module type. While in placement mode, a ghost of the module's surface mask is rendered at the cell under the cursor. Clicking a valid position places one instance of the module. A position is valid if every O cell in the module's (rotated) surface mask coincides with an unoccupied buildable cell of the ship's layout. The player may place unlimited instances of the same module type.
• REQ-MOD-ROTATION: While in module placement mode, pressing Q rotates the module ghost 90° counter-clockwise and E rotates it 90° clockwise. Rotation transforms the surface mask grid identically to building rotation (REQ-BLD-ROTATE).
• REQ-MOD-REMOVE: The module selection grid includes a "Remove" button. Clicking it enters remove mode. In remove mode, clicking on a cell occupied by a placed module removes that entire module instance from the layout. Remove mode is exited by clicking the Remove button again or by selecting a module for placement.

Module Effects

• REQ-MOD-MATERIALS: The total materials required to build a ship are the union of the ship's base [ship.schematic].materials and the materials of every module instance in the configured layout. Quantities of the same item type are summed.

• REQ-MOD-PRODUCTION-TIME: The total production time is the ship's base [ship.schematic].production_time_seconds plus the sum of production_time_seconds for every module instance in the configured layout.

• REQ-MOD-THREAT: The threat cost of a ship is dynamically derived from the accumulated total production time required to produce that ship from scratch. One second of production time equals one threat. The total production time is the sum of:

  1. The ship's base production_time_seconds.
  2. The production_time_seconds of every module instance in the configured layout.
  3. For every material required (the union of the ship's base materials and all module instance materials, with quantities summed per item type): the recursive production time of that material multiplied by the required quantity (see REQ-THREAT-ITEM).

• REQ-THREAT-ITEM: The threat value of an item type (in seconds) is determined by the recipe that produces it:

  • Miner recipe: the recipe's duration_seconds.
  • Smelter recipe: the recipe's duration_seconds plus the sum of each input's threat value multiplied by that input's required quantity.
  • Assembler recipe: the recipe's duration_seconds plus the sum of each input's threat value multiplied by that input's required quantity.
  • Reprocessing-only item (an item type that has no miner, smelter, or assembler recipe producing it, and is only obtainable via reprocessing): (scrap_threat × scrap_per_cycle + duration_seconds) / probability, where scrap_threat is the threat value of scrap (see REQ-THREAT-SCRAP), scrap_per_cycle is the number of scrap consumed per reprocessing cycle, duration_seconds is the reprocessing cycle time, and probability is the normalized weight of that item in the reprocessing output pool.
  • Multiple recipes: if an item type can be produced by more than one non-reprocessing recipe (miner, smelter, or assembler), its threat value is the maximum across all such recipes. The reprocessing path is only used when no other recipe exists.

• REQ-THREAT-SCRAP: The threat value of scrap is derived from the ship schematic with the smallest configured scrap_drop value (from ships.toml [ship.loot].scrap_drop). Scrap threat = that ship's threat cost (REQ-MOD-THREAT) / that ship's scrap_drop value. If multiple schematics share the same smallest scrap_drop, any one of them may be used.

• REQ-MOD-STAT-CALC: For each stat (on the ship hull or on a capability module instance), the final value is computed as: final = base × total_multiplier + total_additive, where:

  • base is the stat's base formula evaluated at the ship's production level (for hull stats) or at the capability module's player_production_level (for capability module stats).
  • total_multiplier = 1 + sum of (m_i − 1) for each multiplicative modifier m_i from all passive module instances. Each m_i is evaluated from the module's multiplicative formula at the module's player_production_level.
  • total_additive = sum of all additive modifier values from all passive module instances. Each additive value is evaluated from the module's additive formula at the module's player_production_level.

  Passive modifier formulas follow the naming convention: a module may define added_<stat>_formula (additive) and/or multiplied_<stat>_formula (multiplicative) under [module.<category>]. The category determines what the modifier targets:

  • [module.health], [module.movement], [module.sensor] — modifiers apply to the ship hull's stats.
  • [module.weapon] — modifiers apply to every weapon module instance on the ship.
  • [module.salvage] — modifiers apply to every salvage module instance on the ship.
  • [module.repair] — modifiers apply to every repair module instance on the ship.

  Example: [module.sensor].added_sensor_range_formula adds to the ship's sensor range. [module.weapon].multiplied_damage_formula multiplies the damage of every weapon module instance on the ship.

Module UI

• REQ-MOD-UI-PREVIEW: When a schematic is selected in a shipyard's selected building panel, a small non-interactive ship layout preview widget is shown below the schematic dropdown. The preview renders the ship's layout grid at a reduced scale: buildable cells without a module are shown as white, non-buildable cells are shown as black, and cells occupied by a module are shown in that module's fill_color with the module's glyph character. Below the preview, a "Configure" button is shown.

• REQ-MOD-UI-DIALOG: Clicking the "Configure" button opens the layout configuration dialog as a modal. While the dialog is open, the game is paused (speed set to 0×). On close, the game speed is restored to what it was before the dialog was opened.

  The dialog contains:

  • Top: The ship's layout grid rendered at full scale. Buildable cells are white; non-buildable cells are black. Placed modules are rendered with their fill_color and glyph. The ghost of the currently selected module is shown at the cursor position when in placement mode.
  • Left (below the grid): The ship stats panel (see REQ-MOD-UI-STATS-PANEL).
  • Center (below the grid): A grid of module selection buttons (one per unlocked module type; see REQ-DEF-SCHEMATIC-DROP) plus a "Remove" button. Each module button shows the module id and its glyph.
  • Right (below the grid): The layout blueprint panel (see REQ-MOD-UI-BLUEPRINT-PANEL through REQ-MOD-UI-BLUEPRINT-FILE-LOAD).
  • Bottom: A "Confirm" button and a "Cancel" button. Cancel discards all changes made in this dialog session and closes the dialog. Confirm applies the changes: the shipyard's configured layout is updated, the required materials and cycle time displayed in the selected building panel are recalculated, and the ship layout preview is refreshed.

• REQ-MOD-UI-STATS-PANEL: The ship stats panel in the layout configuration dialog shows the stats of the currently configured ship layout as they would be computed at the schematic's player_production_level, incorporating all passive module modifiers per REQ-MOD-STAT-CALC. The panel updates in real time whenever modules are placed or removed in the layout grid.

  The panel always shows all hull stats as final computed values:

  • HP
  • Max linear speed
  • Sensor range
  • Main acceleration
  • Maneuvering acceleration
  • Angular acceleration
  • Max rotation speed

  In addition, the panel shows capability module stats conditioned on which capability module types are present in the current layout:

  • Weapons (shown only if at least one weapon module is placed): combined DPS = Σ(damage_i × attack_rate_i) across all weapon module instances; maximum range = max(attack_range_i) across all weapon module instances.
  • Salvage (shown only if at least one salvage module is placed): combined collection rate = Σ(collection_rate_i) across all salvage module instances; maximum range = max(collection_range_i) across all salvage module instances.
  • Repair (shown only if at least one repair module is placed): combined repair rate = Σ(repair_rate_i) across all repair module instances; maximum range = max(repair_range_i) across all repair module instances.

  All capability module stat values incorporate passive modifiers targeting the relevant capability category per REQ-MOD-STAT-CALC. Each capability module instance uses its own player_production_level for formula evaluation.

  While debug draw mode is active (REQ-UI-DEBUG-DRAW), the panel additionally shows the ship's derived threat cost (REQ-MOD-THREAT) for the current layout configuration. This value updates in real time as modules are placed or removed.

• REQ-MOD-UI-LAYOUT-SIZE: Ship layouts are small enough to display in the layout configuration dialog without scrolling (maximum grid size fits within the dialog).

Layout Blueprints

• REQ-MOD-UI-BLUEPRINT-PANEL: The right column of the layout configuration dialog is the layout blueprint panel. It shows only blueprints whose ship_type matches the schematic of the shipyard for which the dialog was opened. The panel contains, from top to bottom: a "Create Blueprint" button, followed by a scrollable list of blueprint entries (one per matching blueprint, in creation order).

• REQ-MOD-UI-BLUEPRINT-CREATE: Clicking "Create Blueprint" opens a modal dialog prompting for a name. The dialog has Confirm and Cancel buttons. Clicking Cancel closes the dialog with no effect. Clicking Confirm with a non-empty name creates a blueprint from the module layout currently shown in the left-side layout grid (the in-progress state of the dialog, not the previously confirmed shipyard layout) and appends it to the blueprint list.

• REQ-MOD-UI-BLUEPRINT-ENTRY: Each blueprint entry shows the blueprint name and a delete icon ("×") to the right of the name. Clicking the entry (name area) loads that blueprint's module list into the left-side layout grid, replacing all currently placed modules. Module instances that are invalid for the current ship layout (unknown module type, locked module type, position outside the grid, position on a non-buildable cell, or overlapping another module in the same blueprint) are silently skipped; the remaining valid instances are placed. Clicking the delete icon ("×") removes that blueprint entry from the list immediately.

• REQ-MOD-UI-BLUEPRINT-STARTUP: At application startup, layout blueprints are loaded from ship_layouts.toml in the same directory as the application executable. Blueprint entries missing required fields (name or ship_type) are silently skipped. If the file does not exist, the blueprint list starts empty with no error. If the file exists but cannot be parsed (malformed TOML), a modal error dialog describes the failure and the blueprint list starts empty.

• REQ-MOD-UI-BLUEPRINT-SHUTDOWN: On application shutdown, all layout blueprints (across all ship types) are written to ship_layouts.toml in the same directory as the application executable. The TOML structure matches the Layout Blueprint TOML Format. Write errors are silently ignored on shutdown.

Defence Stations

• REQ-DEF-PLAYER-PLACEMENT: 2 player defence stations are pre-placed in space at the start. Their positions are determined by world.toml [regions].asteroid_width and player_buffer_width.

• REQ-DEF-PLAYER-FIRE: Player defence stations automatically fire at approaching enemy ships. Stats are defined as formulas of a fixed station level (stations.toml [player_station].level) in stations.toml [player_station]: hp_formula, damage_formula, range_formula, fire_rate_formula, scrap_drop_formula.

• REQ-DEF-PLAYER-DESTRUCTIBLE: Player defence stations can be destroyed by enemies and repaired by repair ships.

• REQ-DEF-ENEMY-PLACEMENT: 2 enemy defence stations are placed at the right boundary of the scrollable area at game start, and again each time a new set is spawned after a push. Stats scale with the station level (REQ-PSH-STATION-STATS).

• REQ-DEF-ENEMY-FIRE: Enemy defence stations automatically fire at player ships within range.

• REQ-DEF-NO-CROSSFIRE: Enemy and player defence stations are never in each other's firing range.

• REQ-DEF-PUSH: When both enemy defence stations in a set are destroyed, the boss countdown is advanced (REQ-WAV-BOSS-ADVANCE), the scrollable area is extended (REQ-GW-PUSH-EXPAND), a new set of enemy defence stations is placed at the new boundary, and exactly one schematic drop is awarded for the destroyed set (REQ-DEF-SCHEMATIC-DROP).

• REQ-DEF-SCHEMATIC-DROP: Each destroyed set of enemy defence stations awards exactly one schematic drop (not one per station). The drop opens a schematic choice dialog — a modal dialog that pauses the game (speed set to 0×; on close, speed is restored to what it was before the dialog opened). Up to three schematic options are drawn uniformly at random without replacement from the eligible drop pool. If the pool contains fewer than three entries, only that many options are shown. The eligible drop pool contains:

  • All ship schematics and module schematics whose unlock_at_station_level is -1 or is ≤ the level of the destroyed station set.
  • All assembler recipe schematics whose unlock_at_station_level is ≥ 0 and ≤ the level of the destroyed station set, whose output item is currently implicitly unlocked (REQ-LOCK-IMPLICIT), and which have not yet been awarded.

  Each option in the dialog displays: the schematic name (ship display_name from ships.toml, module id from modules.toml, or the output item type for assembler recipes), the schematic type (ship, module, or assembler recipe), and whether selecting it would be a new unlock or a level-up (showing the target level for level-ups). Assembler recipe schematics are always new unlocks since they are removed from the pool once awarded.

  Each option additionally displays a vertical list of item names labeled "Unlocks recipes for:", showing which recipes would newly become implicitly unlocked (REQ-LOCK-IMPLICIT) if this option were selected — specifically, the output items of miner recipes and assembler recipes (without unlock_at_station_level) that are not currently implicitly unlocked but would become so after applying this option's effect:

  • For a ship or module schematic that would be a new unlock, its materials are added to the base set per REQ-LOCK-IMPLICIT step 1a before recomputation.
  • For a ship or module schematic level-up, the implicit unlock set is unchanged, so the list is always empty.
  • For an assembler recipe schematic, its output item is added to the base set per REQ-LOCK-IMPLICIT step 1b before recomputation.

  Item names are deduplicated and sorted alphabetically. If no recipes would be newly unlocked, the list shows "None".

  The player selects one option by clicking it. The selected schematic is applied and the dialog closes:

  For a ship or module schematic: if the player does not yet have the schematic, it is unlocked (ship schematics unlock the corresponding shipyard selection; module schematics unlock the module type for placement in the layout configuration dialog (REQ-MOD-UI-DIALOG)). If the player already has it, the schematic's player_production_level is incremented by 1 — for ship schematics, subsequent ships of that type are produced at a higher level; for module schematics, all instances of that module type use the higher level in their stat formulas.

  For an assembler recipe schematic: the recipe is explicitly unlocked and becomes available in the assembler recipe-selection dropdown (subject to REQ-LOCK-UI-RECIPE). The schematic is removed from the drop pool permanently (REQ-LOCK-EXPLICIT). The implicit unlock set is recomputed (REQ-LOCK-IMPLICIT).

Progression & Locking

• REQ-LOCK-EXPLICIT: Ship schematics, module schematics, and assembler recipe schematics (assembler recipes in recipes.toml that define unlock_at_station_level) are explicitly locked or unlocked. A schematic starts unlocked if its unlock_at_station_level is -1; all others start locked. Locked schematics are unlocked only by REQ-DEF-SCHEMATIC-DROP. Once unlocked, a schematic is never re-locked within a run; lock states reset to their initial values on Restart (REQ-CFG-RELOAD). Unlike ship and module schematics, an assembler recipe schematic is removed from the drop pool permanently once awarded and cannot be dropped again.

• REQ-LOCK-IMPLICIT: Item types and miner/assembler recipes are implicitly unlocked or locked based on the current set of unlocked ship, module, and assembler recipe schematics. The implicit unlock set is recomputed whenever any schematic changes lock state (on Restart or after REQ-DEF-SCHEMATIC-DROP). Computation:

  1. Start with the union of: (a) all item types listed in materials across all currently unlocked ship schematics and all currently unlocked module schematics, and (b) the output item type of every currently explicitly unlocked assembler recipe schematic (REQ-LOCK-EXPLICIT).
  2. For each item type in the current set: for every recipe (miner, smelter, or assembler) that produces it — skipping any assembler recipe schematic that defines unlock_at_station_level and is not yet explicitly unlocked — add each of that recipe's input item types to the set. If the recipe is a miner recipe or an assembler recipe that does not define unlock_at_station_level, mark it as implicitly unlocked. Explicitly unlocked assembler recipe schematics are available in the assembler dropdown by virtue of REQ-LOCK-EXPLICIT; their inputs are also added to the implicit set in this step.
  3. Repeat step 2 until no new item types are added. Item types and miner/assembler recipes not reached by this process (and not explicitly unlocked) are locked. Smelter recipes participate in the traversal to propagate unlocking to their inputs but are never themselves shown in any UI dropdown.

• REQ-LOCK-REPROCESSING-POOL: The pool of possible outputs for a Reprocessing Plant cycle (REQ-BLD-REPROCESSING) is restricted to item types that are currently implicitly unlocked (REQ-LOCK-IMPLICIT). Weights are renormalized over the eligible outputs. If no eligible outputs remain, the Reprocessing Plant cannot start a production cycle.

• REQ-LOCK-UI-RECIPE: Locked miner ore-type recipes and assembler recipes are not shown in their respective recipe-selection dropdowns.

• REQ-LOCK-UI-SCHEMATIC: Locked ship schematics are not shown in the shipyard's schematic-selection dropdown.

• REQ-LOCK-UI-SPLITTER: Item types that are not implicitly unlocked are excluded from splitter filter dropdowns (REQ-BLD-SPLITTER).

• REQ-LOCK-UI-BLUEPRINT: When a blueprint is placed (REQ-UI-BLUEPRINT-PLACE): if a stored recipe ID for a miner or assembler is currently locked, that building's recipe is left unset rather than applied; if a stored splitter filter entry refers to a locked item type, that entry is silently removed. (The analogous rule for locked ship schematics is defined in REQ-UI-BLUEPRINT-PLACE.)

Threat Level & Enemy Waves

• REQ-WAV-BOSS-COUNTER: A global boss wave counter x starts at 1 at game start and increments by 1 immediately after each boss wave fires. It represents the current boss wave cycle number and is used as the variable in the threat rate and ship level formulas.
• REQ-WAV-THREAT-RATE: A global threat level accumulates continuously over real game time. The rate of increase per second is determined by world.toml [waves].threat_rate_formula where x is the boss wave counter (REQ-WAV-BOSS-COUNTER), clamped to a minimum of 0 (negative formula values are treated as 0). The rate is constant within each boss wave cycle and steps up each time x increments. Threat accumulation is paused during quiet windows (REQ-WAV-QUIET). Example: 1*x - 30 yields 0 threat/s when x ≤ 30 and increases linearly beyond that.
• REQ-WAV-GAP: At game start and immediately after each normal wave is triggered, a random inter-wave gap is drawn uniformly from [world.toml [waves].gap_min_seconds, gap_max_seconds]. The gap timer does not advance while inside a quiet window (REQ-WAV-QUIET); if a gap would expire inside a quiet window, its expiry is deferred until the quiet window ends.
• REQ-WAV-TRIGGER: When the gap timer expires outside a quiet window, a normal wave is triggered. Ships are selected one at a time: from all schematics whose threat cost (REQ-MOD-THREAT) is > 0, uniformly randomly pick one whose cost fits the remaining threat budget. For wave ship selection, the threat cost is computed using the schematic's default_modules layout (REQ-WAV-DEFAULT-MODULES). Repeat until no eligible schematic fits. Any remaining threat carries over to the next normal wave. A longer gap results in a larger wave.
• REQ-WAV-SHIP-LEVEL: Each wave's (normal and boss) enemy ships are assigned a level determined by world.toml [waves].ship_level_formula where x is the boss wave counter (REQ-WAV-BOSS-COUNTER). Per-ship stats are computed from the ship level via the formulas in ships.toml (see REQ-SHP-STATS). Threat cost is level-independent (REQ-MOD-THREAT).
• REQ-WAV-BOSS-COUNTDOWN: A boss countdown timer starts at world.toml [waves].boss_countdown_seconds (default 300) at game start and counts down continuously in real game-time seconds. It is not paused during quiet windows. When it reaches 0, a boss wave is triggered (REQ-WAV-BOSS-TRIGGER). Immediately after the boss wave fires, x increments (REQ-WAV-BOSS-COUNTER) and a fresh countdown starts at the same configured value.
• REQ-WAV-BOSS-ADVANCE: When the player destroys a set of enemy defence stations, the boss countdown is reduced by world.toml [push].boss_advance_seconds (default 60), clamped to a minimum of 0. Threat that would have accumulated during the skipped time is not added. If the countdown reaches 0 by this reduction, the boss wave is triggered immediately.
• REQ-WAV-QUIET: A quiet window suppresses normal wave spawning around each boss wave. The pre-boss quiet window begins when the boss countdown falls to or below world.toml [waves].boss_quiet_before_seconds and ends when the countdown reaches 0. The post-boss quiet window begins immediately when the boss wave fires and lasts world.toml [waves].boss_quiet_after_seconds seconds. Threat accumulation is paused during both windows. The normal wave gap timer does not advance during either window (REQ-WAV-GAP). The new boss countdown runs during the post-boss quiet window.
• REQ-WAV-BOSS-TRIGGER: When the boss countdown reaches 0, a boss wave is triggered. Its threat budget is the sum of: (a) world.toml [waves].boss_threat_duration_seconds (default 60) multiplied by the current threat rate, and (b) all unspent threat carried over from normal waves. Ships are selected using the same random process as normal waves (REQ-WAV-TRIGGER). Any threat remaining unspent after ship selection carries over to the first normal wave of the new cycle.
• REQ-WAV-DEFAULT-MODULES: Enemy ships spawned by waves use the default_modules list defined per schematic in ships.toml. The default_modules array uses the same format as layout blueprints (see Layout Blueprint TOML Format). If default_modules is absent or empty, the ship spawns with no modules. Invalid module instances (unknown type, position outside the grid, position on a non-buildable cell, or overlapping another module) are silently skipped.
• REQ-WAV-SPAWN-DURATION: Ships in a wave are spawned one at a time over world.toml [waves].spawn_duration_seconds.

Push Effects

• REQ-PSH-STATION-STATS: Enemy defence station stats are each defined as formulas in stations.toml [enemy_station]: hp_formula, damage_formula, range_formula, fire_rate_formula, scrap_drop_formula, where x is the station level — an integer starting at 0 for the initial set and incrementing by 1 each time a new set is placed.

Asteroid Expansion

• REQ-EXP-UNLOCK: The player can unlock additional asteroid tile columns to the left of the existing asteroid by spending building blocks from the global stock.
• REQ-EXP-COST: Each expansion adds world.toml [expansion].columns_per_expansion columns and costs [expansion].cost_building_blocks building blocks.

UI

Layout

The screen is divided into two columns: a main column (75% width) containing the header bar and game world, and a side panel column (25% width) containing the three UI panels stacked vertically:

+--------------------------------------+--------------+
|             Header Bar               |              |
+--------------------------------------+  Selected    |
|                                      |  Building    |
|                                      |  Panel       |
|                                      +--------------+
|           Game World                 |  Build       |
|                                      |  Button      |
|                                      |  Grid        |
|                                      +--------------+
|                                      |  Blueprint   |
|                                      |  Panel       |
+--------------------------------------+--------------+
           (75% width)                   (25% width)

• REQ-UI-HEADER: The header bar spans the width of the game world column (75% of the screen width) and always shows the elapsed survival time and the current global building blocks stock on the left, the boss wave counter and boss countdown (REQ-UI-BOSS-STATUS) to the left of the speed buttons, and game speed controls on the right.
• REQ-UI-BOSS-STATUS: The header bar displays, to the left of the speed buttons, the current boss wave counter (REQ-WAV-BOSS-COUNTER) and the time remaining on the boss countdown (REQ-WAV-BOSS-COUNTDOWN). The boss wave counter is shown as Boss Wave #<x> and the countdown as Next boss: <M:SS>, where <M:SS> is the remaining seconds formatted as whole minutes and two-digit seconds. Both values update continuously as the simulation runs.
• REQ-UI-SPEED: The game speed controls in the header bar are buttons for 0×, 0.5×, 1×, 2×, and 4× speed. The currently active speed is shown as selected. All game simulation (production, movement, threat accumulation, wave timing) scales with the selected speed. 0× pauses the game.
• REQ-UI-WORLD-SIZE: The game world view occupies the full height below the header bar in the main column (75% of the screen width).
• REQ-UI-PANEL-COLUMN: The side panel column occupies 25% of the screen width and the full screen height. It is divided into three equal-height panels stacked top to bottom: selected building panel (top), build button grid (middle), and blueprint panel (bottom).

Game World

• REQ-UI-SCROLL: The player scrolls the view horizontally across the scrollable area by pressing A (scroll left) and D (scroll right).
• REQ-UI-CONSTRUCTION-PROGRESS: Construction sites display the building's glyph centered on the footprint (same as an operational building). Below the glyph — or centered on the footprint if the building has no glyph — a construction progress percentage is shown (integer, e.g. 42%), increasing from 0% to 100% as construction completes.
• REQ-UI-PORT-GLYPH: Every output port of every building is indicated by a directional glyph drawn on the port's tile. The glyph is a > rotated to face the port's exit direction (> for East, ^ for North, < for West, v for South). It is drawn at the midpoint between the tile center and the tile edge that the port exits through (i.e. halfway from center toward the exit edge). The indicator is rendered for all building states: operational buildings, construction sites, and the builder-mode ghost. Buildings with multiple output ports (e.g. splitters) show one indicator per port.
• REQ-UI-HP-BARS: All entities with HP — the HQ, player and enemy defence stations, and player and enemy ships — render an HP bar below them. The bar is always visible regardless of current HP. The bar's filled portion represents the fraction of current HP to maximum HP.
• REQ-UI-NO-ZOOM: The view has a fixed zoom level; the player cannot zoom in or out.
• REQ-UI-HOTKEYS: Global keyboard shortcuts:
  • Space — toggles pause. Pressing Space pauses (sets speed to 0×) and stores the previously selected non-zero speed; pressing Space again restores that speed.
  • W — increases game speed by one step in the sequence 0×, 0.5×, 1×, 2×, 4× (no wrap-around past 4×).
  • S — decreases game speed by one step in the same sequence (no wrap-around past 0×).
  • Backspace — activates demolish mode; Backspace again exits it. (See also REQ-UI-DEMOLISH-BUTTON for the equivalent button.)
  • Q / E — in builder mode, rotate the ghost counter-clockwise / clockwise (REQ-BLD-ROTATE).
  • Escape — opens the escape menu (REQ-UI-GAME-MENU).
  • M — toggles debug draw mode (REQ-UI-DEBUG-DRAW).

Debug Draw

• REQ-UI-DEBUG-DRAW: A debug draw mode can be toggled on and off with the M key (REQ-UI-HOTKEYS). It is inactive by default. While active, the sensor range of every ship — both player and enemy — is drawn as a circle centered on the ship, using that ship schematic's outline color from visuals.toml.

• REQ-UI-DEBUG-OVERLAY: While debug draw mode is active (REQ-UI-DEBUG-DRAW), a text overlay is drawn in the upper left corner of the game world view. The overlay has a semi-transparent black background sized to fit its content. It displays the following lines of text:

  • Accumulated Threat Level: <level> — where <level> is the current accumulated threat level (see REQ-WAV-THREAT-RATE).
  • Time until Wave: <time_s> — where <time_s> is the remaining time in seconds on the normal-wave inter-wave gap timer (see REQ-WAV-GAP). During a quiet window the gap timer is frozen; the displayed value reflects that frozen state.
  • Threat Accumulation Rate: <rate> threat/s — the rate at which the accumulated threat level is currently increasing (see REQ-WAV-THREAT-RATE). During a quiet window (REQ-WAV-QUIET), this is 0, reflecting that accumulation is currently paused.
  • Max Factory Production: <rate> threat/s — the threat-equivalent of the factory's total possible production: 1 threat/second for each completed (operational, not under construction) miner, smelter, assembler, reprocessing plant, and shipyard. One second of production equals one threat (see REQ-MOD-THREAT).
  • Current Factory Production: <rate> threat/s — the threat-equivalent of the factory's current production: 1 threat/second for each completed miner, smelter, assembler, reprocessing plant, or shipyard that currently has an active production cycle (see REQ-MAT-CYCLE; for shipyards, an in-progress production cycle per REQ-BLD-SHIPYARD).

Escape Menu

• REQ-UI-GAME-MENU: Pressing Escape at any time opens the escape menu as a modal dialog and pauses the simulation (sets speed to 0×). On close, the simulation speed is restored to what it was before the menu was opened — so if the game was already paused, it remains paused. The menu contains three buttons:
  • Continue — closes the menu and returns to the game.
  • Restart — resets the simulation to its initial state and closes the menu at 1× speed.
  • Quit — closes the application. Pressing Escape while the escape menu is open is equivalent to clicking Continue.

Selected Building Panel

• REQ-UI-EMPTY-SELECTION: When no building is selected, the panel is empty.
• REQ-UI-SINGLE-SELECTION: When one building is selected, the panel shows: building name, current recipe or schematic selection, input buffer contents, and output buffer contents. Buffer counts are displayed as a/b where a is the current item count and b is the per-cycle amount (items consumed per run for inputs; items produced per run for outputs).
• REQ-UI-PRODUCTION-PROGRESS: For buildings that produce items or ships (miner, smelter, assembler, reprocessing plant, shipyard), the selected building panel also shows: (a) the cycle time of the currently selected recipe or schematic in seconds, and (b) the completion percentage of the active production cycle as an integer (e.g. 42%), or the text idle when no production cycle is active. When no recipe or schematic is selected, neither the cycle time nor the progress indicator is shown.
• REQ-UI-MULTI-SELECT: The player selects multiple buildings by box-drag or by Ctrl+clicking individual buildings to add or remove them from the selection.
• REQ-UI-MULTI-SELECTION: When multiple buildings are selected, the panel shows how many of each building type are selected. No per-building detail is shown.
• REQ-UI-CONFIG-INLINE: Recipe, schematic, ship stance, and target priority configuration for a selected building is shown and changed inline within this panel. For shipyards, the panel additionally shows the ship layout preview and "Configure" button below the schematic dropdown (REQ-MOD-UI-PREVIEW).
• REQ-UI-BELT-CLEAR: When one or more belt, splitter, tunnel entry, or tunnel exit tiles are selected, the panel shows a "Clear" button that removes all items from the selected tiles. Clearing a tunnel entry or exit also discards all items currently in transit through that tunnel (REQ-BLD-TUNNEL-TRANSIT). This can be used to resolve stalled belts, splitters, and tunnels.
• REQ-UI-ENTITY-CLICK-SELECT: The player can click any ship (player or enemy) or any defence station (player or enemy) in the game world to select it. Clicking a ship or defence station clears any existing selection and establishes a single-entity selection containing only that entity. Ships and defence stations cannot participate in multi-select together with buildings. Clicking empty world space (no building, ship, or defence station) clears the selection.
• REQ-UI-SHIP-STATS-PANEL: When a single ship is selected (REQ-UI-ENTITY-CLICK-SELECT), the selected building panel shows a ship stats panel. The panel structure mirrors REQ-MOD-UI-STATS-PANEL but reflects the ship's actual live state: stats are computed at the ship's actual level with its installed modules per REQ-MOD-STAT-CALC. The panel always shows all hull stats: HP (current / maximum), max linear speed, sensor range, main acceleration, maneuvering acceleration, angular acceleration, and max rotation speed. In addition, capability module summaries are shown conditioned on which module types are installed, using the same aggregation rules as REQ-MOD-UI-STATS-PANEL: weapons (combined DPS, maximum range), salvage (combined collection rate, maximum range), and repair (combined repair rate, maximum range), each section appearing only if at least one instance of that module type is installed. While debug draw mode is active (REQ-UI-DEBUG-DRAW), the panel additionally shows the ship's derived threat cost (REQ-MOD-THREAT).
• REQ-UI-STATION-STATS-PANEL: When a single defence station is selected (REQ-UI-ENTITY-CLICK-SELECT), the selected building panel shows a station stats panel displaying the station's stats computed at its current level: HP (current / maximum), damage, range, and fire rate.

Build Button Grid

• REQ-UI-BUILD-GRID: All placeable building types are shown as a flat grid of buttons with no grouping.
• REQ-UI-BUILD-COST: Each button caption shows the building name and its building block cost, e.g. "Belt: 2 Blocks".
• REQ-UI-BUILD-DISABLED: Buttons for buildings the player cannot currently afford are shown as disabled.
• REQ-UI-DEMOLISH-BUTTON: A dedicated Demolish button is shown in the build button grid. Clicking it toggles demolish mode on and off, equivalent to pressing Backspace (REQ-UI-HOTKEYS). The button is shown in a visually active/pressed state while demolish mode is active.

Blueprint Panel

• REQ-UI-BLUEPRINT-PANEL: The blueprint panel is shown to the right of the build button grid. It contains, from top to bottom: a "Create Blueprint" button, and a list of blueprint entries (one per saved blueprint, in creation order).

• REQ-UI-BLUEPRINT-CREATE: The "Create Blueprint" button is enabled only when at least one player-placeable building (i.e. a building with a button in the build button grid) is currently selected; non-player-placeable buildings (HQ, defence stations) in the selection do not count toward this condition. When clicked, a modal dialog appears prompting the player to enter a name. The dialog has Confirm and Cancel buttons. Clicking Cancel closes the dialog with no effect. Clicking Confirm with a non-empty name creates a blueprint from the current selection, silently excluding any non-player-placeable buildings, and appends its button to the blueprint list.

• REQ-UI-BLUEPRINT-STORAGE: A blueprint stores its name and, for each building in the selection, the building type, its rotation, its tile offset (integer dx, dy) from the center of the bounding box of all selected buildings' footprints, and — where applicable — the selected recipe ID (miners and assemblers) or schematic ID (shipyards) at the time of capture. If no recipe or schematic was selected at capture time, none is stored. This structure maps directly to a TOML representation (e.g. one [[building]] array entry per constituent building).

• REQ-UI-BLUEPRINT-BUTTON: Each blueprint entry consists of a blueprint button and a dedicated delete icon ("×") placed to the right of the button. The blueprint button displays the blueprint name and, below it, the total building block cost of the blueprint (sum of the individual costs of all constituent buildings). A blueprint button is disabled when the player cannot afford the total cost. Clicking an enabled blueprint button enters blueprint placement mode for that blueprint. The delete icon is always enabled regardless of whether the player can afford the blueprint.

• REQ-UI-BLUEPRINT-MODE: In blueprint placement mode a ghost is rendered for every building in the blueprint at the position determined by its stored tile offset from the bounding-box center, which is anchored to the tile under the cursor. Each ghost is rendered individually as valid or invalid, applying REQ-BLD-PLACE-VALID conditions (a) and (b) per building (the other ghosts in the same blueprint do not count as existing buildings for the overlap check). Pressing Q/E rotates the entire constellation 90° counter-clockwise / clockwise: each building's tile offset is rotated around the bounding-box center and each building's own rotation is updated, consistent with REQ-BLD-ROTATE. Blueprint placement mode is exited by right-clicking in the game world. Clicking a different blueprint button exits the current mode and enters blueprint placement mode for the newly clicked blueprint.

• REQ-UI-BLUEPRINT-PLACE: Left-clicking in blueprint placement mode places the blueprint if (a) every building in the constellation satisfies REQ-BLD-PLACE-VALID conditions (a) and (b) at its resolved tile, and (b) the player has enough building blocks to afford the total cost. If both conditions are met, a construction site is added to the build queue for each building in the blueprint and the full total cost is deducted from the global building blocks stock in one transaction. If a recipe ID is stored for a building, it is applied to the construction site immediately. If a schematic ID is stored, it is applied only if that schematic is currently unlocked; if it is not unlocked, the shipyard's schematic is left unset. Locked recipe IDs and splitter filter entries for locked item types are handled on placement per REQ-LOCK-UI-BLUEPRINT. After a successful placement the game remains in blueprint placement mode, allowing the player to place the same blueprint again immediately.

• REQ-UI-BLUEPRINT-DELETE: Clicking the delete icon ("×") on a blueprint entry immediately removes that blueprint from the list. If the deleted blueprint was active in blueprint placement mode, that mode is exited.

• REQ-UI-BLUEPRINT-SAVE: A "Save" button is shown at the bottom of the blueprint panel. Clicking it serializes all current blueprints to a file named blueprints.toml located in the same directory as the application executable. The TOML structure matches REQ-UI-BLUEPRINT-STORAGE. If writing fails, a modal error dialog is shown describing the failure.

• REQ-UI-BLUEPRINT-LOAD: A "Load" button is shown at the bottom of the blueprint panel, to the right of the "Save" button. Clicking it shows a confirmation dialog ("Load blueprints? This will replace all current blueprints.") with Confirm and Cancel buttons. Clicking Cancel closes the dialog with no effect. Clicking Confirm reads blueprints.toml from the same directory as the application executable, replaces all current blueprints with those from the file (in the order they appear in the file), and exits any active blueprint-related mode (blueprint placement mode, delete mode). If the file does not exist or cannot be parsed, a modal error dialog is shown describing the failure and the current blueprint list is left unchanged.

Balancing Tool

A separate executable target (balancing) that links against lib but contains no main-game UI code. It provides an automated arena-based ship balancing tool. Code written exclusively for this target does not go into lib.

Config

• REQ-BAL-CONFIG: The balancing tool reads arena definitions from a balancing.toml file. The file is read at startup and again each time the player triggers a config reload (REQ-BAL-UI-RELOAD). If parsing fails or required fields are missing at startup, the tool aborts with a clear error message. If parsing fails during a reload, a modal error dialog is shown describing the failure and the current arena list is left unchanged.
• REQ-BAL-CONFIG-GAME: Ship stats are read from ships.toml and defence station stats are read from stations.toml, using the same config loading as the main game. Formula evaluation uses the levels specified in the arena config.

Arena Definition

• REQ-BAL-ARENA: Each arena in balancing.toml defines:
  • A human-readable arena name.
  • Region widths (in tiles): player buffer width, contest zone width, enemy buffer width. The arena world is pure space — no asteroid region.
  • World height (in tiles).
  • Exactly two teams, each with a human-readable team name.
• REQ-BAL-TEAM: Each team defines:
  • A list of ship entries, each specifying: ship schematic (type), level, count, and an optional modules array defining the module layout applied to every ship of that entry. The modules array format is identical to that used in ship_layouts.toml (see Layout Blueprint TOML Format). If modules is omitted, ships of that entry have no modules. Invalid module instances (unknown type, position outside the grid, position on a non-buildable cell, or overlapping another module in the same entry) are silently skipped during loading.
  • An optional list of defence station entries, each specifying: station type (player_station or enemy_station from stations.toml), level, and tile position (x, y).
• REQ-BAL-HQ: Each team has an HQ placed automatically at the vertical center of the arena at the far end of that team's buffer zone. HQ stats are read from stations.toml [hq] at level 1. Team 1's HQ is at the left edge; team 2's HQ is at the right edge.
• REQ-BAL-SPAWN: Team 1's ships spawn in team 1's buffer zone (left side); team 2's ships spawn in team 2's buffer zone (right side). Spawn positions are uniformly random within the respective buffer zone.

Simulation

• REQ-BAL-SIM-ENV: Each arena simulates a pure-space environment using the same tick-based simulation as the main game. There is no asteroid, no buildings, no belts, no wave system, and no threat accumulation. Only ships, HQs, defence stations, and combat are active.
• REQ-BAL-SIM-AI: Ships use the same AI and stats as in the main game. All ships use aggressive stance and closest-target priority. Ships with no target in sensor range advance toward the enemy team's HQ. Ships that detect an enemy in sensor range engage it as in the normal game (REQ-SHP-COMBAT, REQ-SHP-ENEMY-AI).
• REQ-BAL-SIM-SPEED: Each arena that is not being inspected runs its simulation at maximum tick rate (as many ticks per second as the hardware allows), with no rendering. An inspected arena runs at a player-controllable game speed (same speed steps as the main game: 0×, 0.5×, 1×, 2×, 4×) with full rendering in the inspect window, defaulting to 1× on open.
• REQ-BAL-SIM-PARALLEL: All arenas are simulated in parallel, each on its own thread.
• REQ-BAL-SIM-END: An arena fight ends when either team's HQ is destroyed or all ships and defence stations of one team have been destroyed. If a team has no defence stations, destroying all its ships is sufficient. When the fight ends, the simulation for that arena stops.

UI

• REQ-BAL-UI-WINDOW: On startup the tool displays a window containing a "Reload Config" button and a "Start All" button at the top (in that order, left to right), followed by a scrollable vertical list of arena widgets, one per arena defined in balancing.toml. Simulations do not start automatically on startup. All buttons and controls in the main window are disabled while an arena is being inspected (REQ-BAL-UI-INSPECT).
• REQ-BAL-UI-RELOAD: The "Reload Config" button reloads all config files from disk (balancing.toml, ships.toml, stations.toml), stops any running simulations, and replaces the arena widget list with freshly created widgets from the reloaded config. The button is disabled while any arena simulation is currently running.
• REQ-BAL-UI-START-ALL: The "Start All" button is placed above the scrollable arena list, to the right of the "Reload Config" button. Clicking it starts (or restarts) the simulation for every arena that is not currently running. The button is disabled when all arenas are currently running.
• REQ-BAL-UI-WIDGET: Each arena widget displays the arena name, an "Inspect" button (to the right of the arena name), and two columns (one per team). Each column shows the team name as a header, followed by a list of entries. The HQ is always the first entry in each column. Below the HQ, ship types are listed, followed by defence stations (if any). Each entry uses the format surviving/total TypeName Llevel — for example 2/3 Fighter L5 or 1/1 HQ L1. The surviving count updates live as the simulation progresses. When the fight ends, the winning team's name header is prefixed with [WON].
• REQ-BAL-UI-WIDGET-START: Each arena widget contains a "Start" button that starts the simulation for that arena. The button is disabled while the arena's simulation is running. When a finished arena's Start button is clicked, a fresh simulation is created and started (the widget resets to initial unit counts, the border returns to blue, and the previous results are replaced).
• REQ-BAL-UI-WIDGET-BORDER: Each arena widget has a colored border indicating its state: grey when not yet started, blue while its simulation is running, and green when the fight has ended.
• REQ-BAL-UI-INSPECT: Clicking an arena widget's "Inspect" button opens a new inspect window for that arena. Any previously open inspect window is closed first (its arena's simulation is aborted and its widget border returns to grey). The inspected arena is restarted with a fresh simulation that runs at controllable game speed with full rendering (REQ-BAL-SIM-SPEED). The arena widget updates live during inspection (surviving counts, border color, [WON] prefix) as it does for non-inspected arenas. Only one inspect window may be open at a time.
• REQ-BAL-UI-INSPECT-WINDOW: The inspect window consists of three sections, top to bottom: a title bar area containing the arena name and game speed controls (same buttons as the main game: 0×, 0.5×, 1×, 2×, 4×, with Space to toggle pause — see REQ-UI-SPEED and REQ-UI-HOTKEYS), the arena view in the center, and an info panel at the bottom displaying the same team columns and entry format as the arena widget in the main window (REQ-BAL-UI-WIDGET), updated live.
• REQ-BAL-UI-INSPECT-VIEW: The arena view renders all tiles of the arena and displays ships, HQs, defence stations, and laser beams using the same visual elements and visuals.toml colors as the main game. Team 1 uses player visual styles; team 2 uses enemy visual styles. The view has a fixed zoom level — no zoom or scroll is possible. The tile size is derived so that the full arena (all tiles) fits within the view.
• REQ-BAL-UI-INSPECT-CLOSE: Closing the inspect window (via the window's close button) aborts the inspected arena's simulation. The arena widget's border returns to grey and its surviving counts are left as they were at the moment of closing. All main window buttons and controls are re-enabled.