mlangkabel/dota_factory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: mlangkabel:0.1.1
Branches Tags
mlangkabel:master mlangkabel:ui_changes mlangkabel:refactoring mlangkabel:progression_design mlangkabel:config
mlangkabel:0.1.2 mlangkabel:0.1.1 mlangkabel:0.1.0
..
compare: mlangkabel:config
Branches Tags
mlangkabel:master mlangkabel:ui_changes mlangkabel:refactoring mlangkabel:progression_design mlangkabel:config
mlangkabel:0.1.2 mlangkabel:0.1.1 mlangkabel:0.1.0

5 Commits
0.1.1 ... config

Author SHA1 Message Date
mlangkabel
c44936d1fe adapt config 2026-06-14 14:21:24 +02:00
mlangkabel
68c1345660 recipe iteration 2026-06-14 14:06:12 +02:00
mlangkabel
dbf334c829 add python script to verify module constraints against hulls 2026-06-14 14:06:11 +02:00
mlangkabel
f225c1330e refinement 2026-06-14 14:06:11 +02:00
mlangkabel
fba98c928f design config 2026-06-14 14:06:10 +02:00
225 changed files with 3570 additions and 16170 deletions
Expand all files Collapse all files

12
CMakeLists.txt
View File

@@ -4,20 +4,10 @@ message(STATUS "Using CMake ${CMAKE_VERSION}")
include(cmake/add_files.cmake)
include(cmake/create_source_groups.cmake)
include(cmake/version.cmake)
# Project ----------------------------------------------------------------------
# Product identity — anything that depends on the product/project name is defined
# here so it lives in a single place and can change in the future. These values
# feed the build targets in src/CMakeLists.txt and the Windows version resource
# (see cmake/version.rc.in).
set(PRODUCT_NAME "DotaFactory") # internal name and executable base name
set(PRODUCT_DISPLAY_NAME "Dota Factory") # human-readable product / file description
set(PRODUCT_COMPANY "TODO: company") # placeholder
set(PRODUCT_COPYRIGHT "TODO: copyright") # placeholder
project(${PRODUCT_NAME})
project(DotaFactory)
set(CMAKE_BUILD_TYPE_INIT "Release")

15
bin/app/data/config/buildings.toml
View File

@@ -1,6 +1,5 @@
[[building]]
id = "belt"
tooltip = "Transports items one tile at a time in the direction it faces."
cost = 2
player_placeable = true
construction_time_seconds = 0.2
@@ -8,7 +7,6 @@ surface_mask = ["A>"]
[[building]]
id = "splitter"
tooltip = "Splits an incoming item stream between two outputs, with optional per-output filters."
cost = 3
player_placeable = true
construction_time_seconds = 0.5
@@ -16,7 +14,6 @@ surface_mask = ["<A>"]
[[building]]
id = "tunnel_entry"
tooltip = "Sends items underground to a matching tunnel exit, letting belts cross."
cost = 5
player_placeable = true
construction_time_seconds = 0.5
@@ -24,7 +21,6 @@ surface_mask = ["A>"]
[[building]]
id = "tunnel_exit"
tooltip = "Receives items from a matching tunnel entry and pushes them onward."
cost = 5
player_placeable = true
construction_time_seconds = 0.5
@@ -32,7 +28,6 @@ surface_mask = ["A>"]
[[building]]
id = "miner"
tooltip = "Extracts a selected ore from the asteroid; every tile yields any ore."
cost = 15
player_placeable = true
construction_time_seconds = 1
@@ -42,7 +37,6 @@ surface_mask = [
[[building]]
id = "smelter"
tooltip = "Melts ore or scrap into basic materials. No recipe selection needed."
cost = 20
player_placeable = true
construction_time_seconds = 1
@@ -53,7 +47,6 @@ surface_mask = [
[[building]]
id = "assembler"
tooltip = "Crafts a selected recipe from the production tree into intermediate or final parts."
cost = 35
player_placeable = true
construction_time_seconds = 1
@@ -64,7 +57,6 @@ surface_mask = [
[[building]]
id = "reprocessing_plant"
tooltip = "Consumes scrap and yields one random higher-tier product per cycle."
cost = 40
player_placeable = true
construction_time_seconds = 1
@@ -76,7 +68,6 @@ surface_mask = [
[[building]]
id = "shipyard"
tooltip = "Builds autonomous combat ships from a selected schematic and module layout."
cost = 60
player_placeable = true
construction_time_seconds = 1
@@ -87,12 +78,10 @@ surface_mask = [
[[building]]
id = "salvage_bay"
tooltip = "Drop-off point where salvage ships unload collected scrap onto belts."
cost = 25
player_placeable = true
construction_time_seconds = 1
output_buffer_capacity = 20
surface_mask = [
"<AAS",
" AAS",
"SAA",
"SAA>",
]

168
bin/app/data/config/modules.toml
View File

@@ -1,29 +1,21 @@
# modules.toml
#
# Production tree v2: all weapons are railguns for now — the implementation
# (instant damage, no projectile, no ammunition) stays as-is and the beam
# visual reads as a tracer round. Lasers are reserved for a future distinct
# weapon type (see docs/content_design.md, "Production tree v2 — Weapons").
# Combat stats are placeholders until the arena balancing pass;
# production_time_seconds values come from the numbers pass.
#
# Unlock progression is mostly disabled (unlock_at_station_level = -1) pending
# the pacing pass. The railguns are the exception: railgun_m is gated to
# station level 1, and railgun_l requires railgun_m to be unlocked first
# (unlock_requires) — a demonstration of the prerequisite chain.
# First real-content iteration: module ids and surface masks are the designed
# content; stats, materials, and threat costs are placeholders until the
# recipe and balancing passes.
#
# Surface mask footprint ladder — footprints gate which hulls can mount a
# module, purely through geometry (see ships.toml for the matching hull
# grids):
#
# 1x1 railgun_s, salvager, repair_tool fits every hull, incl. drones
# 1x1 laser_cannon_s, salvager, repair_tool fits every hull, incl. drones
# 1x2 maneuvering_thrusters, sensor_booster,
# armor_plates frigate and up
# 1x3 afterburner frigate and up (eats most of a frigate)
# L-shape weapon_stabilizer, weapon_primer,
# weapon_upgrade frigate and up
# 2x2 railgun_m, drone_bay cruiser and up (no 2x2 area on s hulls)
# 3x3 railgun_l battleship and up (no 3x3 area on m hulls)
# 2x2 laser_cannon_m, drone_bay cruiser and up (no 2x2 area on s hulls)
# 3x3 laser_cannon_l battleship and up (no 3x3 area on m hulls)
# 2x6 drone_hangar carrier only
# -----------------------------------------------------------------------------
@@ -31,57 +23,56 @@
# -----------------------------------------------------------------------------
[[module]]
id = "railgun_s"
tooltip = "Small railgun. Fast-firing, short range, low damage; fits any hull."
id = "laser_cannon_s"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "railgun_s_module", amount = 1}]
production_time_seconds = 1
materials = [{item = "laser_cannon_s_module", amount = 1}]
player_production_level = 1
production_time_seconds = 0.5
fill_color = "#FF8040"
glyph = "Rs"
glyph = "Ls"
[module.weapon]
damage = 2
attack_range_m = 50
attack_rate_hz = 2.0
damage_formula = "2"
attack_range_m_formula = "50"
attack_rate_hz_formula = "2.0"
[[module]]
id = "railgun_m"
tooltip = "Medium railgun. Higher damage at longer range; needs a 2x2 slot."
unlock_at_station_level = 2
id = "laser_cannon_m"
unlock_at_station_level = -1
surface_mask = [
"OO",
"OO"]
materials = [{item = "railgun_m_module", amount = 1}]
production_time_seconds = 3
materials = [{item = "laser_cannon_m_module", amount = 1}]
player_production_level = 1
production_time_seconds = 2
fill_color = "#FF8040"
glyph = "Rm"
glyph = "Lm"
[module.weapon]
damage = 14
attack_range_m = 70
attack_rate_hz = 1.5
damage_formula = "10"
attack_range_m_formula = "70"
attack_rate_hz_formula = "1.5"
[[module]]
id = "railgun_l"
tooltip = "Large railgun. Heavy damage at long range; needs a 3x3 slot."
unlock_at_station_level = 6
unlock_requires = ["railgun_m"]
id = "laser_cannon_l"
unlock_at_station_level = -1
surface_mask = [
"OOO",
"OOO",
"OOO"]
materials = [{item = "railgun_l_module", amount = 1}]
production_time_seconds = 4
materials = [{item = "laser_cannon_l_module", amount = 1}]
player_production_level = 1
production_time_seconds = 8
fill_color = "#FF8040"
glyph = "Rl"
glyph = "Ll"
[module.weapon]
damage = 52
attack_range_m = 100
attack_rate_hz = 0.8
damage_formula = "40"
attack_range_m_formula = "100"
attack_rate_hz_formula = "0.8"
# -----------------------------------------------------------------------------
# Utility tools
@@ -89,34 +80,33 @@ attack_rate_hz = 0.8
[[module]]
id = "salvager"
tooltip = "Collects scrap from wrecks and stores it in the ship's cargo hold."
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "salvager_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 2
fill_color = "#AACC44"
glyph = "Sv"
[module.salvage]
collection_range_m = 60
cargo_capacity = 20
collection_rate_hz = 0.5
collection_range_m_formula = "500"
cargo_capacity_formula = "10"
collection_rate_hz_formula = "0.5"
[[module]]
id = "repair_tool"
tooltip = "Repairs damaged friendly ships and defence stations within range."
unlock_at_station_level = 0
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "repair_tool_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 2
fill_color = "#66CCFF"
glyph = "Rp"
[module.repair]
repair_rate_hz = 1
repair_amount_hp = 4
repair_range_m = 80
repair_rate_hz_formula = "5 + x"
repair_range_m_formula = "800"
# -----------------------------------------------------------------------------
# Propulsion
@@ -124,32 +114,32 @@ repair_range_m = 80
[[module]]
id = "afterburner"
tooltip = "Greatly boosts top speed and forward acceleration."
unlock_at_station_level = 2
unlock_at_station_level = -1
surface_mask = ["OOO"]
materials = [{item = "afterburner_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 2
fill_color = "#40A0FF"
glyph = "Ab"
[module.movement]
multiplied_speed_mps = 1.6
added_main_acceleration_mpss = 60
multiplied_speed_mps_formula = "1.6"
added_main_acceleration_mpss_formula = "60"
[[module]]
id = "maneuvering_thrusters"
tooltip = "Improves top speed and lateral/braking acceleration."
unlock_at_station_level = 1
unlock_at_station_level = -1
surface_mask = ["OO"]
materials = [{item = "maneuvering_thrusters_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 2
fill_color = "#40A0FF"
glyph = "Mt"
[module.movement]
multiplied_speed_mps = 1.2
added_maneuvering_acceleration_mpss = 10
multiplied_speed_mps_formula = "1.2"
added_maneuvering_acceleration_mpss_formula = "10"
# -----------------------------------------------------------------------------
# Defense & sensors
@@ -157,30 +147,30 @@ added_maneuvering_acceleration_mpss = 10
[[module]]
id = "armor_plates"
tooltip = "Adds a large flat bonus to the ship's hit points."
unlock_at_station_level = 0
unlock_at_station_level = -1
surface_mask = ["OO"]
materials = [{item = "armor_plates_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 3
fill_color = "#808080"
glyph = "A"
[module.health]
added_hp = 1200
added_hp_formula = "40"
[[module]]
id = "sensor_booster"
tooltip = "Extends the ship's sensor range."
unlock_at_station_level = 1
unlock_at_station_level = -1
surface_mask = ["OO"]
materials = [{item = "sensor_booster_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 2
fill_color = "#40A0FF"
glyph = "S"
[module.sensor]
added_sensor_range_m = 50
added_sensor_range_m_formula = "50"
# -----------------------------------------------------------------------------
# Weapon modifiers
@@ -188,54 +178,54 @@ added_sensor_range_m = 50
[[module]]
id = "weapon_upgrade"
tooltip = "Increases the damage of all weapons on the ship."
unlock_at_station_level = 4
unlock_at_station_level = -1
surface_mask = [
"OO",
"OX",
]
materials = [{item = "weapon_upgrade_module", amount = 1}]
production_time_seconds = 2
player_production_level = 1
production_time_seconds = 4
fill_color = "#FF4040"
glyph = "Wu"
[module.weapon]
multiplied_damage = 1.2
multiplied_damage_formula = "1.2"
[[module]]
id = "weapon_primer"
tooltip = "Increases the fire rate of all weapons on the ship."
unlock_at_station_level = 4
unlock_at_station_level = -1
surface_mask = [
"OO",
"OX",
]
materials = [{item = "weapon_primer_module", amount = 1}]
production_time_seconds = 2
player_production_level = 1
production_time_seconds = 4
fill_color = "#FF4040"
glyph = "Wp"
[module.weapon]
multiplied_attack_rate_hz = 1.2
multiplied_attack_rate_hz_formula = "1.2"
[[module]]
id = "weapon_stabilizer"
tooltip = "Extends weapon range at the cost of some fire rate."
unlock_at_station_level = 3
unlock_at_station_level = -1
surface_mask = [
"OO",
"OX",
]
materials = [{item = "weapon_stabilizer_module", amount = 1}]
production_time_seconds = 1
player_production_level = 1
production_time_seconds = 4
fill_color = "#FF4040"
glyph = "Ws"
[module.weapon]
multiplied_attack_range_m = 1.3
multiplied_attack_rate_hz = 0.8
multiplied_attack_range_m_formula = "1.5"
multiplied_attack_rate_hz_formula = "0.8"
# -----------------------------------------------------------------------------
# Drone modules
@@ -246,25 +236,25 @@ multiplied_attack_rate_hz = 0.8
[[module]]
id = "drone_bay"
tooltip = "Drone launch bay (capability not yet implemented)."
unlock_at_station_level = 5
unlock_at_station_level = -1
surface_mask = [
"OO",
"OO"]
materials = [{item = "drone_bay_module", amount = 1}]
production_time_seconds = 3
player_production_level = 1
production_time_seconds = 5
fill_color = "#CC66FF"
glyph = "Db"
[[module]]
id = "drone_hangar"
tooltip = "Large drone hangar (capability not yet implemented)."
unlock_at_station_level = 9
unlock_at_station_level = -1
surface_mask = [
"OOOOOO",
"OOOOOO"]
materials = [{item = "drone_hangar_module", amount = 1}]
production_time_seconds = 6
player_production_level = 1
production_time_seconds = 20
fill_color = "#9933CC"
glyph = "Dh"

631
bin/app/data/config/recipes.toml
View File

@@ -1,26 +1,24 @@
# recipes.toml
#
# Production tree v2 (structure in docs/content_design.md, numbers with
# derivations in docs/balancing/derived.md). Quantities and durations are tuned so that every
# fitted ship lands on the threat-cost ladder and the ratio curve is
# realized: tier 1 ratios are 1:1, tier 2 ratios are 2:3, tier 3+ ratios
# are deliberately strange.
# First real-content iteration of the production tree. Quantities and
# durations are a first guess; the balancing pass will tune them and assign
# real unlock_at_station_level values (everything is unlocked for now so the
# full tree is testable).
#
# Input chain per game phase — each phase transition adds exactly one new
# base input:
# Input chain per game phase — each phase adds exactly one new base input:
#
# early iron_ore + copper_ore minable on every asteroid tile (the
# asteroid is an M-type body — its bulk
# rock IS ore)
# mid + quartz geode deposits in expansion territory
# (deposit gating pending — see action
# item 5 in docs/balancing/README.md;
# until then quartz mines anywhere)
# late + voidsteel battle-forged: ONLY from reprocessing
# salvaged scrap, so capital production
# requires combat
# early iron_ore + copper_ore -> ingots -> copper_wire, steel_plate,
# circuit_board
# mid + titanium_ore -> titanium_frame; assembler-made
# mechanical_parts, targeting_unit,
# drive_unit
# late + advanced_alloy -> reinforced_plating, capital_core.
# advanced_alloy CANNOT be mined; it only
# comes from reprocessing salvaged scrap,
# so capital production requires combat.
#
# Run tools/verify_recipes.py and tools/threat_report.py after editing.
# Run tools/verify_recipes.py after editing to check that every consumed
# item has a producer and every item has a visuals.toml entry.
# -----------------------------------------------------------------------------
# Mining (tier 0)
@@ -38,409 +36,404 @@ id = "mine_copper_ore"
building = "miner"
inputs = []
outputs = [{item = "copper_ore", amount = 1}]
duration_seconds = 1.0
duration_seconds = 1.5
# Titanium is the midgame ore: mined three times slower than iron.
[[recipe]]
id = "mine_quartz"
id = "mine_titanium_ore"
building = "miner"
inputs = []
outputs = [{item = "quartz", amount = 1}]
duration_seconds = 2.0
outputs = [{item = "titanium_ore", amount = 1}]
duration_seconds = 3.0
# -----------------------------------------------------------------------------
# Smelting (tier 1) — one recipe per input item; ratios are 1:1 with miners.
# Smelting (tier 1)
# -----------------------------------------------------------------------------
[[recipe]]
id = "iron_ingot"
building = "smelter"
inputs = [{item = "iron_ore", amount = 1}]
inputs = [{item = "iron_ore", amount = 2}]
outputs = [{item = "iron_ingot", amount = 1}]
duration_seconds = 1.0
duration_seconds = 2.0
[[recipe]]
id = "copper_ingot"
building = "smelter"
inputs = [{item = "copper_ore", amount = 1}]
inputs = [{item = "copper_ore", amount = 2}]
outputs = [{item = "copper_ingot", amount = 1}]
duration_seconds = 1.0
duration_seconds = 2.5
[[recipe]]
id = "silicon"
id = "titanium_ingot"
building = "smelter"
inputs = [{item = "quartz", amount = 1}]
outputs = [{item = "silicon", amount = 1}]
duration_seconds = 2.0
# Scrap smelting: the safe, boring sink. Deliberately value-losing (4 threat
# of scrap becomes a 2-threat ingot) — reprocessing is the value-preserving
# path.
[[recipe]]
id = "scrap_smelting"
building = "smelter"
inputs = [{item = "scrap", amount = 1}]
outputs = [{item = "iron_ingot", amount = 1}]
duration_seconds = 1.0
inputs = [{item = "titanium_ore", amount = 3}]
outputs = [{item = "titanium_ingot", amount = 1}]
duration_seconds = 4.0
# -----------------------------------------------------------------------------
# Reprocessing — the only source of voidsteel (battle-forged; formed when
# weapon plasma anneals hull metal in the violence of ship destruction).
# Weights are authored for the fully unlocked pool state; the pool
# renormalizes over implicitly unlocked items early game.
# Reprocessing
#
# The only source of advanced_alloy: salvaged scrap from destroyed ships.
# -----------------------------------------------------------------------------
[[recipe]]
id = "reprocessing_cycle"
building = "reprocessing_plant"
inputs = [{item = "scrap", amount = 4}]
duration_seconds = 4.0
inputs = [{item = "scrap", amount = 5}]
duration_seconds = 3.0
[[recipe.outputs]]
item = "iron_ingot"
amount = 1
probability = 0.3
amount = 2
probability = 0.45
[[recipe.outputs]]
item = "copper_ingot"
amount = 1
probability = 0.3
probability = 0.25
[[recipe.outputs]]
item = "silicon"
item = "titanium_ingot"
amount = 1
probability = 0.2
probability = 0.15
[[recipe.outputs]]
item = "voidsteel"
item = "advanced_alloy"
amount = 1
probability = 0.2
probability = 0.15
# -----------------------------------------------------------------------------
# Tier 2 — early intermediates (clean ratios, ~2:3)
# Basic components (tier 2, early game)
# -----------------------------------------------------------------------------
[[recipe]]
id = "steel_plate"
building = "assembler"
inputs = [{item = "iron_ingot", amount = 2}]
outputs = [{item = "steel_plate", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "copper_wire"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "copper_ingot", amount = 1}]
outputs = [{item = "copper_wire", amount = 2}]
duration_seconds = 1.0
[[recipe]]
id = "copper_coil"
building = "assembler"
inputs = [{item = "copper_wire", amount = 2}]
outputs = [{item = "copper_coil", amount = 1}]
duration_seconds = 1.5
# Depth-3 chain (ore -> ingot -> plate -> block) is the factory's
# doubling-time knob; see the block economy rules in docs/balancing/rules.md.
# Explicitly unlocked at start (-1): building blocks appear in no
# schematic's materials, so implicit unlocking can never reach this recipe.
[[recipe]]
id = "building_block"
id = "steel_plate"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "steel_plate", amount = 2}]
outputs = [{item = "building_block", amount = 4}]
duration_seconds = 2.0
# -----------------------------------------------------------------------------
# Tier 3 — mid intermediates (strange ratios begin; need quartz)
# -----------------------------------------------------------------------------
[[recipe]]
id = "control_chip"
building = "assembler"
inputs = [{item = "silicon", amount = 1}, {item = "copper_wire", amount = 2}]
outputs = [{item = "control_chip", amount = 1}]
duration_seconds = 5.0
[[recipe]]
id = "capacitor_bank"
building = "assembler"
inputs = [{item = "copper_coil", amount = 2}, {item = "silicon", amount = 1}]
outputs = [{item = "capacitor_bank", amount = 1}]
duration_seconds = 5.0
# The quality gate for m+ hulls: a deliberately long-running recipe
# (time-heavy archetype).
[[recipe]]
id = "hardened_steel"
building = "assembler"
inputs = [{item = "steel_plate", amount = 3}]
outputs = [{item = "hardened_steel", amount = 1}]
duration_seconds = 12.0
[[recipe]]
id = "ceramic_plate"
building = "assembler"
inputs = [{item = "quartz", amount = 2}]
outputs = [{item = "ceramic_plate", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "drive_unit"
building = "assembler"
inputs = [
{item = "steel_plate", amount = 2},
{item = "copper_coil", amount = 2},
{item = "control_chip", amount = 1},
]
outputs = [{item = "drive_unit", amount = 1}]
duration_seconds = 8.0
# -----------------------------------------------------------------------------
# Tier 4 — late intermediates (need voidsteel)
# -----------------------------------------------------------------------------
[[recipe]]
id = "voidsteel_plate"
building = "assembler"
inputs = [{item = "voidsteel", amount = 1}, {item = "hardened_steel", amount = 1}]
outputs = [{item = "voidsteel_plate", amount = 1}]
duration_seconds = 8.0
[[recipe]]
id = "capital_core"
building = "assembler"
inputs = [
{item = "voidsteel", amount = 2},
{item = "capacitor_bank", amount = 1},
{item = "control_chip", amount = 1},
]
outputs = [{item = "capital_core", amount = 1}]
duration_seconds = 10.0
# -----------------------------------------------------------------------------
# Shortcut recipes — drop-only assembler recipe schematics
# (unlock_at_station_level >= 0). Pure rewards: item threat stays defined by
# the base (expensive) path via the max rule, so shortcuts give real factory
# efficiency without shifting any balance.
# -----------------------------------------------------------------------------
[[recipe]]
id = "shortcut_steel_plate"
unlock_at_station_level = 1
building = "assembler"
inputs = [{item = "iron_ore", amount = 3}]
inputs = [{item = "iron_ingot", amount = 2}]
outputs = [{item = "steel_plate", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "shortcut_control_chip"
unlock_at_station_level = 2
id = "circuit_board"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "quartz", amount = 2}]
outputs = [{item = "control_chip", amount = 1}]
inputs = [{item = "iron_ingot", amount = 1}, {item = "copper_wire", amount = 2}]
outputs = [{item = "circuit_board", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "building_blocks"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "iron_ingot", amount = 4}]
outputs = [{item = "building_block", amount = 10}]
duration_seconds = 4.0
# -----------------------------------------------------------------------------
# Advanced components (tier 3, midgame)
# -----------------------------------------------------------------------------
[[recipe]]
id = "mechanical_parts"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "steel_plate", amount = 1}, {item = "iron_ingot", amount = 1}]
outputs = [{item = "mechanical_parts", amount = 2}]
duration_seconds = 2.5
[[recipe]]
id = "targeting_unit"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "circuit_board", amount = 2}, {item = "copper_wire", amount = 1}]
outputs = [{item = "targeting_unit", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "drive_unit"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "steel_plate", amount = 1},
{item = "mechanical_parts", amount = 1},
{item = "circuit_board", amount = 1},
]
outputs = [{item = "drive_unit", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "shortcut_hardened_steel"
unlock_at_station_level = 2
id = "titanium_frame"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "iron_ingot", amount = 4}]
outputs = [{item = "hardened_steel", amount = 1}]
inputs = [{item = "titanium_ingot", amount = 2}, {item = "steel_plate", amount = 1}]
outputs = [{item = "titanium_frame", amount = 1}]
duration_seconds = 4.0
# -----------------------------------------------------------------------------
# Capital components (tier 4, lategame — gated on advanced_alloy)
# -----------------------------------------------------------------------------
[[recipe]]
id = "reinforced_plating"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "steel_plate", amount = 2}, {item = "advanced_alloy", amount = 1}]
outputs = [{item = "reinforced_plating", amount = 1}]
duration_seconds = 5.0
[[recipe]]
id = "capital_core"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "targeting_unit", amount = 1},
{item = "drive_unit", amount = 1},
{item = "advanced_alloy", amount = 2},
]
outputs = [{item = "capital_core", amount = 1}]
duration_seconds = 8.0
# -----------------------------------------------------------------------------
# Module items — early game
# -----------------------------------------------------------------------------
[[recipe]]
id = "laser_cannon_s_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "iron_ingot", amount = 2}, {item = "circuit_board", amount = 1}]
outputs = [{item = "laser_cannon_s_module", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "salvager_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "steel_plate", amount = 1}, {item = "circuit_board", amount = 1}]
outputs = [{item = "salvager_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "repair_tool_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "circuit_board", amount = 2}, {item = "copper_wire", amount = 1}]
outputs = [{item = "repair_tool_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "armor_plates_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "steel_plate", amount = 2}]
outputs = [{item = "armor_plates_module", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "sensor_booster_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "circuit_board", amount = 1}, {item = "copper_wire", amount = 2}]
outputs = [{item = "sensor_booster_module", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "maneuvering_thrusters_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "mechanical_parts", amount = 1}, {item = "copper_wire", amount = 1}]
outputs = [{item = "maneuvering_thrusters_module", amount = 1}]
duration_seconds = 3.0
# -----------------------------------------------------------------------------
# Module items — midgame
# -----------------------------------------------------------------------------
[[recipe]]
id = "afterburner_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "drive_unit", amount = 1}, {item = "steel_plate", amount = 1}]
outputs = [{item = "afterburner_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "weapon_upgrade_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "targeting_unit", amount = 1}, {item = "steel_plate", amount = 1}]
outputs = [{item = "weapon_upgrade_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "weapon_primer_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "targeting_unit", amount = 1}, {item = "copper_wire", amount = 2}]
outputs = [{item = "weapon_primer_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "weapon_stabilizer_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "targeting_unit", amount = 1}, {item = "mechanical_parts", amount = 1}]
outputs = [{item = "weapon_stabilizer_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "laser_cannon_m_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "targeting_unit", amount = 1}, {item = "titanium_frame", amount = 1}]
outputs = [{item = "laser_cannon_m_module", amount = 1}]
duration_seconds = 6.0
[[recipe]]
id = "drone_bay_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "titanium_frame", amount = 1},
{item = "mechanical_parts", amount = 1},
{item = "circuit_board", amount = 1},
]
outputs = [{item = "drone_bay_module", amount = 1}]
duration_seconds = 6.0
# -----------------------------------------------------------------------------
# Module items — lategame
# -----------------------------------------------------------------------------
[[recipe]]
id = "laser_cannon_l_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "targeting_unit", amount = 2},
{item = "reinforced_plating", amount = 2},
{item = "titanium_frame", amount = 1},
]
outputs = [{item = "laser_cannon_l_module", amount = 1}]
duration_seconds = 12.0
[[recipe]]
id = "drone_hangar_module"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "capital_core", amount = 1},
{item = "titanium_frame", amount = 2},
{item = "reinforced_plating", amount = 2},
]
outputs = [{item = "drone_hangar_module", amount = 1}]
duration_seconds = 20.0
# -----------------------------------------------------------------------------
# Ship hulls
# -----------------------------------------------------------------------------
[[recipe]]
id = "drone_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [{item = "iron_ingot", amount = 1}]
inputs = [{item = "iron_ingot", amount = 5}, {item = "circuit_board", amount = 1}]
outputs = [{item = "drone_hull", amount = 1}]
duration_seconds = 1.0
duration_seconds = 4.0
[[recipe]]
id = "frigate_hull"
building = "assembler"
inputs = [{item = "steel_plate", amount = 2}, {item = "copper_wire", amount = 1}]
outputs = [{item = "frigate_hull", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "destroyer_hull"
building = "assembler"
inputs = [{item = "steel_plate", amount = 3}, {item = "copper_coil", amount = 2}]
outputs = [{item = "destroyer_hull", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "cruiser_hull"
building = "assembler"
inputs = [{item = "hardened_steel", amount = 2}, {item = "control_chip", amount = 2}]
outputs = [{item = "cruiser_hull", amount = 1}]
duration_seconds = 6.0
[[recipe]]
id = "battlecruiser_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "hardened_steel", amount = 3},
{item = "control_chip", amount = 2},
{item = "drive_unit", amount = 1},
{item = "steel_plate", amount = 3},
{item = "mechanical_parts", amount = 1},
{item = "circuit_board", amount = 1},
]
outputs = [{item = "battlecruiser_hull", amount = 1}]
outputs = [{item = "frigate_hull", amount = 1}]
duration_seconds = 8.0
[[recipe]]
id = "battleship_hull"
id = "destroyer_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "voidsteel_plate", amount = 3},
{item = "steel_plate", amount = 5},
{item = "mechanical_parts", amount = 2},
{item = "circuit_board", amount = 1},
]
outputs = [{item = "destroyer_hull", amount = 1}]
duration_seconds = 10.0
[[recipe]]
id = "cruiser_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "titanium_frame", amount = 2},
{item = "steel_plate", amount = 4},
{item = "drive_unit", amount = 1},
{item = "control_chip", amount = 2},
]
outputs = [{item = "cruiser_hull", amount = 1}]
duration_seconds = 15.0
[[recipe]]
id = "battlecruiser_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "titanium_frame", amount = 3},
{item = "steel_plate", amount = 6},
{item = "drive_unit", amount = 1},
{item = "targeting_unit", amount = 1},
]
outputs = [{item = "battlecruiser_hull", amount = 1}]
duration_seconds = 20.0
[[recipe]]
id = "battleship_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "titanium_frame", amount = 4},
{item = "reinforced_plating", amount = 2},
{item = "drive_unit", amount = 2},
]
outputs = [{item = "battleship_hull", amount = 1}]
duration_seconds = 10.0
duration_seconds = 30.0
[[recipe]]
id = "dreadnought_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "voidsteel_plate", amount = 5},
{item = "capital_core", amount = 1},
{item = "titanium_frame", amount = 6},
{item = "reinforced_plating", amount = 4},
{item = "drive_unit", amount = 2},
]
outputs = [{item = "dreadnought_hull", amount = 1}]
duration_seconds = 12.0
duration_seconds = 60.0
[[recipe]]
id = "carrier_hull"
unlock_at_station_level = -1
building = "assembler"
inputs = [
{item = "voidsteel_plate", amount = 5},
{item = "capital_core", amount = 1},
{item = "titanium_frame", amount = 5},
{item = "reinforced_plating", amount = 3},
{item = "drive_unit", amount = 2},
]
outputs = [{item = "carrier_hull", amount = 1}]
duration_seconds = 12.0
# -----------------------------------------------------------------------------
# Module prefabs
# -----------------------------------------------------------------------------
[[recipe]]
id = "railgun_s_module"
building = "assembler"
inputs = [{item = "copper_coil", amount = 1}]
outputs = [{item = "railgun_s_module", amount = 1}]
duration_seconds = 1.0
[[recipe]]
id = "salvager_module"
building = "assembler"
inputs = [{item = "steel_plate", amount = 1}, {item = "copper_wire", amount = 2}]
outputs = [{item = "salvager_module", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "repair_tool_module"
building = "assembler"
inputs = [{item = "steel_plate", amount = 1}, {item = "copper_wire", amount = 2}]
outputs = [{item = "repair_tool_module", amount = 1}]
duration_seconds = 2.0
# Material-heavy, fast: the armor archetype.
[[recipe]]
id = "armor_plates_module"
building = "assembler"
inputs = [{item = "steel_plate", amount = 4}]
outputs = [{item = "armor_plates_module", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "maneuvering_thrusters_module"
building = "assembler"
inputs = [{item = "steel_plate", amount = 1}, {item = "copper_coil", amount = 1}]
outputs = [{item = "maneuvering_thrusters_module", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "sensor_booster_module"
building = "assembler"
inputs = [{item = "copper_wire", amount = 2}, {item = "copper_coil", amount = 1}]
outputs = [{item = "sensor_booster_module", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "afterburner_module"
building = "assembler"
inputs = [{item = "copper_coil", amount = 2}, {item = "steel_plate", amount = 1}]
outputs = [{item = "afterburner_module", amount = 1}]
duration_seconds = 3.0
[[recipe]]
id = "weapon_stabilizer_module"
building = "assembler"
inputs = [{item = "steel_plate", amount = 1}, {item = "copper_coil", amount = 1}]
outputs = [{item = "weapon_stabilizer_module", amount = 1}]
duration_seconds = 2.0
[[recipe]]
id = "weapon_primer_module"
building = "assembler"
inputs = [{item = "capacitor_bank", amount = 1}, {item = "copper_coil", amount = 1}]
outputs = [{item = "weapon_primer_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "weapon_upgrade_module"
building = "assembler"
inputs = [{item = "control_chip", amount = 1}, {item = "copper_coil", amount = 1}]
outputs = [{item = "weapon_upgrade_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "railgun_m_module"
building = "assembler"
inputs = [
{item = "capacitor_bank", amount = 1},
{item = "steel_plate", amount = 2},
{item = "copper_coil", amount = 1},
]
outputs = [{item = "railgun_m_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "drone_bay_module"
building = "assembler"
inputs = [
{item = "control_chip", amount = 1},
{item = "steel_plate", amount = 2},
{item = "copper_coil", amount = 1},
]
outputs = [{item = "drone_bay_module", amount = 1}]
duration_seconds = 4.0
[[recipe]]
id = "railgun_l_module"
building = "assembler"
inputs = [
{item = "capacitor_bank", amount = 1},
{item = "hardened_steel", amount = 2},
{item = "ceramic_plate", amount = 1},
]
outputs = [{item = "railgun_l_module", amount = 1}]
duration_seconds = 6.0
[[recipe]]
id = "drone_hangar_module"
building = "assembler"
inputs = [
{item = "voidsteel_plate", amount = 1},
{item = "control_chip", amount = 2},
{item = "drive_unit", amount = 1},
]
outputs = [{item = "drone_hangar_module", amount = 1}]
duration_seconds = 10.0
duration_seconds = 60.0

237
bin/app/data/config/ships.toml
View File

@@ -4,11 +4,6 @@
# content; stats, materials, and production times are placeholders until the
# recipe and balancing passes.
#
# Unlock progression is mostly disabled (unlock_at_station_level = -1) pending
# the balancing pass. The capital hulls are the exception: battleship is gated
# to station level 1, and dreadnought (level 2) requires battleship to be
# unlocked first (unlock_requires) — a demonstration of the prerequisite chain.
#
# Size classes:
# xs drone 1 cell — exactly one 1x1 module
# s frigate, destroyer no 2x2 area anywhere: only 1x1/1x2/1x3/L modules fit
@@ -24,24 +19,28 @@
id = "drone"
unlock_at_station_level = -1
layout = ["O"]
default_modules = [{type = "railgun_s", x = 0, y = 0, rotation = "east"}]
default_modules = [{type = "laser_cannon_s", x = 0, y = 0, rotation = "east"}]
[ship.schematic]
materials = [{item = "drone_hull", amount = 1}]
production_time_seconds = 1
materials = [{item = "iron_ore", amount = 1}]
player_production_level = 1
production_time_seconds = 5
[ship.health]
hp = 60
hp_formula = "3"
[ship.movement]
speed_mps = 45
main_acceleration_mpss = 60
maneuvering_acceleration_mpss = 30
angular_acceleration_radpss = 12
max_rotation_speed_radps = 6
speed_mps_formula = "40"
main_acceleration_mpss_formula = "80"
maneuvering_acceleration_mpss_formula = "40"
angular_acceleration_radpss_formula = "12.56"
max_rotation_speed_radps_formula = "6.28"
[ship.sensor]
sensor_range_m = 150
sensor_range_m_formula = "150"
[ship.loot]
scrap_drop = 2
# Frigate — 5 cells in a plus shape. Holds a couple of small guns plus at
@@ -55,28 +54,27 @@ layout = [
"OOO",
"XOX",
]
default_modules = [
{type = "railgun_s", x = 1, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "maneuvering_thrusters", x = 0, y = 1, rotation = "east"},
]
[ship.schematic]
materials = [{item = "frigate_hull", amount = 1}]
production_time_seconds = 2
player_production_level = 1
production_time_seconds = 10
[ship.health]
hp = 300
hp_formula = "30"
[ship.movement]
speed_mps = 35
main_acceleration_mpss = 45
maneuvering_acceleration_mpss = 22
angular_acceleration_radpss = 8
max_rotation_speed_radps = 4
speed_mps_formula = "30"
main_acceleration_mpss_formula = "50"
maneuvering_acceleration_mpss_formula = "25"
angular_acceleration_radpss_formula = "8"
max_rotation_speed_radps_formula = "4"
[ship.sensor]
sensor_range_m = 200
sensor_range_m_formula = "200"
[ship.loot]
scrap_drop = 5
# Destroyer — 8 cells: a long gun deck with three turret bumps on top.
@@ -84,35 +82,32 @@ sensor_range_m = 200
# mount medium hardware.
[[ship]]
id = "destroyer"
unlock_at_station_level = 0
unlock_at_station_level = -1
layout = [
"OXOXO",
"OOOOO",
]
default_modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 0, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "armor_plates", x = 0, y = 1, rotation = "east"},
{type = "sensor_booster", x = 3, y = 1, rotation = "east"},
]
[ship.schematic]
materials = [{item = "destroyer_hull", amount = 1}]
production_time_seconds = 3
player_production_level = 1
production_time_seconds = 15
[ship.health]
hp = 550
hp_formula = "50"
[ship.movement]
speed_mps = 30
main_acceleration_mpss = 35
maneuvering_acceleration_mpss = 18
angular_acceleration_radpss = 6
max_rotation_speed_radps = 3
speed_mps_formula = "25"
main_acceleration_mpss_formula = "40"
maneuvering_acceleration_mpss_formula = "20"
angular_acceleration_radpss_formula = "6"
max_rotation_speed_radps_formula = "3"
[ship.sensor]
sensor_range_m = 220
sensor_range_m_formula = "220"
[ship.loot]
scrap_drop = 8
# Cruiser — 12 cells with notched corners. Fits at most two 2x2 m guns
@@ -120,36 +115,34 @@ sensor_range_m = 220
# supports; no 3x3 area exists for an l gun.
[[ship]]
id = "cruiser"
unlock_at_station_level = 2
unlock_at_station_level = -1
layout = [
"XOOX",
"OOOO",
"OOOO",
"XOOX",
]
default_modules = [
{type = "railgun_m", x = 0, y = 1, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 1, y = 0, rotation = "east"},
{type = "maneuvering_thrusters", x = 1, y = 3, rotation = "east"},
]
[ship.schematic]
materials = [{item = "cruiser_hull", amount = 1}]
production_time_seconds = 4
player_production_level = 1
production_time_seconds = 25
[ship.health]
hp = 1500
hp_formula = "120"
[ship.movement]
speed_mps = 24
main_acceleration_mpss = 25
maneuvering_acceleration_mpss = 12
angular_acceleration_radpss = 4
max_rotation_speed_radps = 2
speed_mps_formula = "20"
main_acceleration_mpss_formula = "30"
maneuvering_acceleration_mpss_formula = "15"
angular_acceleration_radpss_formula = "4"
max_rotation_speed_radps_formula = "2"
[ship.sensor]
sensor_range_m = 250
sensor_range_m_formula = "250"
[ship.loot]
scrap_drop = 15
# Battlecruiser — 16 cells: a wide bow split into two gun cheeks, tapering
@@ -158,39 +151,34 @@ sensor_range_m = 250
# stern leave no 3x3 area for an l gun and no 2x6 area for a drone hangar.
[[ship]]
id = "battlecruiser"
unlock_at_station_level = 4
unlock_requires = ["cruiser"]
unlock_at_station_level = -1
layout = [
"OOXXOO",
"OOOOOO",
"XOOOOX",
"XXOOXX",
]
default_modules = [
{type = "railgun_m", x = 0, y = 0, rotation = "east"},
{type = "railgun_m", x = 4, y = 0, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 2, y = 3, rotation = "east"},
{type = "railgun_s", x = 1, y = 2, rotation = "east"},
{type = "railgun_s", x = 4, y = 2, rotation = "east"},
]
[ship.schematic]
materials = [{item = "battlecruiser_hull", amount = 1}]
production_time_seconds = 5
player_production_level = 1
production_time_seconds = 35
[ship.health]
hp = 2400
hp_formula = "180"
[ship.movement]
speed_mps = 20
main_acceleration_mpss = 20
maneuvering_acceleration_mpss = 10
angular_acceleration_radpss = 3
max_rotation_speed_radps = 1.5
speed_mps_formula = "18"
main_acceleration_mpss_formula = "25"
maneuvering_acceleration_mpss_formula = "12"
angular_acceleration_radpss_formula = "3"
max_rotation_speed_radps_formula = "1.5"
[ship.sensor]
sensor_range_m = 260
sensor_range_m_formula = "260"
[ship.loot]
scrap_drop = 20
# Battleship — 24 cells: a broadside hull with notched flanks on every other
@@ -201,8 +189,7 @@ sensor_range_m = 260
# so no 2x6 drone hangar fits.
[[ship]]
id = "battleship"
unlock_at_station_level = 6
unlock_requires = ["battlecruiser"]
unlock_at_station_level = -1
layout = [
"XOOOOX",
"OOOOOO",
@@ -210,31 +197,27 @@ layout = [
"OOOOOO",
"XOOOOX",
]
default_modules = [
{type = "railgun_l", x = 1, y = 0, rotation = "east"},
{type = "railgun_m", x = 1, y = 3, rotation = "east"},
{type = "railgun_m", x = 3, y = 3, rotation = "east"},
{type = "weapon_stabilizer", x = 4, y = 1, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "railgun_s", x = 0, y = 1, rotation = "east"},
]
[ship.schematic]
materials = [{item = "battleship_hull", amount = 1}]
production_time_seconds = 6
player_production_level = 1
production_time_seconds = 60
[ship.health]
hp = 6300
hp_formula = "350"
[ship.movement]
speed_mps = 15
main_acceleration_mpss = 14
maneuvering_acceleration_mpss = 7
angular_acceleration_radpss = 2
max_rotation_speed_radps = 1
speed_mps_formula = "14"
main_acceleration_mpss_formula = "18"
maneuvering_acceleration_mpss_formula = "8"
angular_acceleration_radpss_formula = "2"
max_rotation_speed_radps_formula = "1"
[ship.sensor]
sensor_range_m = 280
sensor_range_m_formula = "280"
[ship.loot]
scrap_drop = 35
# Dreadnought — 36 cells: the main battery deck is split into three 3x3 gun
@@ -244,8 +227,7 @@ sensor_range_m = 280
# stay the only hangar hull. Bow and stern strips hold supports.
[[ship]]
id = "dreadnought"
unlock_at_station_level = 8
unlock_requires = ["battleship"]
unlock_at_station_level = -1
layout = [
"XXXOOOOOXXX",
"OOOXOOOXOOO",
@@ -253,33 +235,27 @@ layout = [
"OOOXOOOXOOO",
"XXOOXXXOOXX",
]
default_modules = [
{type = "railgun_l", x = 0, y = 1, rotation = "east"},
{type = "railgun_l", x = 4, y = 1, rotation = "east"},
{type = "railgun_l", x = 8, y = 1, rotation = "east"},
{type = "armor_plates", x = 3, y = 0, rotation = "east"},
{type = "armor_plates", x = 5, y = 0, rotation = "east"},
{type = "armor_plates", x = 2, y = 4, rotation = "east"},
{type = "armor_plates", x = 7, y = 4, rotation = "east"},
{type = "railgun_s", x = 7, y = 0, rotation = "east"},
]
[ship.schematic]
materials = [{item = "dreadnought_hull", amount = 1}]
production_time_seconds = 8
player_production_level = 1
production_time_seconds = 120
[ship.health]
hp = 24000
hp_formula = "800"
[ship.movement]
speed_mps = 10
main_acceleration_mpss = 8
maneuvering_acceleration_mpss = 4
angular_acceleration_radpss = 1
max_rotation_speed_radps = 0.5
speed_mps_formula = "8"
main_acceleration_mpss_formula = "10"
maneuvering_acceleration_mpss_formula = "5"
angular_acceleration_radpss_formula = "1"
max_rotation_speed_radps_formula = "0.5"
[ship.sensor]
sensor_range_m = 300
sensor_range_m_formula = "300"
[ship.loot]
scrap_drop = 60
# Carrier — 37 cells: the top flight deck (rows 0-1) is the only place wide
@@ -288,8 +264,7 @@ sensor_range_m = 300
# the lower decks hold supports and 2x2 point-defense m guns.
[[ship]]
id = "carrier"
unlock_at_station_level = 9
unlock_requires = ["battleship"]
unlock_at_station_level = -1
layout = [
"XOOOOOOOOX",
"OOOOOOOOOO",
@@ -297,28 +272,24 @@ layout = [
"XOOOOOOOOX",
"XXXOOOOXXX",
]
default_modules = [
{type = "drone_hangar", x = 2, y = 0, rotation = "east"},
{type = "railgun_m", x = 3, y = 2, rotation = "east"},
{type = "railgun_m", x = 6, y = 2, rotation = "east"},
{type = "armor_plates", x = 0, y = 1, rotation = "east"},
{type = "armor_plates", x = 8, y = 1, rotation = "east"},
{type = "sensor_booster", x = 3, y = 4, rotation = "east"},
]
[ship.schematic]
materials = [{item = "carrier_hull", amount = 1}]
production_time_seconds = 8
player_production_level = 1
production_time_seconds = 120
[ship.health]
hp = 24000
hp_formula = "700"
[ship.movement]
speed_mps = 10
main_acceleration_mpss = 8
maneuvering_acceleration_mpss = 4
angular_acceleration_radpss = 1
max_rotation_speed_radps = 0.5
speed_mps_formula = "9"
main_acceleration_mpss_formula = "10"
maneuvering_acceleration_mpss_formula = "5"
angular_acceleration_radpss_formula = "1"
max_rotation_speed_radps_formula = "0.5"
[ship.sensor]
sensor_range_m = 350
sensor_range_m_formula = "350"
[ship.loot]
scrap_drop = 60

28
bin/app/data/config/stations.toml
View File

@@ -1,18 +1,10 @@
# stations.toml
#
# Combat-pass anchors (see docs/balancing/targets.md, "Combat anchors"):
# a fresh player defence station holds one early parity wave unaided; the
# enemy station at level 0 matches the player station exactly and scales
# with the push level x. Station scrap drops stay authored (pushing rewards
# are tuned independently of ship production costs, REQ-RES-SCRAP-DROP).
[hq]
surface_mask = [
"AAA",
"AAA",
"AAA",
]
hp_formula = "5000"
hp_formula = "1000"
[player_station]
surface_mask = [
@@ -20,19 +12,19 @@ surface_mask = [
"SS",
]
level = 1
hp_formula = "3000"
damage_formula = "25"
range_m_formula = "120"
hp_formula = "300"
damage_formula = "5"
range_m_formula = "200"
fire_rate_hz_formula = "1"
scrap_drop_formula = "40"
scrap_drop_formula = "10"
[enemy_station]
surface_mask = [
"SS",
"SS",
]
hp_formula = "3000 + 1500*x"
damage_formula = "25 + 12*x"
range_m_formula = "120"
fire_rate_hz_formula = "1.0 + 0.1*x"
scrap_drop_formula = "40 + 30*x"
hp_formula = "300 + 150*x"
damage_formula = "2 + 1*x"
range_m_formula = "200"
fire_rate_hz_formula = "1.0 + 0.2*x"
scrap_drop_formula = "10 + 5*x"

69
bin/app/data/config/visuals.toml
View File

@@ -116,11 +116,11 @@ outline = "#201010"
fill = "#c47a3a"
outline = "#3a1a0a"
[items.quartz]
fill = "#e0d4f0"
outline = "#40345a"
[items.titanium_ore]
fill = "#9aa3ad"
outline = "#2a2e33"
# --- smelted basics ---
# --- ingots ---
[items.iron_ingot]
fill = "#b0b0b8"
@@ -130,9 +130,9 @@ outline = "#202028"
fill = "#d48a4a"
outline = "#402010"
[items.silicon]
fill = "#33415e"
outline = "#0e1420"
[items.titanium_ingot]
fill = "#c8d2dc"
outline = "#3a4048"
# --- salvage loop ---
@@ -140,9 +140,9 @@ outline = "#0e1420"
fill = "#7a7268"
outline = "#201a14"
[items.voidsteel]
fill = "#4a3a6a"
outline = "#151020"
[items.advanced_alloy]
fill = "#a06acc"
outline = "#201030"
# --- basic components ---
@@ -154,9 +154,9 @@ outline = "#3a2008"
fill = "#8a92a0"
outline = "#22262c"
[items.copper_coil]
fill = "#d07030"
outline = "#381808"
[items.circuit_board]
fill = "#2ea35a"
outline = "#0a2a14"
[items.building_block]
fill = "#c8b070"
@@ -164,30 +164,26 @@ outline = "#302810"
# --- advanced components ---
[items.control_chip]
fill = "#2ea35a"
outline = "#0a2a14"
[items.mechanical_parts]
fill = "#6f7a66"
outline = "#1c2018"
[items.capacitor_bank]
fill = "#d0a030"
outline = "#302408"
[items.hardened_steel]
fill = "#6a7280"
outline = "#181c22"
[items.ceramic_plate]
fill = "#e0d8c8"
outline = "#3a3428"
[items.targeting_unit]
fill = "#3a9e8c"
outline = "#0c2824"
[items.drive_unit]
fill = "#4a6ad0"
outline = "#101a38"
[items.titanium_frame]
fill = "#b8c4d4"
outline = "#343c48"
# --- capital components ---
[items.voidsteel_plate]
fill = "#7a5aaa"
[items.reinforced_plating]
fill = "#8a6ad0"
outline = "#1c1038"
[items.capital_core]
@@ -196,15 +192,15 @@ outline = "#280c30"
# --- module items ---
[items.railgun_s_module]
[items.laser_cannon_s_module]
fill = "#691313"
outline = "#f3ff4f"
[items.railgun_m_module]
[items.laser_cannon_m_module]
fill = "#892020"
outline = "#f3ff4f"
[items.railgun_l_module]
[items.laser_cannon_l_module]
fill = "#a92d2d"
outline = "#f3ff4f"
@@ -329,10 +325,8 @@ outline = "#ffffff"
# -----------------------------------------------------------------------------
[beams]
weapon_color = "#ff6600"
repair_color = "#33ff66"
salvage_color = "#33ccff"
width_px = 2
color = "#ff6600"
width_px = 2
# -----------------------------------------------------------------------------
# Build / demolish / selection overlays
@@ -348,9 +342,6 @@ demolish_tint = "#ff000033" # demolish-mode hover tint
selection_rect = "#00ff00" # box-drag selection rectangle (REQ-UI-MULTI-SELECT)
tile_highlight = "#ffffff22" # tile under cursor
selected_outline = "#ffff00" # outline drawn around currently-selected building(s)
copy_config = "#33ccff66" # copy-settings eligible-target tint + copy/paste flash (REQ-BLD-COPY-CONFIG-FEEDBACK)
locked_asteroid = "#0000007f" # tint over the asteroid left of the buildable edge (not yet unlocked by expansion)
modal_dim = "#00000099" # semi-transparent black dim behind modal dialogs/menus (REQ-UI-MODAL-DIM)
# -----------------------------------------------------------------------------
# Schematic-drop toasts (REQ-UI-SCHEMATIC-TOAST)

40
bin/app/data/config/world.toml
View File

@@ -1,54 +1,30 @@
[world]
height_tiles = 40
refund_percentage = 100
starting_building_blocks = 200
scrap_despawn_seconds = 120
scrap_per_threat = 0.25
height_tiles = 30
refund_percentage = 75
starting_building_blocks = 1000
scrap_despawn_seconds = 30
tile_size_m = 10
belt_speed_mps = 20
tunnel_max_distance_tiles = 10
departure_interval_seconds = 20
orbit_factor = 0.8
rally_orbit_radius_tiles = 5.0
building_blocks_tooltip = "Building blocks are the currency for construction. Spend them to place buildings and to expand the asteroid. Produce building blocks in your factory and deliver them to the HQ on a belt to grow your stock."
[regions]
asteroid_width_tiles = 60
asteroid_width_tiles = 40
player_buffer_width_tiles = 20
contest_zone_width_tiles = 60
enemy_buffer_width_tiles = 20
[scroll]
# View pan speed (REQ-UI-SCROLL-SPEED): slow near the asteroid, fast across the
# contest zone, with a linear ramp of the given width straddling each boundary.
pan_speed_slow_tiles_per_second = 16.0
pan_speed_fast_tiles_per_second = 32.0
pan_ramp_band_width_tiles = 16
[expansion]
columns_per_expansion_tiles = 10
# x = expansions already purchased; ~1 per cycle mid-game, decelerating
# to 2-3 cycles late (docs/balancing/derived.md).
cost_building_blocks_formula = "300 + 50*x + 10*x*x"
cost_building_blocks = 200
[push]
push_expand_columns_tiles = 10
boss_advance_seconds = 60
[targeting]
target_score_formula = "1 / (1 + x)" # x = distance / max weapon range; higher = better, clamped to >=0
overclaim_penalty_formula = "max(0.5, 1 - 0.1*x)" # x = competing claim count; multiplies score, clamped to [0,1]
target_hysteresis = 0.40 # keep current target unless a challenger beats it by >10%
[artifacts]
artifact_chance_formula = "0.05 * x" # 5% chance per station level
artifact_win_count = 5
[waves]
# Tuned against the factory-size curve (docs/balancing/targets.md, balancing
# targets): stays below the player's achievable military output early,
# crosses it around the late boundary (~cycle 15), overwhelms by ~24.
threat_rate_formula = "2*x + 0.15*x*x"
threat_rate_formula = "x"
ship_level_formula = "1"
gap_min_seconds = 15
gap_max_seconds = 45
spawn_duration_seconds = 10

390
bin/balancing/data/balancing.toml
View File

@@ -1,397 +1,73 @@
# balancing.toml — canonical arena suite for the combat stats pass.
#
# Ship counts are chosen so both teams have (near-)equal total threat,
# using the verified fitted threat values from tools/threat_report.py:
# drone 10.5, frigate 47, destroyer 99, cruiser 233.5,
# battlecruiser 354.5, battleship 722.5, dreadnought 1491.5,
# carrier 1436.5, glass destroyer (8 small guns) 92, repair drone 17.
# Module arrays mirror the ships' default_modules loadouts unless a
# doctrine variant is the point of the arena.
#
# Expectations: mirror matches and equal-threat cross-tier matchups should
# be near-draws (power-per-threat rule); the two-to-one arena must be a
# decisive win for the larger team. "Cruisers vs carrier" is EXPECTED to be
# a loss for the carrier until the drone-launching capability exists — the
# hangar is 224 threat of dead weight.
# --- mirrors (sanity: symmetric outcomes, fight duration in the 30-60 s band) ---
[[arena]]
name = "Mirror: drones 20v20"
height_tiles = 10
name = "Fighters vs Sniper"
height_tiles = 20
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
contest_zone_width_tiles = 60
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Alpha"
[[arena.team.ship]]
schematic = "drone"
count = 20
level = 1
count = 5
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "laser_cannon_s", x = 1, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Beta"
[[arena.team.ship]]
schematic = "drone"
count = 20
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
]
[[arena]]
name = "Mirror: cruisers 6v6"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Alpha"
[[arena.team.ship]]
schematic = "cruiser"
count = 6
modules = [
{type = "railgun_m", x = 0, y = 1, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 1, y = 0, rotation = "east"},
{type = "maneuvering_thrusters", x = 1, y = 3, rotation = "east"},
]
[[arena.team]]
name = "Beta"
[[arena.team.ship]]
schematic = "cruiser"
count = 6
modules = [
{type = "railgun_m", x = 0, y = 1, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 1, y = 0, rotation = "east"},
{type = "maneuvering_thrusters", x = 1, y = 3, rotation = "east"},
]
[[arena]]
name = "Mirror: battleships 2v2"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Alpha"
[[arena.team.ship]]
schematic = "battleship"
level = 1
count = 2
modules = [
{type = "railgun_l", x = 1, y = 0, rotation = "east"},
{type = "railgun_m", x = 1, y = 3, rotation = "east"},
{type = "railgun_m", x = 3, y = 3, rotation = "east"},
{type = "weapon_stabilizer", x = 4, y = 1, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "railgun_s", x = 0, y = 1, rotation = "east"},
{type = "laser_cannon_s", x = 1, y = 1, rotation = "east"},
{type = "weapon_stabilizer", x = 1, y = 1, rotation = "east"},
{type = "weapon_stabilizer", x = 1, y = 1, rotation = "east"},
{type = "weapon_upgrade", x = 1, y = 1, rotation = "east"},
{type = "sensor_booster", x = 1, y = 1, rotation = "east"},
{type = "sensor_booster", x = 1, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Beta"
[[arena.team.ship]]
schematic = "battleship"
count = 2
modules = [
{type = "railgun_l", x = 1, y = 0, rotation = "east"},
{type = "railgun_m", x = 1, y = 3, rotation = "east"},
{type = "railgun_m", x = 3, y = 3, rotation = "east"},
{type = "weapon_stabilizer", x = 4, y = 1, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "railgun_s", x = 0, y = 1, rotation = "east"},
]
# --- equal-threat cross-tier matchups (power-per-threat: expect near-draws) ---
[[arena]]
name = "Drone swarm vs cruisers (462 vs 467)"
height_tiles = 10
name = "Fighters vs Supported"
height_tiles = 20
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
contest_zone_width_tiles = 60
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Swarm"
name = "Fighters"
[[arena.team.ship]]
schematic = "drone"
count = 44
level = 1
count = 5
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "laser_cannon_s", x = 1, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Cruisers"
name = "Supported"
[[arena.team.ship]]
schematic = "cruiser"
count = 2
modules = [
{type = "railgun_m", x = 0, y = 1, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 1, y = 0, rotation = "east"},
{type = "maneuvering_thrusters", x = 1, y = 3, rotation = "east"},
]
[[arena]]
name = "Frigates vs battleship (705 vs 723)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Frigates"
[[arena.team.ship]]
schematic = "frigate"
count = 15
modules = [
{type = "railgun_s", x = 1, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "maneuvering_thrusters", x = 0, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Battleship"
[[arena.team.ship]]
schematic = "battleship"
count = 1
modules = [
{type = "railgun_l", x = 1, y = 0, rotation = "east"},
{type = "railgun_m", x = 1, y = 3, rotation = "east"},
{type = "railgun_m", x = 3, y = 3, rotation = "east"},
{type = "weapon_stabilizer", x = 4, y = 1, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "railgun_s", x = 0, y = 1, rotation = "east"},
]
[[arena]]
name = "Destroyers vs dreadnought (1485 vs 1492)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Destroyers"
[[arena.team.ship]]
schematic = "destroyer"
count = 15
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 0, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "armor_plates", x = 0, y = 1, rotation = "east"},
{type = "sensor_booster", x = 3, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Dreadnought"
[[arena.team.ship]]
schematic = "dreadnought"
count = 1
modules = [
{type = "railgun_l", x = 0, y = 1, rotation = "east"},
{type = "railgun_l", x = 4, y = 1, rotation = "east"},
{type = "railgun_l", x = 8, y = 1, rotation = "east"},
{type = "armor_plates", x = 3, y = 0, rotation = "east"},
{type = "armor_plates", x = 5, y = 0, rotation = "east"},
{type = "armor_plates", x = 2, y = 4, rotation = "east"},
{type = "armor_plates", x = 7, y = 4, rotation = "east"},
{type = "railgun_s", x = 7, y = 0, rotation = "east"},
]
[[arena]]
name = "Cruisers vs carrier (1401 vs 1437, carrier expected to lose)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Cruisers"
[[arena.team.ship]]
schematic = "cruiser"
count = 6
modules = [
{type = "railgun_m", x = 0, y = 1, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 1, y = 0, rotation = "east"},
{type = "maneuvering_thrusters", x = 1, y = 3, rotation = "east"},
]
[[arena.team]]
name = "Carrier"
[[arena.team.ship]]
schematic = "carrier"
count = 1
modules = [
{type = "drone_hangar", x = 2, y = 0, rotation = "east"},
{type = "railgun_m", x = 3, y = 2, rotation = "east"},
{type = "railgun_m", x = 6, y = 2, rotation = "east"},
{type = "armor_plates", x = 0, y = 1, rotation = "east"},
{type = "armor_plates", x = 8, y = 1, rotation = "east"},
{type = "sensor_booster", x = 3, y = 4, rotation = "east"},
]
[[arena]]
name = "Mixed mid vs battlecruisers (1394 vs 1418)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Mixed"
[[arena.team.ship]]
schematic = "destroyer"
count = 7
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 0, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "armor_plates", x = 0, y = 1, rotation = "east"},
{type = "sensor_booster", x = 3, y = 1, rotation = "east"},
]
[[arena.team.ship]]
schematic = "cruiser"
schematic = "drone"
level = 1
count = 3
modules = [
{type = "railgun_m", x = 0, y = 1, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 1, y = 0, rotation = "east"},
{type = "maneuvering_thrusters", x = 1, y = 3, rotation = "east"},
{type = "laser_cannon_s", x = 1, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Battlecruisers"
[[arena.team.ship]]
schematic = "battlecruiser"
count = 4
modules = [
{type = "railgun_m", x = 0, y = 0, rotation = "east"},
{type = "railgun_m", x = 4, y = 0, rotation = "east"},
{type = "railgun_m", x = 2, y = 1, rotation = "east"},
{type = "armor_plates", x = 2, y = 3, rotation = "east"},
{type = "railgun_s", x = 1, y = 2, rotation = "east"},
{type = "railgun_s", x = 4, y = 2, rotation = "east"},
]
# --- asymmetric checks ---
[[arena]]
name = "Two to one (must be decisive)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Six"
[[arena.team.ship]]
schematic = "frigate"
count = 6
modules = [
{type = "railgun_s", x = 1, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "maneuvering_thrusters", x = 0, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Three"
[[arena.team.ship]]
schematic = "frigate"
count = 3
modules = [
{type = "railgun_s", x = 1, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "maneuvering_thrusters", x = 0, y = 1, rotation = "east"},
]
[[arena]]
name = "Armored vs glass destroyers (1188 vs 1196)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Armored"
[[arena.team.ship]]
schematic = "destroyer"
count = 12
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 0, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "armor_plates", x = 0, y = 1, rotation = "east"},
{type = "sensor_booster", x = 3, y = 1, rotation = "east"},
]
[[arena.team]]
name = "Glass"
[[arena.team.ship]]
schematic = "destroyer"
count = 13
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 0, rotation = "east"},
{type = "railgun_s", x = 4, y = 0, rotation = "east"},
{type = "railgun_s", x = 0, y = 1, rotation = "east"},
{type = "railgun_s", x = 1, y = 1, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "railgun_s", x = 3, y = 1, rotation = "east"},
{type = "railgun_s", x = 4, y = 1, rotation = "east"},
]
[[arena]]
name = "Repair escort vs raw numbers (444 vs 444)"
height_tiles = 10
player_buffer_width_tiles = 10
contest_zone_width_tiles = 50
enemy_buffer_width_tiles = 10
[[arena.team]]
name = "Escorted"
[[arena.team.ship]]
schematic = "frigate"
count = 8
modules = [
{type = "railgun_s", x = 1, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "maneuvering_thrusters", x = 0, y = 1, rotation = "east"},
]
[[arena.team.ship]]
schematic = "drone"
count = 4
modules = [
{type = "repair_tool", x = 0, y = 0, rotation = "east"},
]
[[arena.team]]
name = "Raw"
[[arena.team.ship]]
schematic = "frigate"
count = 9
modules = [
{type = "railgun_s", x = 1, y = 0, rotation = "east"},
{type = "railgun_s", x = 2, y = 1, rotation = "east"},
{type = "maneuvering_thrusters", x = 0, y = 1, rotation = "east"},
]
[[arena.team.ship]]
schematic = "drone"
level = 1
count = 2
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "repair_tool", x = 1, y = 1, rotation = "east"},
]
[[arena]]
name = "Station assault (2 stations + 105 vs 315)"
height_tiles = 10
name = "Stations and Ships"
height_tiles = 60
player_buffer_width_tiles = 15
contest_zone_width_tiles = 40
enemy_buffer_width_tiles = 15
@@ -400,9 +76,10 @@ enemy_buffer_width_tiles = 15
name = "Fortified"
[[arena.team.ship]]
schematic = "drone"
count = 10
level = 1
count = 3
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "laser_cannon_s", x = 1, y = 1, rotation = "east"},
]
[[arena.team.station]]
type = "player_station"
@@ -419,7 +96,8 @@ enemy_buffer_width_tiles = 15
name = "Swarm"
[[arena.team.ship]]
schematic = "drone"
count = 30
level = 1
count = 8
modules = [
{type = "railgun_s", x = 0, y = 0, rotation = "east"},
{type = "laser_cannon_s", x = 1, y = 1, rotation = "east"},
]

2
bin/test/data/config/buildings.toml
View File

@@ -83,8 +83,6 @@ id = "salvage_bay"
cost = 25
player_placeable = true
construction_time_seconds = 15
output_buffer_capacity = 20
tooltip = "Drop-off point for salvage ships."
surface_mask = [
"SAA",
"SAA>",

48
bin/test/data/config/modules.toml
View File

@@ -1,129 +1,137 @@
[[module]]
id = "armor_plate"
tooltip = "Adds a large flat bonus to hit points."
unlock_at_station_level = -1
surface_mask = ["OO"]
materials = [{item = "iron_ingot", amount = 2}]
player_production_level = 1
production_time_seconds = 3
fill_color = "#808080"
glyph = "A"
[module.health]
multiplied_hp = 1.5
multiplied_hp_formula = "1.5"
[[module]]
id = "sensor_booster"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "circuit_board", amount = 1}]
player_production_level = 1
production_time_seconds = 2
fill_color = "#40A0FF"
glyph = "S"
[module.sensor]
added_sensor_range_m = 100
added_sensor_range_m_formula = "100"
[[module]]
id = "weapon_upgrade"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "iron_ingot", amount = 1}, {item = "circuit_board", amount = 1}]
player_production_level = 1
production_time_seconds = 4
fill_color = "#FF4040"
glyph = "W"
[module.weapon]
multiplied_damage = 1.2
multiplied_damage_formula = "1.2"
[[module]]
id = "laser_cannon"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "iron_ingot", amount = 1}]
player_production_level = 1
production_time_seconds = 5
fill_color = "#FF8040"
glyph = "L"
[module.weapon]
damage = 2
attack_range_m = 50
attack_rate_hz = 2.0
damage_formula = "2"
attack_range_m_formula = "50"
attack_rate_hz_formula = "2.0"
[[module]]
id = "salvager"
unlock_at_station_level = -1
surface_mask = ["OO"]
materials = [{item = "iron_ingot", amount = 2}]
player_production_level = 1
production_time_seconds = 5
fill_color = "#AACC44"
glyph = "Sv"
[module.salvage]
collection_range_m = 500
cargo_capacity = 10
collection_rate_hz = 0.5
collection_range_m_formula = "500"
cargo_capacity_formula = "10"
collection_rate_hz_formula = "0.5"
[[module]]
id = "repair_tool"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "circuit_board", amount = 2}]
player_production_level = 1
production_time_seconds = 5
fill_color = "#66CCFF"
glyph = "Rp"
[module.repair]
repair_rate_hz = 1
repair_amount_hp = 6
repair_range_m = 800
repair_rate_hz_formula = "5 + x"
repair_range_m_formula = "800"
[[module]]
id = "weapon_primer"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "iron_ingot", amount = 1}]
player_production_level = 1
production_time_seconds = 4
fill_color = "#FF4040"
glyph = "Wp"
[module.weapon]
multiplied_attack_rate_hz = 1.2
multiplied_attack_rate_hz_formula = "1.2"
[[module]]
id = "weapon_stabilizer"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "iron_ingot", amount = 1}]
player_production_level = 1
production_time_seconds = 4
fill_color = "#FF4040"
glyph = "Ws"
[module.weapon]
multiplied_attack_range_m = 1.5
multiplied_attack_rate_hz = 0.8
multiplied_attack_range_m_formula = "1.5"
multiplied_attack_rate_hz_formula = "0.8"
[[module]]
id = "afterburner"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "iron_ingot", amount = 1}]
player_production_level = 1
production_time_seconds = 2
fill_color = "#40A0FF"
glyph = "Ab"
[module.movement]
multiplied_speed_mps = 1.6
added_main_acceleration_mpss = 60
multiplied_speed_mps_formula = "1.6"
added_main_acceleration_mpss_formula = "60"
[[module]]
id = "maneuvering_thrusters"
unlock_at_station_level = -1
surface_mask = ["O"]
materials = [{item = "iron_ingot", amount = 1}]
player_production_level = 1
production_time_seconds = 2
fill_color = "#40A0FF"
glyph = "Mt"
[module.movement]
multiplied_speed_mps = 1.2
added_maneuvering_acceleration_mpss = 10
multiplied_speed_mps_formula = "1.2"
added_maneuvering_acceleration_mpss_formula = "10"

57
bin/test/data/config/recipes.toml
View File

@@ -92,60 +92,3 @@ duration_seconds = 3.0
item = "advanced_alloy"
amount = 1
probability = 0.1
# -------------------------------------------------------------------
# Extra recipes for ThreatCostCalculator unit tests (fixes 6-9)
# -------------------------------------------------------------------
# Fix 6: scrap-consuming smelter recipe for iron_ingot. Because iron_ingot
# already has a scrap-free smelter recipe above, this recipe must be excluded
# from iron_ingot's threat computation.
[[recipe]]
id = "scrap_iron"
building = "smelter"
inputs = [{item = "scrap", amount = 1}]
outputs = [{item = "iron_ingot", amount = 1}]
duration_seconds = 1.0
# Fix 7: a recipe that produces 2 items per cycle. Per-unit threat must
# divide by the output amount.
# dual_wire: (duration=3.0 + iron_ore(1.0)*1) / 2 = 4.0 / 2 = 2.0 per unit.
[[recipe]]
id = "dual_wire"
building = "assembler"
inputs = [{item = "iron_ore", amount = 1}]
outputs = [{item = "dual_wire", amount = 2}]
duration_seconds = 3.0
# Fix 8: an item downstream of a reprocessing-only item (advanced_alloy).
# advanced_alloy is resolved only by the reprocessing pass; downstream_product
# can only resolve in a non-reprocessing pass that runs AFTER the reprocessing
# pass, requiring proper fixpoint iteration.
# downstream_product: 2.0 + advanced_alloy(80.0)*1 = 82.0
[[recipe]]
id = "downstream_product"
building = "assembler"
inputs = [{item = "advanced_alloy", amount = 1}]
outputs = [{item = "downstream_product", amount = 1}]
duration_seconds = 2.0
# Fix 9: two recipes producing the same staggered_item. The cheap recipe
# resolves before circuit_board is known; the expensive one requires
# circuit_board. The item must be committed only once BOTH are computable,
# so the result is max(cheap, expensive).
# staggered_item_cheap: 1.0 + iron_ore(1.0)*1 = 2.0 (resolves early)
# staggered_item_expensive: 1.0 + circuit_board(28.0)*1 = 29.0 (resolves later)
# expected: max = 29.0
[[recipe]]
id = "staggered_item_cheap"
building = "assembler"
inputs = [{item = "iron_ore", amount = 1}]
outputs = [{item = "staggered_item", amount = 1}]
duration_seconds = 1.0
[[recipe]]
id = "staggered_item_expensive"
building = "assembler"
inputs = [{item = "circuit_board", amount = 1}]
outputs = [{item = "staggered_item", amount = 1}]
duration_seconds = 1.0

72
bin/test/data/config/ships.toml
View File

@@ -6,20 +6,24 @@ default_modules = [{type = "laser_cannon", x = 1, y = 1, rotation = "east"}]
[ship.schematic]
materials = [{item = "iron_ingot", amount = 3}, {item = "circuit_board", amount = 1}]
player_production_level = 3
production_time_seconds = 10
[ship.health]
hp = 45
hp_formula = "40 + 5*x"
[ship.movement]
speed_mps = 2050
main_acceleration_mpss = 1000000
maneuvering_acceleration_mpss = 1000000
angular_acceleration_radpss = 100000
max_rotation_speed_radps = 100000
speed_mps_formula = "2000 + 50*x"
main_acceleration_mpss_formula = "1000000"
maneuvering_acceleration_mpss_formula = "1000000"
angular_acceleration_radpss_formula = "100000"
max_rotation_speed_radps_formula = "100000"
[ship.sensor]
sensor_range_m = 2000
sensor_range_m_formula = "2000"
[ship.loot]
scrap_drop = 2
[[ship]]
@@ -30,20 +34,24 @@ default_modules = [{type = "laser_cannon", x = 1, y = 1, rotation = "east"}]
[ship.schematic]
materials = [{item = "iron_ingot", amount = 5}, {item = "circuit_board", amount = 2}]
player_production_level = 5
production_time_seconds = 20
[ship.health]
hp = 135
hp_formula = "120 + 15*x"
[ship.movement]
speed_mps = 1200
main_acceleration_mpss = 1000000
maneuvering_acceleration_mpss = 1000000
angular_acceleration_radpss = 100000
max_rotation_speed_radps = 100000
speed_mps_formula = "1200"
main_acceleration_mpss_formula = "1000000"
maneuvering_acceleration_mpss_formula = "1000000"
angular_acceleration_radpss_formula = "100000"
max_rotation_speed_radps_formula = "100000"
[ship.sensor]
sensor_range_m = 3000
sensor_range_m_formula = "3000"
[ship.loot]
scrap_drop = 4
[[ship]]
@@ -53,20 +61,24 @@ layout = ["OOO", "OOO"]
[ship.schematic]
materials = [{item = "iron_ingot", amount = 4}]
player_production_level = 3
production_time_seconds = 10
[ship.health]
hp = 44
hp_formula = "40 + 4*x"
[ship.movement]
speed_mps = 1100
main_acceleration_mpss = 1000000
maneuvering_acceleration_mpss = 1000000
angular_acceleration_radpss = 100000
max_rotation_speed_radps = 100000
speed_mps_formula = "1100"
main_acceleration_mpss_formula = "1000000"
maneuvering_acceleration_mpss_formula = "1000000"
angular_acceleration_radpss_formula = "100000"
max_rotation_speed_radps_formula = "100000"
[ship.sensor]
sensor_range_m = 2500
sensor_range_m_formula = "2500"
[ship.loot]
scrap_drop = 2
[[ship]]
@@ -76,17 +88,21 @@ layout = ["XOX", "OOO", "XOX"]
[ship.schematic]
materials = [{item = "iron_ingot", amount = 4}, {item = "circuit_board", amount = 2}]
player_production_level = 3
production_time_seconds = 15
[ship.health]
hp = 65
hp_formula = "60 + 5*x"
[ship.movement]
speed_mps = 1300
main_acceleration_mpss = 1000000
maneuvering_acceleration_mpss = 1000000
angular_acceleration_radpss = 100000
max_rotation_speed_radps = 100000
speed_mps_formula = "1300"
main_acceleration_mpss_formula = "1000000"
maneuvering_acceleration_mpss_formula = "1000000"
angular_acceleration_radpss_formula = "100000"
max_rotation_speed_radps_formula = "100000"
[ship.sensor]
sensor_range_m = 2500
sensor_range_m_formula = "2500"
[ship.loot]
scrap_drop = 2

21
bin/test/data/config/world.toml
View File

@@ -3,14 +3,10 @@ height_tiles = 60
refund_percentage = 75
starting_building_blocks = 100
scrap_despawn_seconds = 30
scrap_per_threat = 1.0
tile_size_m = 10
belt_speed_mps = 20
tunnel_max_distance_tiles = 10
departure_interval_seconds = 20
orbit_factor = 0.8
rally_orbit_radius_tiles = 5.0
building_blocks_tooltip = "Spend building blocks to build; deliver them to the HQ to gain more."
[regions]
asteroid_width_tiles = 40
@@ -18,30 +14,17 @@ player_buffer_width_tiles = 10
contest_zone_width_tiles = 30
enemy_buffer_width_tiles = 15
[scroll]
pan_speed_slow_tiles_per_second = 8.0
pan_speed_fast_tiles_per_second = 24.0
pan_ramp_band_width_tiles = 16
[expansion]
columns_per_expansion_tiles = 10
cost_building_blocks_formula = "400 * 2^x"
cost_building_blocks = 200
[push]
push_expand_columns_tiles = 20
boss_advance_seconds = 60
[targeting]
target_score_formula = "1 / (1 + x)" # x = distance / max weapon range; higher = better, clamped to >=0
overclaim_penalty_formula = "max(0.5, 1 - 0.1*x)" # x = competing claim count; multiplies score, clamped to [0,1]
target_hysteresis = 0.10 # keep current target unless a challenger beats it by >10%
[artifacts]
artifact_chance_formula = "0.05 * x" # 5% chance per station level
artifact_win_count = 3
[waves]
threat_rate_formula = "x"
ship_level_formula = "1 + x / 10"
gap_min_seconds = 15
gap_max_seconds = 45
spawn_duration_seconds = 10

60
cmake/version.cmake
View File

@@ -1,60 +0,0 @@
# simple check for a git repo
if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
find_package(Git)
execute_process(
COMMAND ${GIT_EXECUTABLE} rev-parse --abbrev-ref HEAD
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE GIT_BRANCH
OUTPUT_STRIP_TRAILING_WHITESPACE
)
execute_process(
COMMAND ${GIT_EXECUTABLE} log -1 --format=%h
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE GIT_COMMIT_HASH
OUTPUT_STRIP_TRAILING_WHITESPACE
)
execute_process(
COMMAND ${GIT_EXECUTABLE} log -1 --format=%ci
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE GIT_COMMIT_TIME
OUTPUT_STRIP_TRAILING_WHITESPACE
)
execute_process(
COMMAND ${GIT_EXECUTABLE} describe --long --match "[0-9]*" HEAD
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE GIT_VERSION_NUMBER
OUTPUT_STRIP_TRAILING_WHITESPACE
)
string(REGEX REPLACE "^([0-9]+)\\..*" "\\1" VERSION_MAJOR "${GIT_VERSION_NUMBER}")
string(REGEX REPLACE "^[0-9]+\\.([0-9]+).*" "\\1" VERSION_MINOR "${GIT_VERSION_NUMBER}")
string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]+).*" "\\1" VERSION_PATCH "${GIT_VERSION_NUMBER}")
string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.[0-9]+-([0-9]+).*" "\\1" VERSION_COMMIT "${GIT_VERSION_NUMBER}")
else(EXISTS "${CMAKE_SOURCE_DIR}/.git")
set(GIT_BRANCH "")
set(GIT_COMMIT_HASH "")
set(GIT_VERSION_NUMBER "")
set(VERSION_MAJOR "0")
set(VERSION_MINOR "0")
set(VERSION_PATCH "0")
set(VERSION_COMMIT "0")
set(BUILD_TYPE "")
endif(EXISTS "${CMAKE_SOURCE_DIR}/.git")
set(VERSION_STRING "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}.${VERSION_COMMIT}")
message(STATUS "Version: ${VERSION_STRING}")
# message(STATUS "Git current branch: ${GIT_BRANCH}")
# message(STATUS "Git version number: " ${GIT_VERSION_NUMBER} )
# message(STATUS "Git commit hash: ${GIT_COMMIT_HASH}")
# message(STATUS "Git commit time: ${GIT_COMMIT_TIME}")
# message(STATUS "Version major: ${VERSION_MAJOR}")
# message(STATUS "Version minor: ${VERSION_MINOR}")
# message(STATUS "Version patch: ${VERSION_PATCH}")
# message(STATUS "Version commit: ${VERSION_COMMIT}")

35
cmake/version.rc.in
View File

@@ -1,35 +0,0 @@
// Windows version resource. Generated by CMake via configure_file() from this
// template; @VAR@ placeholders are filled from cmake/version.cmake (version
// numbers) and the product identity variables in the top-level CMakeLists.txt.
// Shows up on the executable's Details tab (right-click -> Properties).
#include <windows.h>
VS_VERSION_INFO VERSIONINFO
FILEVERSION @VERSION_MAJOR@,@VERSION_MINOR@,@VERSION_PATCH@,@VERSION_COMMIT@
PRODUCTVERSION @VERSION_MAJOR@,@VERSION_MINOR@,@VERSION_PATCH@,@VERSION_COMMIT@
FILEFLAGSMASK VS_FFI_FILEFLAGSMASK
FILEFLAGS 0x0L
FILEOS VOS_NT_WINDOWS32
FILETYPE VFT_APP
FILESUBTYPE VFT2_UNKNOWN
BEGIN
BLOCK "StringFileInfo"
BEGIN
BLOCK "040904b0" // US English (0x0409), Unicode (0x04b0)
BEGIN
VALUE "CompanyName", "@PRODUCT_COMPANY@"
VALUE "FileDescription", "@PRODUCT_DISPLAY_NAME@"
VALUE "FileVersion", "@VERSION_STRING@"
VALUE "InternalName", "@PRODUCT_NAME@"
VALUE "OriginalFilename", "@PRODUCT_NAME@.exe"
VALUE "ProductName", "@PRODUCT_DISPLAY_NAME@"
VALUE "ProductVersion", "@VERSION_STRING@"
VALUE "LegalCopyright", "@PRODUCT_COPYRIGHT@"
END
END
BLOCK "VarFileInfo"
BEGIN
VALUE "Translation", 0x409, 1200 // 0x409 = en-US, 1200 = Unicode code page
END
END

77
docs/architecture.md
View File

@@ -52,14 +52,14 @@ See REQ-GW-COORDS for the authoritative tile-coordinate convention. This section
Simulation types shared across subsystems:
- `EntityId` — strictly increasing integer handle, allocated centrally by the simulation. Assigned to every targetable entity: ships, scrap drops, **and** buildings (including HQ and defence stations). Buildings additionally retain their anchor tile for spatial lookups and placement; the `EntityId` is the canonical reference used by ship-component target fields (`Weapon.currentTarget`, `RepairTool.currentTarget`, `AttackBehavior.currentTarget`, etc.), so a combat ship can target either another ship or a defence station uniformly.
- `EntityId` — strictly increasing integer handle, allocated centrally by the simulation. Assigned to every targetable entity: ships, scrap drops, **and** buildings (including HQ and defence stations). Buildings additionally retain their anchor tile for spatial lookups and placement; the `EntityId` is the canonical reference used by ship-component target fields (`Weapon.currentTarget`, `RepairTool.currentTarget`, `ThreatResponse.currentTarget`, etc.), so a combat ship can target either another ship or a defence station uniformly.
- `Rotation` — enum `{ North, East, South, West }`. The rotation applied to a building's surface_mask when placed.
- `BuildingType` — enum covering every building type in requirements.md (Miner, Smelter, Assembler, ReprocessingPlant, Shipyard, SalvageBay, Belt, Splitter, Hq, PlayerDefenceStation, EnemyDefenceStation). `Belt` and `Splitter` share the enum for cost, construction, placement, and `visuals.toml` lookup, but their runtime data lives inside the belt subsystem rather than in `Building` instances (see Belt Subsystem).
- `ItemType` — tagged id of every transportable material (ores, ingots, intermediates, building_blocks, scrap).
- `Item` — `struct Item { ItemType type; }`. Items on belts have no persistent identity across ticks.
- `Port` — `struct Port { QPoint tile; Rotation direction; }`. Identifies a belt-adjacent cell and the direction of flow across that cell.
- `MovementIntent` — `struct MovementIntent { bool active; QVector2D target; }`. Written by the winning behavior's executor (see Movement Arbitration). Cleared (`active = false`) at the start of each tick; `tickMovement` brakes when inactive, otherwise drives toward `target`.
- `BeamFiredEvent` — `struct BeamFiredEvent : public Event { BeamKind kind; entt::entity shooter; entt::entity target; Tick emittedAt; }`. Transient record emitted each time a weapon fires, a repair tool starts a heal cycle, or a salvage module starts a collection cycle (REQ-SHP-FIRING, REQ-SHP-FIRING-BEAM). `BeamKind` (`Weapon`/`Repair`/`Salvage`) selects the beam color. Buffered in a sim-owned vector during the tick, then drained and re-emitted via EventManager by the UI frame handler; see Sim → UI Events.
- `MovementIntent` — `struct MovementIntent { int priority; QVector2D target; }`. Priority follows the order declared under Movement Arbitration. Cleared at the start of each tick; the highest-priority write wins; `tickMovement` reads the winner.
- `WeaponFiredEvent` — `struct WeaponFiredEvent : public Event { entt::entity shooter; entt::entity target; Tick emittedAt; }`. Transient record emitted each time a weapon fires (REQ-SHP-FIRING, REQ-SHP-FIRING-BEAM). Buffered in a sim-owned vector during the tick, then drained and re-emitted via EventManager by the UI frame handler; see Sim → UI Events.
- `SchematicChoiceOption` — `struct SchematicChoiceOption { string schematicId; SchematicType type; string displayName; bool isNewUnlock; int targetLevel; }`. Describes one option in the schematic choice dialog (REQ-DEF-SCHEMATIC-DROP). Up to three are generated when an enemy station set is destroyed. `SchematicType` is `Ship`, `Module`, or `Recipe`.
- `SchematicChoicesAvailableEvent` — EventManager event carrying a `vector<SchematicChoiceOption>`. Sent by the UI each frame when pending choices are detected; handled by `MainWindow` which opens the schematic choice dialog.
@@ -85,9 +85,9 @@ The EventManager is thread-safe (mutex-guarded).
### Sim → UI Events
The simulation layer stays free of EventManager — it uses a plain `std::vector<BeamFiredEvent>` internally (owned by `Simulation`, filled by the combat, repair, and salvage systems). This preserves determinism, tick-order fidelity, and headless testability (Catch2 tests read the queue directly via `drainBeamFiredEvents()` after `tick()`).
The simulation layer stays free of EventManager — it uses a plain `std::vector<WeaponFiredEvent>` internally (owned by `CombatSystem`). This preserves determinism, tick-order fidelity, and headless testability (Catch2 tests read the queue directly via `drainWeaponFiredEvents()` after `tick()`).
The UI frame handler (`GameWorldView::onFrame` / `ArenaView::onFrame`) bridges the gap: each frame it calls `simulation.drainBeamFiredEvents()`, then re-emits each `BeamFiredEvent` via `EventManager::sendEventImmediately()`. Subscribers (the same view's `handleEvent(BeamFiredEvent)`) create `ActiveBeam` records tracked for 0.3 s of wall time, then discarded. If either the shooter or target entity is gone when the renderer looks them up, the beam is dropped early.
The UI frame handler (`GameWorldView::onFrame` / `ArenaView::onFrame`) bridges the gap: each frame it calls `simulation.drainWeaponFiredEvents()`, then re-emits each `WeaponFiredEvent` via `EventManager::sendEventImmediately()`. Subscribers (the same view's `handleEvent(WeaponFiredEvent)`) create `ActiveBeam` records tracked for 0.3 s of wall time, then discarded. If either the shooter or target entity is gone when the renderer looks them up, the beam is dropped early.
Schematic drops: when an enemy station set is destroyed, the simulation generates up to 3 `SchematicChoiceOption` entries and stores them as pending state. The UI polls `hasSchematicChoicesPending()` each frame and, when true, sends a `SchematicChoicesAvailableEvent` via EventManager. `MainWindow` handles this event by pausing the game and opening a modal `SchematicChoiceDialog`. The player's selection is fed back via `applySchematicChoice(index)`.
@@ -107,8 +107,8 @@ Within a single simulation tick, subsystems run in this fixed order. The order i
4. **Building production** — advance production timers; start new cycles when inputs and output-buffer space permit (REQ-MAT-CYCLE); on completion, deposit output.
5. **Building → belt push** — buildings push items from output buffer onto the belt tile at their output port (REQ-MAT-OUTPUT-PORT).
6. **Belt tick** — advance items along belt tiles; apply splitter routing (REQ-BLD-SPLITTER).
7. **Ship behavior systems** — clear `MovementIntent` on each ship, then the `AiSystem` runs three batched phases: every behavior **evaluator** scores its behavior and sets its target data; a **selection** pass records the highest-scoring behavior per ship in `SelectedBehaviorComponent`; each behavior **executor** runs for the winner, writing `MovementIntent` and preferred module targets. The module systems then perform world mutation: `SalvagerSystem` (scrap collection/delivery) and `RepairSystem` (healing). See Movement Arbitration.
8. **Combat resolution** — ships and defence stations validate/acquire targets, fire, apply damage; queue deaths. Each fire appends a `BeamFiredEvent` to the sim's beam-fired-event queue (REQ-SHP-FIRING-BEAM). The repair and salvage module systems (tick step 7d) append their own `BeamFiredEvent`s to the same queue when they start a cycle.
7. **Ship behavior systems** — clear `MovementIntent` on each ship, then run `tickThreatResponse`, `tickScrapCollector`, `tickRepairBehavior`, `tickHomeReturn` in any order (arbitration is via intent priority).
8. **Combat resolution** — ships and defence stations acquire targets, fire, apply damage; queue deaths. Each fire appends a `WeaponFiredEvent` to the sim's weapon-fired-event queue (REQ-SHP-FIRING-BEAM).
9. **Deaths & loot** — process queued deaths: drop scrap (REQ-RES-SCRAP-DROP); if a full enemy-defence-station set was destroyed this tick, generate up to 3 schematic choice options (REQ-DEF-SCHEMATIC-DROP) stored as pending state for the UI to present; remove entities.
10. **`tickMovement`** — advance ship positions based on final `MovementIntent`.
11. **Scrap despawn** — decrement scrap timers; remove expired scrap (REQ-RES-SCRAP-DROP).
@@ -212,26 +212,21 @@ Ships follow a component-composition model using `std::optional<Component>` memb
struct Weapon { float damage; float range; float fireRateHz; float cooldownTicks;
std::optional<EntityId> currentTarget; };
struct SalvageCargo { int capacity; int current; };
struct RepairTool { float repairAmountHp; int repairIntervalTicks; int cooldownTicksRemaining;
float range; std::optional<EntityId> currentTarget; };
struct RepairTool { float ratePerTick; std::optional<EntityId> currentTarget; };
```
### Behavior Components
Behaviors are decomposed, not bundled into per-role monolithic AIs. This is the critical modeling choice: adding a capability (e.g., putting a `Weapon` on a repair ship) must not require rewriting AI code. Each behavior is a small component carrying its own target data plus a `float score` written by its evaluator each tick.
Behaviors are decomposed, not bundled into per-role monolithic AIs. This is the critical modeling choice: adding a capability (e.g., putting a `Weapon` on a repair ship) must not require rewriting AI code.
```cpp
struct AdvanceBehavior { float score; }; // baseline fallback, all ships
struct RallyBehavior { QVector2D rallyPoint; float score; }; // player combat ships
struct RetreatBehavior { float retreatHpFraction; QVector2D retreatPoint; // player ships
float score; };
struct AttackBehavior { std::optional<EntityId> currentTarget; float score; };
struct RepairBehavior { std::optional<EntityId> currentTarget;
float maxRepairRange_tiles; float score; };
struct SalvageScrapBehavior { std::optional<QVector2D> scrapTarget;
float maxCollectionRange_tiles; float score; };
struct DeliverScrapBehavior { BuildingId deliveryBay; float score; };
struct SelectedBehaviorComponent { BehaviorKind winner; float bestScore; }; // selection result
struct ThreatResponse { float engagementRange; CombatStance stance;
CombatTargetPriority priority;
std::optional<EntityId> currentTarget; };
struct ScrapCollector { std::optional<QVector2D> scrapTarget; EntityId deliveryBay; };
struct RepairBehavior { RepairTargetPriority priority;
std::optional<EntityId> currentTarget; };
struct HomeReturn { float retreatHpFraction; QVector2D homePos; };
```
### Ship
@@ -251,42 +246,38 @@ struct Ship {
std::optional<SalvageCargo> cargo;
std::optional<RepairTool> repairTool;
// Behaviors (attached per capability; AdvanceBehavior + SelectedBehaviorComponent
// on every ship, RetreatBehavior on player ships, etc.)
std::optional<AttackBehavior> attackBehavior;
std::optional<SalvageScrapBehavior> salvageScrapBehavior;
std::optional<DeliverScrapBehavior> deliverScrapBehavior;
std::optional<RepairBehavior> repairBehavior;
// Behaviors
std::optional<ThreatResponse> threatResponse;
std::optional<ScrapCollector> scrapCollector;
std::optional<RepairBehavior> repairBehavior;
std::optional<HomeReturn> homeReturn;
// Written by the winning behavior's executor, read by movement.
// Written by behavior systems, read by movement.
MovementIntent intent;
};
```
### Systems
Each behavior is split into a stateless **evaluator** and **executor** class (one per behavior, e.g. `AttackEvaluator`/`AttackExecutor`), orchestrated by `AiSystem`. Evaluators and executors only read/write behavior components and module target fields — they never mutate the game world. World mutation lives in dedicated module systems that run every tick, independent of which behavior won:
Each behavior has its own tick system. A system iterates a flat `std::vector<Ship>` and skips ships that do not have the relevant components.
- `CombatSystem` — validates each weapon's executor-set target, falls back to nearest-target acquisition, fires, applies damage.
- `SalvagerSystem` — collects scrap into cargo and delivers full cargo at a `SalvageBay`.
- `RepairSystem` — validates each repair tool's target, falls back to nearest damaged friendly, applies healing.
- `MovementIntentSystem` (`tickMovement`) — reads `MovementIntent`, advances `position`; brakes when inactive.
- `tickThreatResponse` — requires `threatResponse` + `weapon`. Acquires target, fires, manages cooldown.
- `tickScrapCollector` — requires `scrapCollector` + `cargo`. Flies to scrap, picks up, returns to delivery bay.
- `tickRepairBehavior` — requires `repairBehavior` + `repairTool`. Finds damaged target, moves to range, repairs.
- `tickHomeReturn` — requires `homeReturn`. Overrides movement if hp drops below threshold.
- `tickMovement` — reads `intent`, advances `position`.
### Movement Arbitration
Arbitration is **score-based**, not fixed-priority. In a single tick `AiSystem` runs three phases:
When multiple behaviors want to drive movement, a fixed global priority resolves the conflict. Each behavior system writes a `MovementIntent` carrying its priority; a higher-priority write overwrites a lower-priority one. `tickMovement` reads the final winner.
1. **Evaluate** — every behavior's evaluator iterates the ships that have its component, sets its target data, and writes a `float score` (see `BehaviorScores.h`). An evaluator returns an inactive score when its behavior does not apply.
2. **Select** — `selectWinningBehaviors` resets each `SelectedBehaviorComponent`, then compares every behavior's score per ship, recording the highest as `winner`. Behaviors are considered highest-band first so a strict `>` breaks ties toward the more urgent behavior.
3. **Execute** — each behavior's executor runs only for ships where it is the `winner`, writing the single `MovementIntent` and any preferred module targets.
`AdvanceBehavior` is present on every ship with the lowest score, guaranteeing a winner. The resulting band order:
Initial priority order (subject to tuning):
```
Retreat > Attack / Repair / SalvageScrap / DeliverScrap > Rally > Advance
HomeReturn > ThreatResponse > RepairBehavior > ScrapCollector
```
`MovementIntent` is cleared (inactive) at the start of each tick; `tickMovement` runs last.
`tickMovement` runs last. Intents are cleared at the start of each tick.
### Why Not ECS
@@ -309,7 +300,7 @@ The game world is rendered by a single `GameWorldView` widget that inherits `QOp
### Threading
Sim and UI run on the same thread for v1. `paintEvent` reads sim state directly without locks. If profiling later justifies moving the sim to a worker thread, the pull-style `drainBeamFiredEvents()` / `getPendingSchematicChoices()` / `applySchematicChoice()` / `forEachVisualItem()` APIs already support a clean snapshot-and-render split; a single mutex at the sim boundary would suffice. The `ArenaSimulation` used by the balancing tool runs headlessly on a worker thread; fire events accumulate in its internal vector and are only drained when `ArenaView` drives `tickOnce()` on the main thread during interactive inspection.
Sim and UI run on the same thread for v1. `paintEvent` reads sim state directly without locks. If profiling later justifies moving the sim to a worker thread, the pull-style `drainWeaponFiredEvents()` / `getPendingSchematicChoices()` / `applySchematicChoice()` / `forEachVisualItem()` APIs already support a clean snapshot-and-render split; a single mutex at the sim boundary would suffice. The `ArenaSimulation` used by the balancing tool runs headlessly on a worker thread; fire events accumulate in its internal vector and are only drained when `ArenaView` drives `tickOnce()` on the main thread during interactive inspection.
### Layer Order (back to front)
@@ -318,7 +309,7 @@ Sim and UI run on the same thread for v1. `paintEvent` reads sim state directly
3. **Belt items** — 10×10 colored squares emitted by `BeltSystem::forEachVisualItem`.
4. **Scrap** — glyphs at world positions.
5. **Ships** — colored arrows oriented by velocity; color keyed to role (player combat / salvage / repair / enemy).
6. **Laser beams** — lines derived from live `BeamFiredEvent`s kept by the renderer for 0.3 s, colored per `BeamKind` (weapon/repair/salvage) (REQ-SHP-FIRING-BEAM).
6. **Laser beams** — lines derived from live `WeaponFiredEvent`s kept by the renderer for 0.3 s (REQ-SHP-FIRING-BEAM).
7. **Build overlays** — ghost in builder mode (REQ-BLD-GHOST), demolish-mode tint, tile highlight under cursor, box-drag selection rectangle.
8. **Screen-space UI** — screen-anchored elements, drawn after resetting the world-space transform.

56
docs/balancing/README.md
View File

@@ -1,56 +0,0 @@
# Balancing Documentation
Everything about balancing Dota Factory, separated by role:
- **[rules.md](rules.md)** — the design rules and principles. Timeless;
changes only when the design changes.
- **[targets.md](targets.md)** — the base numbers (roots/anchors) chosen
by design. Change these first; everything else re-derives.
- **[derived.md](derived.md)** — the current tuned state of all derived
numbers, mirroring the configs. Updated whenever configs change.
- **[process.md](process.md)** — how balancing is done: the pass order,
tuning discipline, tools, and the checklist for the next round.
- **[history.md](history.md)** — chronological record of decisions,
findings, bugs, and arena rounds.
Related: game content (hull grids, footprint gating, tree design and
fiction) in [../content_design.md](../content_design.md); rules with
REQ-* ids in [../requirements.md](../requirements.md).
## Status
First full balancing round complete (2026-07-06): targets → tree →
numbers → threat-calculator parity → combat stats (arena-converged) →
pacing. Next step: full-game playtests against the run-shape targets in
`targets.md`.
## Open action items
Agreed changes that require edits to `requirements.md`, the code, or the
configs. Completed items are removed (their outcomes live in
`requirements.md`, `history.md`, and the git history).
1. **Fill unfillable schematic slots with artifacts.** With duplicates
removed, the schematic drop pool can run dry — previously unreachable.
Decision: every slot in the choice dialog that cannot be filled with a
schematic because the eligible pool is exhausted is filled with an
artifact option instead (in addition to any artifact option granted by
the regular artifact roll). A push therefore always awards a full
dialog. Update REQ-DEF-SCHEMATIC-DROP.
2. **Confirm wave scaling in playtests.** `threat_rate_formula` is the
only time-scaling axis; verify the tuned curve (see `derived.md`)
produces the intended difficulty race in real runs.
3. **Gate shortcut-recipe drops on their inputs.** Extend the assembler
recipe schematic pool eligibility in REQ-DEF-SCHEMATIC-DROP: in
addition to the existing station-level and output-item checks, all of
the recipe's input item types must be implicitly unlocked as well.
4. **Resource deposits.** Add a terrain deposit layer per the Resource
deposits rules (`rules.md`): deposit patches generated in expansion
columns (deterministic content per expansion, randomized placement
within the new columns), deposit rendering, and a miner condition (a
resource recipe is selectable only if the miner's footprint overlaps
at least one matching deposit tile). Touches REQ-BLD-MINER ("every
asteroid tile is equivalent" no longer holds),
REQ-GW-ASTEROID-EXPAND / REQ-EXP-*, `world.toml`, and `visuals.toml`.
Until this lands, quartz mines anywhere and the mid-game is
knowledge-gated only.

164
docs/balancing/derived.md
View File

@@ -1,164 +0,0 @@
# Derived Values (current tuned state)
Everything here is derived from `targets.md` under the rules in
`rules.md`, and mirrors the config files. Item threats, ship threats,
ratios, and belt checks are verified by `tools/threat_report.py` — re-run
it after any recipe or material change and update this file when values
move. Combat stats were tuned empirically against the arena suite in
`bin/balancing/data/balancing.toml` (round-by-round record in
`history.md`).
## Economy constants
- `scrap_per_threat = 0.25` — 1 scrap per 4 threat destroyed (a cruiser
kill drops ~59 scrap); threat(scrap) = 4.
- Scrap smelting: 1 scrap → 1 iron_ingot, 1 s — deliberately
value-losing; reprocessing is the value-preserving path.
- Reprocessing: 4 scrap per cycle, 4 s; full-pool weights iron_ingot 30 /
copper_ingot 30 / silicon 20 / voidsteel 20 → threat(voidsteel)
= (4·4 + 4)/0.2 = 100.
- `scrap_despawn_seconds = 120` (a capital kill drops hundreds of scrap,
collected one per salvage cycle).
## Recipes and item threats
(dur in seconds; threat is per output unit)
| item | recipe | dur | out | threat |
|---|---|---|---|---|
| iron_ore / copper_ore | miner | 1 | 1 | 1 |
| quartz | miner (deposit) | 2 | 1 | 2 |
| iron_ingot | 1 iron_ore | 1 | 1 | 2 |
| copper_ingot | 1 copper_ore | 1 | 1 | 2 |
| silicon | 1 quartz | 2 | 1 | 4 |
| steel_plate | 2 iron_ingot | 3 | 1 | 7 |
| copper_wire | 1 copper_ingot | 1 | 2 | 1.5 |
| copper_coil | 2 copper_wire | 1.5 | 1 | 4.5 |
| building_block | 2 steel_plate | 2 | 4 | 4 |
| control_chip | 1 silicon + 2 copper_wire | 5 | 1 | 12 |
| capacitor_bank | 2 copper_coil + 1 silicon | 5 | 1 | 18 |
| hardened_steel | 3 steel_plate | 12 | 1 | 33 |
| ceramic_plate | 2 quartz | 4 | 1 | 8 |
| drive_unit | 2 steel_plate + 2 copper_coil + 1 control_chip | 8 | 1 | 43 |
| voidsteel_plate | 1 voidsteel + 1 hardened_steel | 8 | 1 | 141 |
| capital_core | 2 voidsteel + 1 capacitor_bank + 1 control_chip | 10 | 1 | 240 |
Shortcut recipes (drop-only; item threat stays defined by the base path
via the max rule): `shortcut_steel_plate` 3 iron_ore → 1 plate (2 s,
level 1), `shortcut_control_chip` 2 quartz → 1 chip (4 s, level 2),
`shortcut_hardened_steel` 4 iron_ingot → 1 hardened (8 s, level 2).
Ratio curve realized: t1 all 1:1 (miner:smelter); t2 clean 2:3
(ingot→plate, wire→coil); t3 strange — 2:5 (silicon→chip), 3:5
(coil→capacitor), 3:4 (plate→hardened, plate→drive); t4 inverted 3:2
(hardened→voidsteel_plate). Belt check: worst input demand 1.33 items/s,
under the ~2/s single-belt cap everywhere.
## Module prefabs
(contribution = item threat + module production time)
| module | recipe | dur | mod. time | contribution |
|---|---|---|---|---|
| railgun_s | 1 copper_coil | 1 | 1 | 6.5 |
| salvager | 1 steel_plate + 2 copper_wire | 2 | 1 | 13 |
| repair_tool | 1 steel_plate + 2 copper_wire | 2 | 1 | 13 |
| armor_plates | 4 steel_plate | 3 | 1 | 32 |
| maneuvering_thrusters | 1 steel_plate + 1 copper_coil | 2 | 1 | 14.5 |
| sensor_booster | 2 copper_wire + 1 copper_coil | 2 | 1 | 10.5 |
| afterburner | 2 copper_coil + 1 steel_plate | 3 | 1 | 20 |
| weapon_stabilizer | 1 steel_plate + 1 copper_coil | 2 | 1 | 14.5 |
| weapon_primer | 1 capacitor_bank + 1 copper_coil | 4 | 2 | 28.5 |
| weapon_upgrade | 1 control_chip + 1 copper_coil | 4 | 2 | 22.5 |
| railgun_m | 1 capacitor_bank + 2 steel_plate + 1 copper_coil | 4 | 3 | 43.5 |
| drone_bay | 1 control_chip + 2 steel_plate + 1 copper_coil | 4 | 3 | 37.5 |
| railgun_l | 1 capacitor_bank + 2 hardened_steel + 1 ceramic_plate | 6 | 4 | 102 |
| drone_hangar | 1 voidsteel_plate + 2 control_chip + 1 drive_unit | 10 | 6 | 224 |
## Ships
(fitted = hull item + ship base time + default loadout; the default
loadouts are the `default_modules` used by enemy waves and are
geometry-validated against the hull grids)
| ship | hull recipe | dur | base | default loadout | fitted |
|---|---|---|---|---|---|
| drone | 1 iron_ingot | 1 | 1 | railgun_s | 10.5 |
| frigate | 2 steel_plate + 1 copper_wire | 2 | 2 | 2× railgun_s, maneuvering_thrusters | 47 |
| destroyer | 3 steel_plate + 2 copper_coil | 4 | 3 | 3× railgun_s, armor_plates, sensor_booster | 99 |
| cruiser | 2 hardened_steel + 2 control_chip | 6 | 4 | 2× railgun_m, armor_plates, maneuvering_thrusters | 233.5 |
| battlecruiser | 3 hardened_steel + 2 control_chip + 1 drive_unit | 8 | 5 | 3× railgun_m, armor_plates, 2× railgun_s | 354.5 |
| battleship | 3 voidsteel_plate + 1 drive_unit + 2 control_chip | 10 | 6 | railgun_l, 2× railgun_m, weapon_stabilizer, 2× railgun_s | 722.5 |
| dreadnought | 5 voidsteel_plate + 1 capital_core + 2 drive_unit | 12 | 8 | 3× railgun_l, 4× armor_plates, railgun_s | 1491.5 |
| carrier | 5 voidsteel_plate + 1 capital_core + 2 drive_unit | 12 | 8 | drone_hangar, 2× railgun_m, 2× armor_plates, sensor_booster | 1436.5 |
## Combat stats
(arena-converged, 2026-07; see `history.md` rounds 1–5)
**Weapons:** railgun_s 2 dmg × 2.0 Hz (4.0 DPS), range 50 m;
railgun_m 14 × 1.5 (21), range 70; railgun_l 52 × 0.8 (41.6), range 100.
**Hull HP** (15/threat prior + empirical trims): drone 60, frigate 300,
destroyer 550, cruiser 1500, battlecruiser 2400, battleship 6300,
dreadnought/carrier 24000.
**Mobility ladder** (speed m/s | main accel | maneuvering | angular |
max rot): drone 45|60|30|12|6, frigate 35|45|22|8|4,
destroyer 30|35|18|6|3, cruiser 24|25|12|4|2, battlecruiser 20|20|10|3|1.5,
battleship 15|14|7|2|1, dreadnought/carrier 10|8|4|1|0.5.
Sensors: 150/200/220/250/260/280/300/350 m.
**Other modules:** armor_plates +1200 HP; repair_tool 9 HP × 1 Hz,
range 80; salvager range 60, cargo 20, 0.5 collections/s; afterburner
×1.6 speed +60 accel; maneuvering_thrusters ×1.2 speed +10 maneuvering;
sensor_booster +50 m; weapon_upgrade ×1.2 damage; weapon_primer ×1.2
rate; weapon_stabilizer ×1.3 range ×0.8 rate.
**Stations:** HQ 5000 HP. Player station 3000 HP, 25 dmg × 1 Hz,
range 120, scrap 40. Enemy station: 3000+1500x HP, 25+12x dmg,
1.0+0.1x Hz, range 120, scrap 40+30x (x = push level).
## Pacing
**Unlock ladder** (level → unlocks; ← marks `unlock_requires`; starting
set at −1: drone, frigate, railgun_s, salvager, building_block recipe):
| level | ships | modules | recipes |
|---|---|---|---|
| 0 | destroyer | repair_tool, armor_plates | |
| 1 | | maneuvering_thrusters, sensor_booster | shortcut_steel_plate |
| 2 | cruiser | railgun_m, afterburner | shortcut_control_chip, shortcut_hardened_steel |
| 3 | | weapon_stabilizer | |
| 4 | battlecruiser ← cruiser | weapon_primer, weapon_upgrade | |
| 5 | | drone_bay | |
| 6 | battleship ← battlecruiser | railgun_l ← railgun_m | |
| 8 | dreadnought ← battleship | | |
| 9 | carrier ← battleship | drone_hangar | |
Level 0's pool has exactly three entries (a full first dialog). Level 2
is the quartz gate: cruiser and railgun_m are the first schematics whose
chains reach quartz; the shortcut outputs only become implicitly
unlocked alongside them, so shortcuts cannot drop early.
**Threat rate** `2*x + 0.15*x*x` (x = boss cycle counter), against the
factory-size curve with ~half the player's output assumed military:
| cycle x | rate (threat/s) | player military (≈ curve/2) |
|---|---|---|
| 2 | 4.6 | ~12 |
| 6 | 17.4 | ~30 |
| 15 | 63.8 | ~60 |
| 20 | 100 | ~75 |
| 24 | 134 | — |
**Economy:** `starting_building_blocks = 200`; expansion cost formula
`300 + 50*x + 10*x*x` (x = expansions already purchased: ~1 affordable
per cycle mid-game at ~1/3 of block income, stretching to 2–3 cycles
late — quadratic so costs outrun the roughly linear block income
gradually, never with a hard wall); `artifact_win_count = 5` with
`artifact_chance_formula = 0.05*x`. Building costs: belt 2, splitter 3,
tunnels 5, miner 15, smelter 20, assembler 35, reprocessing plant 40,
salvage bay 25, shipyard 60 — averaging ≈18 blocks per placed building
(belts included), which meets the 4-minute doubling target at block
threat 4.

96
docs/balancing/history.md
View File

@@ -1,96 +0,0 @@
# Balancing History
Chronological record of the balancing work: what was decided, what was
found, what changed. Current values live in `derived.md`; this file
explains how they got there.
## 2026-07-02/03 — rules and structural decisions
- Rules document written (now `rules.md`): ratio curve, shortcut
recipes, refactorability, cost archetypes, threat model, growth curve.
- Scrap derived from threat (`scrap_per_threat`), replacing authored
per-ship scrap drops; scrap threat became the constant
`1/scrap_per_threat`, removing the old min-scrap_drop derivation and
its circularity.
- Duplicate schematic drops removed (no level-ups); ship/module levels
removed entirely — all time scaling lives in the threat rate, push
scaling stays on stations. Mk2 upgrade recipes noted as the future
per-item progression.
- Growth-curve rules added: escalating expansion costs, designed
doubling time, growth limited by economy not waiting; resource
deposits designed (deposit-gated mid resource in expansion territory).
- Production tree v2 decided: iron/copper everywhere (M-type asteroid),
quartz in geodes (mid), voidsteel battle-forged from scrap (late);
titanium dropped; lasers renamed to railguns, lasers reserved as a
future weapon type.
## 2026-07-03 — targets, tree, numbers
- Balancing targets fixed: ≤2 h run, phases 1–5/6–14/15+, factory curve
25/60/120/150, threat ladder, 25-ship swarm, block roots.
- Tree structure drafted and numbers computed (recursive threat
calculator); ratio curve realized; fitted ships within 96–124% of the
strawman ladder (small end hot from fixed chain overhead — ladder
later adopted the achieved values).
- **Rule bugs found by the numbers work:** the scrap→ingot smelter
recipe would inflate basic materials via the max rule (fixed:
scrap-consuming recipes are threat fallback only); recipe output
amounts were ignored (fixed: per-unit division); items downstream of
reprocessing-only items never resolved (fixed: fixpoint resolution);
a shortcut recipe resolving earlier than the base path silently
underpriced items (fixed: commit only when all eligible recipes are
computable). All four fixed in `ThreatCostCalculator` with tests, and
implemented in `tools/threat_report.py`.
- v2 tree written into the configs; `default_modules` loadouts
geometry-validated (the numbers-pass loadouts for battlecruiser and
dreadnought were geometrically impossible — L-modifiers don't fit
beside full gun complements; corrected loadouts landed closer to the
ladder).
## 2026-07-04 — combat stats, arena rounds 1–5
Initial stats derived from the anchors (weapon DPS ≈0.6/threat flat,
hull 15 HP/threat, armor 20/threat, repair 2 HP/s/threat, station
range 200).
- **Round 1:** concentrated fleets won all equal-threat cross-tier
matchups flawlessly; glass beat armored; repair escort flawless; two
stations shrugged off a 3× swarm. Changes: concentration tax on m/l
gun damage (railgun_m 17→14, railgun_l 70→52), armor 640→1000,
repair 25→12, station range 200→120. (Team-1 "bias" in mirrors later
shown to be noise.)
- **Round 2 (EHP-margin logging added):** battleship +33% while
dreadnought −37% (stabilizer range + opposing armor); glass still
+11%. Changes: stabilizer range ×1.5→×1.3; per-hull trims introduced
(BC 2700→2500, BS 7500→7000, DN/CV 15500→19000).
- **Round 3 (narrow lanes — geometry fixed into the fixture):**
DN closed to −11%, BS +22%, swarm flipped to +14% over cruisers,
glass +12% third time. Changes: armor 1000→1200, BC 2500→2000,
BS 7000→6300, DN/CV 19000→22500.
- **Round 4:** glass-vs-armored resolved (+3% armored); noise floor
established (~±10%/run: BS ignored a −10% EHP cut; repair drifted
14→24% untouched). Convergence policy adopted: two-round signals only,
±20% converged. Changes: BC 2000→2200, DN/CV 22500→24000; BS +23%
accepted as doctrine texture (mechanical range edge vs. pure small
fleets).
- **Round 5 (durations logged; end-condition bug fixed upstream):**
TTK anchor validated (mirrors 23/71/95 s; DN-vs-swarm 214 s outlier
accepted); dreadnought +3%, everything else inside band. Final
changes: BC 2200→2400, repair 12→9 (persistent +24% escort margin).
**Combat pass declared converged.**
## 2026-07-05/06 — pacing pass
- Unlock ladder set (starting set drone/frigate/railgun_s/salvager;
quartz gate at level 2; capitals at 8–9 with `unlock_requires`
chains); threat rate `2*x + 0.15*x*x`; starting blocks 1000→200;
expansion 400 flat pending the cost formula; artifacts 3→5.
- **Bug found:** the building_block recipe was silently locked at game
start (building blocks appear in no schematic's materials, so implicit
unlocking could never reach the recipe) — fixed with an explicit
`unlock_at_station_level = -1`.
- Expansion cost formula implemented and set (`300 + 50*x + 10*x*x`):
quadratic, so costs outrun the roughly linear block income gradually
— ~1 expansion per cycle mid-game, 2–3 cycles apart late.
- **First full balancing round complete.** Next: full-game playtests
against the run-shape targets.

98
docs/balancing/process.md
View File

@@ -1,98 +0,0 @@
# Balancing Process
How balancing is done in this project: the pass order, the tuning
discipline, and the tools. Refer to this when starting the next
balancing round.
## The pass order
Each pass depends on the ones before it; a change in an earlier pass
invalidates the later ones (but not vice versa). Redo from the earliest
pass whose inputs changed.
1. **Targets** (`targets.md`) — choose the root numbers: run shape,
factory curve, threat-cost ladder, fleet size, block roots, combat
anchors, pacing anchors. These are design decisions, not
measurements. Everything else is derived from them.
2. **Tree structure** (`../content_design.md`) — items, chains,
what-consumes-what, per the production tree rules (one input per
phase transition, generic parts, archetypes, refactorability).
Structure only, no quantities.
3. **Numbers** (`derived.md`, recipes/materials in the configs) —
quantities and durations so every fitted ship sums to its ladder
value, the ratio curve is realized, and the belt/buffer guardrails
hold. Verified computationally by `tools/threat_report.py`.
4. **Calculator/tooling parity** — the game's `ThreatCostCalculator`
and `tools/threat_report.py` must produce identical values; the
Python tool is the design reference. Any semantic change to
REQ-THREAT-* needs both updated plus tests.
5. **Combat stats** (arena-driven) — derive stats from the combat
anchors, then iterate against the arena suite
(`bin/balancing/data/balancing.toml`) until equal-threat matchups are
near-draws. Threat costs are stat-independent, so arena ship counts
stay valid across stat changes.
6. **Pacing** — unlock ladder, `unlock_requires` edges, threat rate,
block/artifact/expansion values, per the pacing anchors.
Then: **full-game playtests**, which are the only check for the pacing
pass and feed back into targets.
## Tuning discipline (learned in arena rounds 1–5)
- **Change anchors, not symptoms.** When a class of results is off,
adjust the anchor that explains all of them (e.g. the concentration
tax) rather than individual stats.
- **Fewest knobs per round.** Attribution dies when many knobs move at
once. Prefer one anchor change plus its mechanical compensations.
- **Shared vs. local knobs.** Guns and module stats are shared across
many hulls — changing them moves many matchups. Per-hull HP moves
exactly one matchup; it is the designated per-ship trim knob on top of
the HP-per-threat prior.
- **Mind the ride-alongs.** A module buff lands on every default loadout
containing it (e.g. an armor buff strengthens the destroyer swarm that
opposes the dreadnought). Compute the net effect per matchup before
choosing step sizes.
- **Two-round signal policy.** Single arena runs re-roll by ~±10% EHP
margin; a margin inside ±20% counts as converged for v1. Only act on
signals that persist across two rounds.
- **Arena geometry is part of the fixture.** Lane width/height changes
the results (full engagement vs. fleets slipping past); margins are
only comparable within the same geometry.
- **Accept mechanical texture.** Not every deviation is a bug: a margin
that survives a stat change is mechanical (usually range/kiting under
the orbit AI) and may be desirable doctrine texture. Document the
acceptance in `targets.md` instead of chasing it.
- **Range is the strongest stat** under the orbit AI — free approach
fire. Price range modifiers conservatively; station dominance is
controlled via range, not HP.
## Tools
- `tools/threat_report.py` — item threats, module contributions,
hull/fitted ship threats, producer:consumer ratios, belt feasibility;
reads the real configs. The design reference for threat semantics.
- `tools/verify_recipes.py` — recipe tree closure, visuals coverage,
orphans, reprocessing-only items.
- `tools/verify_layouts.py` — module footprint gating matrix per hull.
- **Balancing tool** (`balancing` target) — parallel arena simulation of
`bin/balancing/data/balancing.toml`; logs winner, surviving counts,
team EHP %, and fight duration per arena. The suite covers: class
mirrors (expect near-mutual annihilation, symmetric winners),
equal-threat cross-tier matchups (expect near-draws — power-per-threat
made empirical), a 2:1 decisiveness check, doctrine matchups
(armored-vs-glass, repair-escort), and station assault.
## Checklist for the next balancing round
1. Pull; run `verify_recipes.py`, `verify_layouts.py`,
`threat_report.py`; compare against the tables in `derived.md`.
2. If recipes/materials changed: re-check fitted threats vs. the ladder
in `targets.md`; update arena suite ship counts if fitted values
moved.
3. Run the arena suite; read EHP margins and durations against the
expectations noted in `balancing.toml` and the anchors.
4. Apply changes per the tuning discipline (two-round signals only);
record the round and its knob changes in `history.md`.
5. Update `derived.md` where values moved; if an anchor moved, update
`targets.md` and state why.
6. Commit and push (the review workflow reads the remote).

333
docs/balancing/rules.md
View File

@@ -1,333 +0,0 @@
# Balancing & Progression Rules
Rules and principles that govern the production tree, progression pacing,
and balancing. This document contains **rules only** — the chosen base
numbers live in `targets.md`, everything derived from them in
`derived.md`, and the concrete content in the config files and
`../content_design.md`. All of those must follow the rules stated here.
## Player-experience goals
What each phase of a run should feel like:
- **Early:** learning belts and ratios with forgiving chains. The building
block economy is the main constraint; the player bootstraps a
self-sustaining factory from the starting stock.
- **Mid:** deeper chains, the first real ratio puzzles, and the first
meaningful drop decisions (which schematic, when to push).
- **Late:** combat feeds the factory — capital production requires salvage.
Progress means extending and refactoring the existing factory, not
rebuilding it. Strange ratios are deliberate optimization puzzles.
Overarching: an experienced player gains efficiency through **knowledge** —
layout foresight, understanding chains, exploiting shortcut recipes — never
through hidden mechanics. An inexperienced setup should not cost much more
than an experienced one; experience pays off in how easily the factory
adapts later (see Refactorability).
## Resource phases
- A run has exactly **four base inputs**:
1. Two mined resources available from the start, minable on **every**
asteroid tile.
2. A third mined resource unlocked mid-game, minable **only on deposit
patches** found in expansion territory (see Resource deposits).
3. A fourth input unlocked late-game, obtainable **only** from
reprocessing salvaged scrap.
- The fourth input is the core loop hook: capital ship production requires
fighting (salvaging and reprocessing), not just mining.
- Every gating has a fictional reason (concrete fiction in
`../content_design.md`): the asteroid is a metal-rich body, so its bulk
rock is minable anywhere; the mid resource sits in rare pockets; the
late input is battle-forged — created only in the violence of ship
destruction, which is why any wreck (including the player's own)
yields it and no foundry can make it.
- The mid resource is **dual-gated**: schematics (knowledge, via drops)
and territory (deposits, via expansions). Tuning must guarantee the
deposit-bearing expansion is comfortably affordable by the time the
first mid-tier schematics drop, or those drops are dead picks.
- There is no direct "resource unlock" mechanism. Miner recipes unlock
**implicitly** (REQ-LOCK-IMPLICIT) when some unlocked schematic's material
chain reaches that resource. Resource pacing is therefore controlled
through the `unlock_at_station_level` values of ships, modules, and
assembler recipe schematics — and the content must guarantee that the
chains actually connect (a mid-game schematic must require an item whose
chain reaches the mid resource, or it never unlocks).
### Resource deposits
- **Rule: freedom first, geography later.** The starting resources are
minable everywhere, so the player has full layout freedom while
learning. Later mined resources are bound to deposit patches — fixed
geography as a layout puzzle, introduced once the player is competent.
- **Rule: deposits exist only in expansion territory.** Expansions buy
space *and* access to resource tiers — the second leg of the growth
curve (see Building block economy).
- **Rule: patch area is the throughput cap.** Deposits never deplete but
are finite in area; the number of deposit tiles caps how many miners
the chain supports. Buying deeper expansions raises the throughput
ceiling of high-tier chains.
- **Rule: no empty expansions.** Deposit content per expansion is
deterministic and config-defined; only the placement within the new
columns is randomized. Buying an expansion never rolls "nothing".
- **Rule: mining is binary.** A miner whose footprint overlaps at least
one deposit tile of a resource can select that resource's recipe; no
partial-coverage rate scaling.
- Deposits arrive at the periphery (expansions add columns on the left),
so each new chain starts in fresh space — supporting the
refactorability property — and high-tier chains have the longest belt
runs to the shipyards, escalating the logistics puzzle with tier.
## Production tree rules
### Structure
- **Each phase transition adds exactly one new base input chain.** A base
input is a bottom-level resource entering the factory from outside — a
mined resource or the scrap-only input. The early game starts with two
ores as the baseline; the transition to mid adds one (the deposit-bound
mid resource), the transition to late adds one (the scrap-only input).
No transition ever introduces more than one unfamiliar bottom-level
chain, so the factory grows in one direction at a time.
- **Intermediates are generic shared parts.** Keep the item count low —
modules and hulls of a tier draw from a shared pool of that tier's and
lower tiers' intermediates rather than each having bespoke inputs.
- **Thematic naming over thematic items.** Inputs should be plausible for
what the recipe produces (crystals for lasers, heat sinks for bigger
lasers). Achieve this through naming and chain membership, not by adding
item types: rename a generic part, don't add a parallel one.
### Ratios
- **Ratio "niceness" degrades with tier.** The producer:consumer ratios
needed for 100% throughput follow a curve:
- Tier 1 (ore → basic material): trivially nice (e.g. 1:1 or 1:2
miner:smelter).
- Tier 2: slightly complex but still clean (e.g. 2:3).
- Higher tiers: increasingly strange ratios, as deliberate optimization
puzzles.
- Exceptions in both directions are allowed when there is a reason — a
clean late chain as a breather, an odd early chain as a teaser — but the
curve is the default.
### Shortcut recipes
- Some strange chains get a **shortcut recipe**: an explicitly unlockable
assembler recipe schematic (`unlock_at_station_level ≥ 0`, drop-only per
REQ-LOCK-EXPLICIT) that skips a step (e.g. t1 → t3 directly) and yields
nice ratios for a chain whose base path is strange.
- **Not every strange chain gets a shortcut.** Some strangeness is
permanent; the absence of a fix is a valid design choice.
- **Shortcuts drop only for known chains.** A shortcut recipe enters the
drop pool only when both its input items and its output item are
already unlocked (in addition to the station level check). The player
is never offered a shortcut for a chain they have not built yet. The
output-item half of this check already exists in
REQ-DEF-SCHEMATIC-DROP; the input half is an open action item (see
`README.md`).
- **Shortcuts are pure rewards, never balance factors.** An item's threat
value is the *maximum* across its producing recipes (REQ-THREAT-ITEM), so
unlocking a cheaper recipe does not lower the item's threat accounting —
the player gains real factory efficiency without their ships being
valued cheaper and without enemy wave budgets shifting. Consequently:
**balance every chain around its base (expensive) path**; the shortcut's
savings define the size of the reward.
### Refactorability
- **Rule (the property):** unlocking the next tier or size of a thing must
be a *local edit* of the existing production line — adding assemblers
and belts, or replacing a machine or two in place — never a rebuild of
the line.
- **What this buys the player:** foresight pays off in space, not blocks.
An experienced player leaves a little slack in the middle of a line,
knowing the next size or tier upgrade means tearing out one assembler
and a few belts there and inserting the new step — plus maybe swapping
a recipe or two elsewhere — while the rest of the line keeps running
untouched.
- **Default technique:** the bigger version introduces one new intermediate
that is produced from a subset of the smaller version's inputs (possibly
plus one additional low-tier material), and otherwise reuses the smaller
version's inputs. Existing lines keep running and feed the new
intermediate's assemblers.
- The property is the rule; the technique is only the default. It may be
broken where it fights thematic plausibility, as long as the property
still holds.
## Cost archetypes
Every item has two cost knobs: **material quantity** and **cycle time**.
Both feed the threat value identically (threat = recursive
production-seconds, REQ-MOD-THREAT), so the split between them does not
change what an item is *worth* — it changes what kind of **factory
pressure** it creates:
- **Material-heavy, fast** (e.g. armor plates): simple items; stress belt
throughput, splitter logistics, and miner/smelter counts.
- **Time-heavy, lean** (e.g. shield modules): technically complex items;
few inputs — possibly higher-tier ones — but long cycles; stress
assembler counts and parallelization.
**Rule:** each module family commits to a clear archetype, so factories
supporting different fleet doctrines feel structurally different to build.
## Threat model (balancing backbone)
- Threat cost = total recursive production-seconds (REQ-MOD-THREAT). One
factory-second equals one threat; player output and enemy wave budgets
are denominated in the same currency.
- **Rule: combat power per threat is roughly constant** across all ships,
modules, and tiers. Higher tiers are better per *ship* and per *module
slot*, not per invested factory-second — their advantage is
concentration (fewer, bigger things; slot geometry per
`../content_design.md`) and qualitative capabilities, not a better
exchange rate. Deviations from this rule are deliberate and documented.
- **Difficulty race:** the enemy threat rate (`threat_rate_formula`) is
tuned against the factory output (threat/s) achievable by a competent
player — slightly below it early, crossing above it eventually. The game
is endless; enemy scaling must ultimately outpace any factory, and
player skill shifts *when*, not *whether*.
- **All time scaling lives in the threat rate** — waves get bigger, ships
of a given schematic never get individually stronger. There is no ship
level dimension: stat formulas are plain values, and per-ship level
scaling does not exist. Push scaling on enemy defence stations is the
separate, player-triggered difficulty axis and keeps its level formulas.
## Unlock & drop pacing
- **Starting set rule:** the schematics unlocked at game start
(`unlock_at_station_level = -1`) must be exactly enough to reach the
first push unaided — a functioning block loop, small hulls, a basic
weapon, and the salvage loop. Nothing more.
- The `unlock_at_station_level` ladder mirrors the resource phases:
mid-tier hulls/modules/recipes at low station levels, capital content at
higher levels. A schematic must not become available before the chains
its materials need can be unlocked alongside it.
- **Schematics can require other schematics.** Beyond the station-level
gate, a schematic (ship, module, or assembler recipe) may list
prerequisite schematics (`unlock_requires`, REQ-LOCK-PREREQ) that must
already be unlocked before it enters the drop pool — e.g. the medium
gun requires the small gun; a future Mk2 requires its base version.
Station level gates the earliest *when*; prerequisites gate the
*order*, keeping drop offers coherent with what the player already
owns.
- **No duplicate drops.** Ship and module schematics leave the drop pool
once owned, exactly as assembler recipe schematics already do. There are
no schematic level-ups; player power grows through unlock breadth and
factory scale only, which keeps power-per-threat exact on both sides.
The pool therefore shrinks over a run and late pushes increasingly offer
artifacts — intended: the late game is a race for the win condition.
Per-item progression may return later as Mk2 upgrade recipes (see Future
work), never as free level-ups.
- **Artifacts trade power for progress.** Artifact options compete with
schematic picks in the same choice dialog; the artifact chance must be
tuned so that taking one is a real decision (giving up an unlock), not
automatic in either direction.
## Scrap & reprocessing economy
- Scrap is the bridge from combat back into the factory, with two sinks:
**smelting** (same basic materials as ore — the safe, boring option) and
**reprocessing** (probabilistic higher intermediates, including the
late-game input — the gamble that eventually becomes mandatory).
- The reprocessing output pool renormalizes over implicitly unlocked items
(REQ-LOCK-REPROCESSING-POOL), so its output quality improves
automatically as the run progresses. **Rule:** weights are authored for
the *fully unlocked* pool state; early-game behavior falls out of
renormalization for free and needs no separate staging.
- **Rule: ship scrap drops are derived, never authored.** A destroyed ship
drops `threat cost × scrap_per_threat` (a `world.toml` key), with the
threat cost computed from its actual hull plus installed modules
(REQ-MOD-THREAT) — a kitted-out ship drops more scrap than a bare hull
automatically. `ships.toml` carries no scrap value. Defence stations are
the exception: they keep authored `scrap_drop_formula`s, because pushing
rewards are tuned independently of ship production costs.
- Consequence: the threat value of scrap is the constant
`1 / scrap_per_threat` (REQ-THREAT-SCRAP). The former min-`scrap_drop`
schematic derivation and its potential circularity are gone.
- **Rule:** the late-game input's income rate meaningfully gates capital
production — unlocking a capital hull must not mean spamming it; the
input trickles in slowly enough that every capital ship is a noticeable
investment. The tuning target is relative, not absolute: assume a
reference player who destroys and salvages roughly the threat the game
spawns ("fighting at parity"), and tune `scrap_per_threat`, the
reprocessing weights, and capital material costs so that this player
affords roughly N capital ships per boss cycle. An absolute income rate
would be meaningless (income depends entirely on how much the player
fights) and would not self-scale; per boss cycle, the target tracks the
threat rate as it steps up.
## Building block economy
- Building blocks are the only global currency and the early game's
central constraint. The early game is a bootstrap problem: convert the
starting stock into a self-sustaining block loop before the first waves
bite.
- **Rule:** the starting stock suffices for a minimal block loop plus the
first shipyard — with a little slack for beginner mistakes, but not
enough to skip the loop entirely.
- **Rule: the growth curve lives here.** A saturated building produces
exactly 1 threat/s, so the player's output curve *is* their
building-count curve — shaping growth over a run means shaping the
block and space economy, there is nowhere else it can live. Intended
shape: exponential bootstrap (block-limited) → ramp
(expansion-limited) → asymptotic squeeze as expansion costs outrun
income, racing the enemy threat rate throughout.
- **Rule: escalating expansion costs.** Expansion cost is a formula of
the number of expansions already purchased, rising steeply enough that
expansions eventually outrun any block income. The starting asteroid
is deliberately small — filled within the first boss cycle or two, so
the early exponential burst is a satisfying ramp, not a balance hole —
and from then on the output curve is the expansion curve. Blocks keep
a meaningful sink for the entire run, and "grow vs. army" stays a live
decision at every moment.
- **Rule: designed doubling time.** Block production is a positive
feedback loop (blocks buy assemblers, assemblers make blocks); its
time constant is a designed quantity, never an accident of quantity
choice. The block chain's depth and the per-building costs are tuned
against a stated target of the form: "a factory spending X% of its
capacity on blocks doubles in ~T minutes."
- **Rule: growth is limited by economy, never by waiting.** Construction
times stay short; the serial build queue must not be used as a growth
brake. Waiting for placed buildings to become operational — especially
at the start of a run — is frustration, not gameplay. All growth
limiting comes from block income and expansion pricing.
- Note: block income has a structural ceiling — blocks enter the stock
through the HQ's single belt port, so income is capped at belt
throughput regardless of assembler count. Per-building costs should be
high enough that this cap can bind late-game (see the condensed-block
idea under Future work).
## Numeric guardrails
Constraints that every recipe must respect, independent of tuning:
- **Belt throughput:** belt speed and per-tile capacity cap how fast a
single belt can feed an input. A recipe whose per-cycle inputs cannot be
sustained by one belt per input at 100% duty cycle is a *deliberate*
design (forcing parallel belts/splitters as part of a high-tier puzzle)
— never an accident of quantity choice.
- **Buffer burstiness:** input buffers hold 2× the per-cycle amount
(REQ-MAT-INPUT-BUFFER), so large per-cycle quantities create bursty belt
demand. Low tiers prefer small quantities with short cycles; big-batch
recipes are reserved for high tiers where burstiness is part of the
puzzle.
- **Cycle times scale with tier** monotonically — a higher-tier item never
has a shorter total chain time than a lower-tier item of the same role.
## Future work
- **Condensed building blocks** — a drop-unlockable shortcut-style
recipe that packs several blocks' worth of value into one belt item,
relieving the HQ intake ceiling (see Building block economy) as a
late-game reward. The ceiling is the puzzle, the drop is the fix —
same philosophy as shortcut recipes.
- **Mk2 upgrade recipes** — the deferred design for per-item progression,
to revisit once the config has stabilized. A duplicate-style drop
unlocks a distinct `*_mk2` item whose recipe consumes the Mk1 item plus
higher-tier parts. This preserves power-per-threat (the extra power is
paid in real production-seconds, since threat is recursive), satisfies
the refactorability rule (the Mk1 line keeps running and feeds one new
assembler), and keeps balancing one-dimensional (no level variable
anywhere). Enemy-side progression happens via `default_modules`
variants per era instead of a level formula.

104
docs/balancing/targets.md
View File

@@ -1,104 +0,0 @@
# Balancing Targets (base numbers)
The root numbers of the balancing. Everything in `derived.md` is tuned to
hit these; when rebalancing, **change these first and re-derive — never
patch derived values directly**. The rules these numbers follow live in
`rules.md`.
All time targets are in **game time**. The player can pause and
accelerate, so real session length differs; playtests measure both. The
time unit is the boss cycle (`world.toml boss_countdown_seconds`, 300 s).
Destroying a station set advances the boss countdown by
`boss_advance_seconds` (60 s), so cycles run shorter than nominal when
pushing actively — targets deliberately ignore that.
## Run shape
1. **Run length** — a winning run takes up to 2 hours of game time: win
around boss cycle 20–24. Losing runs end earlier.
2. **Phase boundaries** — early = cycles 1–5 (iron/copper, small hulls),
mid = cycles 6–14 (quartz, medium hulls), late = cycles 15+
(voidsteel, capitals). Push cadence: first station set around cycle
2–3, roughly one per cycle from mid onward — so the destroyed set's
level ℓ is reached around cycle ℓ+2.
3. **Factory size curve** — producing buildings over time; when
saturated, output threat/s equals this count, so this curve IS the
player power curve: ~25 when the starting asteroid is full (end of
cycle 2), ~60 at the start of mid (cycle 6), ~120 at the start of
late (cycle 15), ~150 near the win. `threat_rate_formula` must remain
a fraction of this curve; buildings plus belts must physically fit
the asteroid plus affordable expansions.
4. **Threat-cost ladder** — total production-seconds per *fitted* hull
(including the typical/default module loadout): drone 10.5,
frigate 47, destroyer 99, cruiser 233.5, battlecruiser 354.5,
battleship 722.5, dreadnought 1491.5, carrier 1436.5. Every
production chain must sum to its ladder value. (The original strawman
was 10/40/80/200/350/700/1500; the small end runs ~10–20% hot because
fixed chain overhead dominates small hulls — accepted, and the
achieved values adopted as the ladder. The ~×2-per-class curve shape
is the invariant.)
5. **Fleet size** — swarm-leaning: ~25 player combat ships as the
standing mid-game fleet. Standing fleet = build cadence (4) × average
ship lifetime, so this target drives time-to-kill and therefore all
combat stat magnitudes.
6. **Block economy roots** — bootstrap complete (starting asteroid full)
by the end of cycle 2; a factory spending ~30% of its capacity on
blocks doubles in ~4 minutes early game; one expansion affordable per
cycle at ~1/3 of block income mid-game, decelerating to one per 2–3
cycles late as escalating costs outrun income.
## Combat anchors
All combat stats derive from these; per-hull HP additionally carries
empirical trims from arena rounds (values in `derived.md`).
- **Weapon DPS per threat pays a concentration tax that grows with gun
size**: small ≈ 0.62, medium ≈ 0.48, large ≈ 0.41 DPS per threat of
weapon contribution, compensated by the range ladder 50/70/100 m.
Rationale: concentration itself (focus fire, no DPS loss to attrition,
range) is worth paying for — with a flat curve, concentrated fleets
win equal-threat fights outright (arena round 1).
- **Hull HP = 15 per threat of hull contribution** as the prior; per-hull
HP is the empirical trim knob (guns are shared across hulls, hull HP
moves exactly one matchup). The arena consistently prices capitals as
*tanks with taxed guns* — capital hulls sit well above the prior.
- **Armor HP ≈ 37 per threat** — a strong premium over hull HP because
armor is pure HP with no capability, and fights snowball: killing
removes enemy DPS, surviving merely delays — HP must be cheaper than
DPS.
- **Repair ≈ 0.7 HP/s per threat** — in-combat sustain effectively
removes enemy DPS and must be priced like DPS, not like HP.
- **TTK / fight duration**: parity fights in the 30–60 s band at
mid-game scale; capital mirrors ~90 s deliberately; the extreme
tank-vs-chip-damage matchup (dreadnought vs destroyer swarm, ~3.5 min)
is an accepted outlier.
- **Mobility is monotone in size** — the smallest hulls are the fastest
and nimblest. Sensor ranges (150→350 m) always exceed weapon ranges.
- **Weapon modifiers are capital economy**: a ×1.2 damage modifier at
~22.5 threat beats adding a gun once a ship carries more than ~68
threat of weapons — modifiers pay off on gun-heavy big hulls, waste on
small ones. Range modifiers are the strongest and are priced/kept
small (×1.3): range is the dominant stat under the orbit AI (free
approach fire).
- **Stations**: a fresh player station holds one early parity wave
unaided; the enemy station at level 0 matches the player station
exactly and scales per push level. Station range is the dominance
lever, not HP (at 4× a small gun's range, two stations annihilated a
3× threat swarm through approach fire alone).
- **Accepted imbalances**: the carrier loses its equal-threat fights
until the drone-launching capability exists (the hangar is dead
threat) — fix by implementing drones, not stats. A pure smallest-ship
fleet modestly loses (~15–25%) to a range-fitted capital — desirable
doctrine texture; the fair anti-capital answer is the mixed fleet.
## Pacing anchors
- **Starting set** is the rule-minimum: drone, frigate, small gun,
salvager (plus the explicitly unlocked building-block recipe).
- **Threat rate shape**: below the player's achievable military output
(≈ half the factory curve) early, crossing at the late boundary
(~cycle 15), overwhelming by ~cycle 24.
- **Winning = five real decisions**: `artifact_win_count` is set so that
across a winning run's ~15–18 pushes (~7 cumulative artifact offers at
the current chance formula), the player must choose the artifact over
a schematic about five times.

19
docs/concept.md
View File

@@ -2,7 +2,7 @@
## Overview
A single-player asymmetric game inspired by DOTA's wave/tower structure, combined with a Factorio-style factory builder. The player builds a factory on an asteroid to supply shipyards that produce autonomous combat ships. Those ships fight off enemy waves advancing from the right, with tougher boss waves arriving periodically. Pushing into enemy territory and destroying their defence stations occasionally yields artifacts, which are used to upgrade the HQ; the goal is to upgrade the HQ enough to launch it into space, winning the game.
A single-player asymmetric game inspired by DOTA's wave/tower structure, combined with a Factorio-style factory builder. The player builds a factory on an asteroid to supply shipyards that produce autonomous combat ships. Those ships fight off endless enemy waves advancing from the right. The goal is to survive as long as possible; elapsed time is always displayed.
## Setting & Visuals
@@ -62,26 +62,21 @@ Two sources feed the same production tree:
- Waves consist of a single enemy ship type whose stats scale with difficulty.
- Waves spawn over several seconds; a gap follows before the next wave begins spawning. The previous wave may still be approaching or fighting during the gap.
- A tougher **boss wave** spawns periodically on its own countdown, on top of normal waves.
- Enemy strength increases gradually over time and with each boss wave that occurs.
- Difficulty scales multiplicatively from two sources:
- **Time scaling** — enemy strength increases gradually over elapsed time.
- **Push scaling** — destroying a set of enemy defence stations multiplies enemy strength by a configurable factor. The replacement stations are scaled by the same factor.
## Push Mechanic
- The player must push — destroying enemy defence stations is the only way to earn artifacts, which are required to win.
- Destroying a set of enemy defence stations advances the boss countdown (bringing the next, stronger boss wave sooner), extends the scrollable area, and places a new (stronger) set of stations at the new boundary.
- Destroyed enemy defence stations drop either a ship/module schematic or, occasionally, an artifact.
## Win Condition
- Artifacts are gathered by defeating enemy defence stations instead of taking a schematic reward.
- Artifacts are used to upgrade the HQ. Once the HQ is upgraded enough, the player can launch it into space — this is how the game is won.
- The player is not forced to push; purely defensive play is valid.
- Destroying enemy defence stations applies the push scaling multiplier to all future waves, extends the scrollable area, and places a new (stronger) set of stations at the new boundary.
- Destroyed enemy defence stations drop ship schematics.
## Starting Conditions & Game Over
- The player starts with the HQ and player defence stations pre-placed and a stock of building blocks; no other buildings are pre-placed.
- There is a grace period before the first wave to allow initial setup.
- If all ships and player defence stations are destroyed, enemies attack the HQ. The game is lost when the HQ is destroyed. Factory buildings are never targeted.
- The game is won when the player launches the HQ into space (see Win Condition).
## Asteroid Expansion

218
docs/content_design.md
View File

@@ -1,10 +1,9 @@
# Content Design — Ships, Modules & Production Tree
# Content Design — Ships & Modules
The designed game content: hull layout grids, module footprints and the
gating between them, and the production tree (items, chains, fiction).
All numbers — quantities, durations, threat values, stats, unlock levels
— live in the config files and are documented with their derivations in
`docs/balancing/` (see `balancing/README.md` for the index).
First real-content iterations (June 2026). Pass 1 defined ship hull grids and
module surface masks; pass 2 defined the production tree (recipes). Stats and
threat costs in the config files are still placeholders for the balancing
pass.
## Design principle: footprint gating
@@ -18,12 +17,12 @@ and makes them trivially moddable through the config files alone.
| Footprint | Modules | Smallest hull that fits it |
|-----------|---------|----------------------------|
| 1x1 | railgun_s, salvager, repair_tool | drone |
| 1x1 | laser_cannon_s, salvager, repair_tool | drone |
| 1x2 | maneuvering_thrusters, sensor_booster, armor_plates | frigate |
| 1x3 | afterburner | frigate (eats most of it) |
| L-shape (3 cells) | weapon_stabilizer, weapon_primer, weapon_upgrade | frigate |
| 2x2 | railgun_m, drone_bay | cruiser |
| 3x3 | railgun_l | battleship |
| 2x2 | laser_cannon_m, drone_bay | cruiser |
| 3x3 | laser_cannon_l | battleship |
| 2x6 | drone_hangar | carrier (only) |
### Hull grids
@@ -132,163 +131,64 @@ drone hangar — carrier 1.
## Production tree
Designed against the rules in `docs/balancing/rules.md` (ratio curve,
cost ladder, cost archetypes, refactorability). Quantities, durations,
and threat values live in `docs/balancing/derived.md`.
Design principle: each game phase adds exactly one new base input chain, so
factory complexity ramps alongside ship size.
### Base inputs (4) and fiction
| Phase | New input | How acquired | Unlocks |
|-------|-----------|--------------|---------|
| early | iron_ore, copper_ore | mined | drone, frigate, destroyer; small guns and basic supports |
| mid | titanium_ore | mined (3x slower than iron) | cruiser, battlecruiser; m guns, drone bay, weapon modifiers |
| late | advanced_alloy | ONLY from reprocessing salvaged scrap | battleship, dreadnought, carrier; l guns, drone hangar |
- **iron_ore, copper_ore** — from the start, minable on every asteroid
tile. Fiction: the asteroid is an M-type (metal) body — its bulk rock
*is* ore, which is why the shipyard operation was built here at all.
- **quartz** — mid-game, minable only on geode deposit patches in
expansion territory (see the Resource deposits rules in
`docs/balancing/rules.md`; the deposit mechanic itself is an open
action item — until it lands, quartz mines anywhere). Fiction:
ordinary silicate dust is everywhere and worthless; chips and optics
need rare, pocket-bound optical-grade crystal.
- **voidsteel** — late-game, obtained only by reprocessing scrap.
Fiction: battle-forged — formed when weapon plasma anneals hull metal
in the violence of ship destruction. Any wreck yields it, including the
player's own; no foundry can replicate it.
- **titanium was dropped** (v1 tree). Its hull-gating role moved to
quartz-era control systems ("you can smelt all the steel you want, but
you cannot steer a battlecruiser without electronics") plus the
hardened-steel quality step (a deliberately long-running, time-heavy
recipe) — explicitly not sheer steel quantity alone.
The advanced_alloy gate is the core loop hook: capital ship production
requires fighting (salvaging scrap from kills and reprocessing it), not just
mining. The reprocessing plant turns 5 scrap into iron/copper/titanium ingots
or advanced_alloy probabilistically.
### Material palette (fingerprints per family)
Intermediate components, by tier:
- **iron/steel** — structure.
- **copper** — conduction and heat: wiring, coils, heat sinks.
- **silicon family** (all derived from quartz): silicon (logic,
sensors), ceramics (heat shielding, insulators); glass/optics are cut
from v1 — their only consumers would be lasers, which are deferred.
- **voidsteel** — capital-tier structure and exotics.
- Deliberately skipped: carbon (mostly redundant with copper/ceramics),
plastics (drags in Factorio-style chemical chains; ceramics read more
sci-fi anyway), volatiles/ice (materials are build costs only — no
consumption mechanic to justify fuel).
- **Tier 2 (early):** copper_wire (copper), steel_plate (iron), circuit_board
(iron + wire), building_block (iron).
- **Tier 3 (mid):** mechanical_parts (steel + iron), targeting_unit (circuits
+ wire), drive_unit (steel + mechanical_parts + circuit), titanium_frame
(titanium + steel).
- **Tier 4 (late):** reinforced_plating (steel + advanced_alloy),
capital_core (targeting_unit + drive_unit + 2 advanced_alloy).
### Weapons
Hulls and modules consume intermediates of their tier: early items are built
from tier-2 parts, midgame items require tier-3 parts (deeper chains, more
assemblers), capital items require tier-4 parts (and therefore combat). Hull
items are named `<ship>_hull`; module items `<module>_module`. Every item has
an `[items.*]` entry in visuals.toml; hull item outlines match the ship's
fleet color from `[ships.*]`.
- All v1 weapons are **railguns** (`railgun_s/m/l`, renamed from the
laser placeholders; footprints and the gating matrix unchanged).
Implementation is instant damage application with no projectile and no
ammunition — the beam visual reads as a tracer round. Materials: iron
slugs, copper coils, steel rails — the starting-metal fingerprint.
- **Lasers are reserved for later** as a genuinely distinct weapon type
(e.g. once projectile/ammunition mechanics exist for other families),
arriving with quartz optics. More weapon types are planned; railguns
are simply the baseline tech that ships with v1.
- `drone_bay` and `drone_hangar` are footprint-only placeholders: the
drone-launching capability does not exist in the simulation yet, so
they define no capability section. The carrier is deliberately weak
until that capability lands (see the accepted imbalances in
`docs/balancing/targets.md`).
### Tree structure
Input lists only — quantities, durations, and per-item threat values are
in `docs/balancing/derived.md` and the configs.
**Mined (miner):** `iron_ore`, `copper_ore` (every tile), `quartz`
(geode deposits in expansion territory).
**Smelted (smelter — exactly one recipe per input item):**
| output | input | ratio class |
|---|---|---|
| iron_ingot | iron_ore | nice (1:1) |
| copper_ingot | copper_ore | nice |
| silicon | quartz | mid entry |
| iron_ingot | scrap | the safe, boring scrap sink |
**Reprocessing pool (scrap):** `iron_ingot`, `copper_ingot`, `silicon`,
`voidsteel` — the only source of voidsteel. Weights authored for the
fully unlocked pool state.
**Tier 2 — early intermediates (clean ratios, ~2:3):**
| item | inputs | role |
|---|---|---|
| steel_plate | iron_ingot | structure backbone, highest volume |
| copper_wire | copper_ingot | conductors |
| copper_coil | copper_wire | electromagnets: railguns, thrusters |
| building_block | steel_plate | depth-3 chain = the doubling-time knob |
**Tier 3 — mid intermediates (strange ratios begin, need quartz):**
| item | inputs | role |
|---|---|---|
| control_chip | silicon + copper_wire | electronics gate for m+ hulls |
| capacitor_bank | copper_coil + silicon | power for railgun m/l |
| hardened_steel | steel_plate (long cycle) | quality gate for m+ hulls; time-heavy |
| ceramic_plate | quartz | heat shielding: drives, l guns, capitals |
| drive_unit | steel_plate + copper_coil + control_chip | propulsion for m+ hulls |
**Tier 4 — late intermediates (need voidsteel):**
| item | inputs | role |
|---|---|---|
| voidsteel_plate | voidsteel + hardened_steel | capital structure |
| capital_core | voidsteel + capacitor_bank + control_chip | capital heart |
**Hull items** (`<ship>_hull`, assembler-made; the shipyard consumes the
hull item plus module materials). The m+ hull gate is **both**
hardened_steel (quality steel, the time-heavy step) *and* control_chip
(electronics):
| hull | inputs |
|---|---|
| drone_hull | iron_ingot |
| frigate_hull | steel_plate + copper_wire |
| destroyer_hull | steel_plate + copper_coil |
| cruiser_hull | hardened_steel + control_chip |
| battlecruiser_hull | hardened_steel + control_chip + drive_unit |
| battleship_hull | voidsteel_plate + drive_unit + control_chip |
| dreadnought_hull | voidsteel_plate + capital_core + drive_unit |
| carrier_hull | voidsteel_plate + capital_core + drive_unit |
**Module items** (`<module>_module`, assembler-made prefabs — kept as
items so shipyard belt inputs stay simple and module production can be
stockpiled):
| module | inputs | archetype |
|---|---|---|
| railgun_s | copper_coil | lean |
| salvager | steel_plate + copper_wire | balanced |
| repair_tool | steel_plate + copper_wire | balanced |
| armor_plates | steel_plate (many) | material-heavy, fast |
| maneuvering_thrusters | steel_plate + copper_coil | balanced |
| sensor_booster | copper_wire + copper_coil | lean (an antenna, no chip) |
| afterburner | copper_coil + steel_plate | balanced |
| weapon_stabilizer | steel_plate + copper_coil | balanced |
| weapon_primer | capacitor_bank + copper_coil | mid; time-heavy |
| weapon_upgrade | control_chip + copper_coil | mid; time-heavy |
| railgun_m | capacitor_bank + steel_plate + copper_coil | mid |
| drone_bay | control_chip + steel_plate + copper_coil | mid |
| railgun_l | capacitor_bank + hardened_steel + ceramic_plate | late |
| drone_hangar | voidsteel_plate + control_chip + drive_unit | late (carrier only) |
**Refactorability check** (the default technique holds): railgun_s → m
introduces capacitor_bank, built from a subset of the small gun's inputs
(copper_coil) plus the new base resource (silicon); the m gun otherwise
reuses the small gun's inputs. Hulls likewise: the cruiser adds
hardening (fed by the existing steel line) and chips (fed by the new
quartz territory) without touching the iron/copper core.
**Shortcut recipes** (drop-only assembler schematics; not every strange
chain gets one): `iron_ore → steel_plate` (skips the ingot step on the
highest-volume chain), `quartz → control_chip` (skips silicon),
`iron_ingot → hardened_steel` (a nicer-ratio route past the deliberately
awkward hardening step).
Consistency is checked by `tools/verify_recipes.py` — re-run it after
editing recipes, ship/module materials, or visuals:
Consistency is checked by `tools/verify_recipes.py` — re-run it after editing
recipes, ship/module materials, or visuals:
python dota_factory/tools/verify_recipes.py
It verifies every consumed item has a producer, every item has a visuals
entry, flags orphaned items, and prints which items are
reprocessing-only (currently exactly voidsteel).
entry, flags orphaned items, and prints which items are reprocessing-only
(currently exactly advanced_alloy).
## Deliberate placeholders / open questions for later passes
- All new hulls have `threat.cost_formula = "0"` so enemy waves do not spawn
them yet (WaveSystem treats any ship with positive threat cost as wave-
eligible, regardless of unlock level). The balancing pass should set real
threat costs together with `default_modules` loadouts so waves spawn them
armed.
- All new hulls and all assembler recipes are `unlock_at_station_level = -1`
(available from the start) to make testing easy; the balancing pass should
stagger these so mid/lategame recipes drop as schematics from enemy defence
stations.
- Recipe quantities and durations are a first guess, deliberately roughly
tiered (capital hulls ~60 s, drones 4 s); the balancing pass tunes them.
- `drone_bay` and `drone_hangar` are footprint-only placeholders: the drone
launching capability does not exist in the simulation yet, so they define
no capability section.
- Renames in this pass: `laser_cannon_xs` → `laser_cannon_s` (the old 2x2
`laser_cannon_s` became `laser_cannon_m`), `armor_plate` → `armor_plates`,
`manuvering_thrusters` → `maneuvering_thrusters` (typo fix). Test data
under `bin/test/data/config` intentionally still uses the old ids — it is
an independent fixture set.

482
docs/replay_design.md
View File

@@ -1,482 +0,0 @@
# Replay — Design
This document captures the design for the replay record/playback feature. It records the
decisions made during design discussion; it is a complement to `architecture.md`. No
implementation exists yet — this is the agreed design to implement against.
## Goal
Record every play session and allow it to be played back later. Playback is **view-only**
(no interaction) with **manual game-speed selection** (including pause). Playback is launched
via a command-line argument to the executable.
## Approach: deterministic command-replay (re-simulation)
We record **player intent** (commands) plus the inputs needed to reproduce the run, and on
playback we **re-run the real simulation**, injecting the recorded commands at their recorded
ticks. We do **not** record per-tick state snapshots.
This is viable because the simulation is already built for it (see `architecture.md`:
"determinism, replayability ... fall out for free"):
- Fixed 30 Hz tick-based simulation, decoupled from render rate via `TickDriver`.
- Game speed (0/0.5/1/2/4×) and pause are tick-rate multipliers — they change *how many*
ticks run per frame, never the *outcome* of a tick. So speed, pause, camera scroll, and
selection are pure presentation and are **not recorded**.
- A single deterministic RNG stream: `Simulation::m_rng` (one `std::mt19937`) is passed by
reference into `WaveSystem` and `BuildingSystem`, the only two consumers. ECS combat/AI/
movement/scrap systems use no RNG. The `utility::getRandom*` global is not used by the sim.
- Config is immutable after load; a replay is pinned to the config it was recorded with.
A replay run is therefore a pure function of `(seed, config, ordered commands)`.
### What we do NOT do (now)
- No per-tick / keyframe state snapshots.
- No backward seek / scrubbing (would require snapshots).
- No save/load. (See "Future direction".)
- No interactive playback (no taking over a replay mid-run).
## Replay commands
A *replay command* is the resolved, serializable **intent** behind a player action — the
data, not the UI gesture. Example: placing a miner records
`PlaceBuilding{type=Miner, anchor=(3,5), rotation=East}`, not the mouse pixel that produced it.
- Commands are at **intent level, resolved to tile coordinates / domain ids** — independent
of window size, camera scroll, and DPI.
- Command payloads reference **stable, deterministic domain ids** (`BuildingId`, tile
coordinates, choice indices) — never raw `entt::entity` handles. These ids are sim-allocated
deterministically, so a recorded command resolves to the same entity on replay.
- Camera scroll, selection, game speed, and pause are **not** commands.
### Command vocabulary
One command per sim-mutating operation (the complete mutation surface):
- `PlaceBuilding`
- `Demolish`
- `RotateInPlace`
- `SetRecipe`
- `SetShipLayout`
- `SetSplitterFilters` (building-site and belt variants)
- `ClearBeltTiles`
- `ApplySchematicChoice`
- `Reset` / restart — see "Restart is a boundary".
### Command representation
Commands use a **base class + derived classes** (mirroring the existing `Event` hierarchy
idiom, so it is native to this codebase). They are routed through a dedicated command path,
**not** through `EventManager` (see next section).
> **Implementation refinement (Phase 1).** `PlaceBuilding` is **atomic**: it carries the
> optional recipe / ship-layout / splitter-filters to configure the new building in the same
> command. This is forced by the deferred-drain timing — commands apply at a later tick
> boundary, so the caller never sees the new `BuildingId` and therefore cannot issue a
> follow-up `SetRecipe`/`SetShipLayout` against it. The standalone `SetRecipe`,
> `SetShipLayout`, and the two `SetSplitterFilters` commands remain for the dialog-driven
> edits on *existing* buildings (which reference a known id). `Reset` carries the (move-only)
> `GameConfig` via `shared_ptr` and is moved into the sim on apply; a null config means "keep
> current config".
## Command system: reuse the *pattern*, not the EventManager singleton
We reuse the **pattern** of the existing event system (a polymorphic base + small derived
types), but the sim-mutating command path is a **dedicated, ordered queue**, not the
`EventManager` pub/sub bus. Reasons:
1. **Determinism / ordering.** Sim mutations must apply in a strict, tick-pinned, recorded
order. `architecture.md` deliberately keeps the sim free of `EventManager` for exactly this
reason (determinism, tick-order fidelity, headless testability — why `BeamFiredEvent` uses a
plain vector). Routing commands into the sim via the singleton would break that.
2. **Single consumer.** A command has exactly one recipient (the `Simulation`); pub/sub
N-handler fan-out is the wrong shape.
3. **Recording chokepoint.** One place must see every command, stamp its tick, append it to the
file, and apply it. A direct queue gives that; a multi-handler bus does not.
4. **Headless tests.** Tests link only `lib` and build a `Simulation` directly; the command
type and apply path live in `lib` and must work with no UI and no singleton.
### Structure
- **In `lib`:** a `Command` base class + derived command types, plus a `CommandManager`
(ordered queue) and a single `Simulation::apply(command)` chokepoint.
- **UI fan-in still uses `EventManager`:** widgets emit a UI event as today; a single
dispatcher/recorder catches it, builds the `lib` command, and hands it to the
`CommandManager`. This keeps widgets decoupled (consistent with current architecture).
- **Replay** skips the UI half and feeds commands straight into the same `CommandManager` /
`Simulation::apply` chokepoint.
### The completeness invariant (enforced structurally)
**Every** sim mutation must flow through the single `CommandManager → Simulation::apply`
chokepoint. Any path that mutates the sim directly would not be recorded and would silently
desync the replay.
This is enforced **structurally**: the `Simulation` player-action mutators are **private**, so
the only way production code can reach them is `apply(command)`.
> **Implementation decision (Phase 1, revised post-Phase 4).** Structural enforcement was
> initially deferred in favour of convention, because the test suite legitimately drives the
> same mutators directly and relies on their return values (notably the `BuildingId` from
> placement, which `apply()` cannot hand back to a caller). It was later restored once a key
> observation made the change cheap: **the UI's only handle to a mutable subsystem is through
> `Simulation`** — no production code in `ui`/`app`/`balancing` holds a `BuildingSystem`/
> `BeltSystem` directly, and every production `buildings()`/`belts()` call is a const query.
> So:
>
> - `Simulation::tryPlaceBuilding`, `demolish`, and `applySchematicChoice` are **private**.
> - The mutable subsystem accessors are private and renamed `buildingsMutable()` /
> `beltsMutable()`; only `const BuildingSystem& buildings() const` / `belts() const` are
> public (queries). UI query sites bind to the const overload unchanged.
> - `Simulation::apply` still mutates through the private members directly, so the chokepoint
> itself is unaffected.
> - Tests reach the private mutators through `SimulationTestAccess` (src/test, a `friend struct`
> of `Simulation`), so they keep calling the real mutators **and keep getting return values**
> — no id-by-position recovery needed. This header is not on the lib/ui/app include path, so
> only test translation units can use it.
>
> The `BuildingSystem` subsystem mutators (`place`, `setRecipe`, `placeImmediate`,
> `forEachBuilding`, …) stay **public**: `BuildingTest` unit-tests a bare `BuildingSystem` with
> no `Simulation`/command layer, and that surface is unreachable from production anyway (you
> cannot obtain a mutable subsystem without the private accessor). A `[command]` Catch2 suite
> still asserts `apply(...)` produces byte-identical state to the direct mutator path, guarding
> the equivalence the replay relies on. Tests are not gameplay (they never record), so direct
> mutator use there does not affect replay correctness.
Recording happens **at the apply chokepoint**, not at the UI gesture — so only commands that
actually reached the sim are recorded, and they replay through the identical apply path.
UI-side validation (placement validity, affordability) remains a pre-filter that simply does
not produce a command unless the action reaches the sim.
## Command timing: drain once per frame, before the tick batch
- During live play, input pushes commands onto the `CommandManager` queue (not applied
synchronously).
- The queue is drained at **one defined point: once per frame, before stepping the tick
batch.** The whole queue is drained in FIFO order (not one-per-tick), so bursts (e.g. laying
many belts quickly) apply immediately instead of dribbling across ticks, and it matches the
lockstep model wanted later.
- Each drained command is **tagged with the current completed-tick count**, recorded at drain
time (so record-order == apply-order canonically), and applied.
### Build-while-paused is preserved
The drain runs every frame including at 0× (the tick batch is simply empty when paused). So a
player can place buildings while paused and **see the construction sites immediately**. This is
still fully deterministic: replay applies each command at its recorded tick regardless of the
frame cadence that produced it.
On replay, there is no input; the player applies each pre-filled command at its recorded tick
through the same drain path, preserving order.
The Qt single-threaded event loop guarantees input events and the `onFrame` tick-batch never
interleave, so the completed-tick count at drain time is unambiguous. (If the sim is ever moved
to a worker thread, this needs a lock at the sim boundary.)
## Determinism: checksums and verification
We do not verify EnTT iteration order statically. EnTT view iteration is a pure function of the
sequence of spawn/destroy/add/remove operations, so on a fixed binary it contributes zero
run-to-run nondeterminism. Instead we verify **end-to-end determinism** with a state checksum,
and any divergence (EnTT order, float, container ordering, etc.) surfaces loudly.
### What is checksummed (now)
- **RNG state only**, for now. The `mt19937` state is fingerprinted into a 64-bit value.
- The hash can be extended later (entity positions/HP, belt items, building buffers, scalars)
without changing the format.
### Cadence
- **In the replay file:** every **30 ticks**, **and** after **every command** is applied. The
per-command checksum pins any divergence to the action that triggered it; the periodic one
localizes drift to a ~1 s window. On playback the recomputed checksum is compared; a mismatch
reports "desync at tick N".
- **In tests:** the Catch2 **double-run determinism test** hashes **full sim state every tick**
(not just RNG). It runs a scripted command sequence twice from the same seed and asserts
per-tick checksums match. This keeps the file lean while still catching non-RNG determinism
bugs during development.
### Known limitation of the RNG-only file checksum (accepted)
An RNG-only checksum only catches divergences that change **how much randomness is consumed**
(wave composition, recipe rolls, scrap). Float or iteration drift that does **not** alter RNG
draw counts passes the checksum undetected. This is acceptable for same-binary Windows replay
(no float drift expected on an identical binary; the checksum's real job there is catching
determinism *bugs*). When cross-platform replay becomes a goal, the **file** hash must be
expanded to include entity state.
## Cross-platform: Windows-first, portable by construction
The replay file is platform-neutral data; `std::mt19937` is bit-identical across platforms, so
RNG is not a cross-platform problem. The only real cross-platform issue is **floating-point
reproducibility** — the sim does heavy `QVector2D` float math, and a 1-ULP difference (compiler
/ CPU / SIMD / FMA contraction) can flip an in-range comparison and cascade into different ship
behavior (the classic lockstep-RTS problem).
Decision: **Windows-only first**, but make the later swap cheap and bounded by, from day one:
- a **per-period state checksum** in the file (above), and
- a **build/version + config-hash identity tag** in the header.
Then cross-platform later is a contained float-hardening pass (`/fp:strict`, no FMA contraction,
possibly fixed-point positions) guided by the checksums — **not** a redesign of the
command-replay architecture.
Note: even a new Windows *build* of the game can desync old replays for the same float reasons,
so the version tag + "warn on mismatch" is needed regardless of cross-platform ambitions.
## Seed and config
- **Seed:** a **random** seed is generated at the start of each run, **outside** the sim (e.g.
`std::random_device` in `main`/reset), so the `Simulation` stays a pure function of
`(seed, config, commands)`. The seed is written to the replay header.
- **Config:** the header stores a **config hash** (not a full config snapshot). On playback the
current config is hashed and compared; a mismatch warns/refuses. The hash is taken over the
actually-loaded config (so editing config files and restarting yields a new, consistent
replay).
## File format: line-oriented append-friendly text
Non-binary, chosen for readability and crash-safety. Size is a non-issue: the command log is
sparse (only ticks with a player action), so even a multi-hour game is tens of KB in any text
format.
- A small keyed/header section: seed, config hash, build/version, start timestamp.
- One line per command, e.g. `1234 place miner 3 5 E`.
- Periodic checksum lines interleaved, e.g. `# checksum 9000 a1b2c3...`.
Why line-oriented text:
- **Append-friendly** — the recorder stream-appends as the game runs, so a crash does not lose
the replay (a crash is exactly when you would want it). A format that must be rewritten/closed
as a whole is rejected for this reason.
- **No new dependency** — the project has no JSON lib; toml++ is parse-oriented and clunky for a
long event stream (fine for the header, awkward as an array-of-tables of thousands of
entries).
- Greppable, diffable, tiny.
- Aligns with the project's existing text-serialization idiom (`BlueprintSerializer`,
`ShipLayoutBlueprintSerializer`).
## Recording lifecycle
- **Record every run.** A new replay file is created at `Simulation` construction and at each
`reset()`.
- **Restart is a boundary.** Restart (escape menu → restart, which reloads config and resets)
closes the current file and opens a new one with a fresh seed and header. One replay file =
one contiguous run from tick 0 to game-over/quit.
- **Retention: keep everything.** Files live in the existing `data/` directory, named by
timestamp + seed. (No automatic pruning for now.)
## Playback
Launched via a command-line argument, e.g. `DotaFactory.exe --replay <file>`.
`main` for the `--replay` path:
1. Read the header → validate config hash and build/version (warn on mismatch).
2. Construct the `Simulation` from the recorded seed + config.
3. Construct the `CommandManager` in **Replay mode**, **pre-filled** with the whole command list
from the file. (Pre-fill memory is trivial; streaming-read is a later optimization if files
ever get huge — not needed now.)
4. Run the driver in replay mode: each frame, drain commands due at the reached tick (same drain
path as live), step ticks, compare checksums.
### Replay mode rules
Reframe: the schematic-choice modal is **an input source** (the device that produces an
`ApplySchematicChoice` command in live play), exactly like the mouse. Replay's single rule is
"**disable live input sources**", which the modal falls under.
- **`CommandManager` in replay mode:** `addCommand` is a no-op; the queue is pre-filled from the
file. Live input therefore produces nothing.
- **Only two reactions need explicit gating** — the sim-state *polls* in `onFrame` that emit
`SchematicChoicesAvailableEvent` and `GameOverEvent`. In replay these polls do not run, so no
modal opens, no auto-pause occurs, and there is no deadlock against the recorded command.
- **Everything else falls away for free** because it is click-driven, not sim-state-driven: the
recipe dialog (`RecipeSelectionRequestedEvent`), ship-layout dialog
(`LayoutDialogRequestedEvent`), and escape menu are all triggered by player input, which is
disabled — so they never open and need no special handling.
- **Schematic choice still resolves with no UI:** the sim regenerates identical choices
deterministically (same seed + prior commands), and the pre-filled `ApplySchematicChoice`
applies itself at its recorded tick through the normal drain path. The tick-tag invariant
places it correctly relative to when the choices became pending, in both record and replay.
- **Game-over is replaced, not just suppressed:** instead of the live restart/quit dialog,
playback detects the end condition (command stream exhausted / recorded game-over reached) and
stops, showing a passive "replay ended" state.
- **Kept in replay:** the renderer/view and **manual game-speed selection** (including pause /
0× and fast-forward via high speed). Playback only ever moves forward.
## Future direction (informs the design, not built now)
Save/load and (deterministic lockstep) multiplayer are wanted later. The command bus is the
shared foundation; two cheap shaping decisions now keep that path open:
1. **Each command carries a source/player id** (always "player 0" in single-player). Lockstep
multiplayer is just commands from multiple sources merged into one ordered stream.
2. **Commands are applied at a defined tick boundary** (already required for replay). Multiplayer
schedules them a few ticks in the future to hide latency; single-player uses the next drain.
Implications to note:
- Multiplayer makes cross-platform float determinism mandatory and promotes the checksum to
load-bearing desync-detection (rather than a test aid) — reinforcing doing the checksum now.
- **Save/load** is the one feature that needs a *different* mechanism: either "replay to current
tick" on load (reuses 100% of replay machinery; load time grows with game length, though
fast-forward usually replays hours in seconds), or a full **state-snapshot serializer**
(EnTT registry + belts + buildings + scalars). The snapshot serializer is also what
backward-seek/scrubbing would need. Building the command bus now does not block adding it
later; it is explicitly out of scope here.
## Summary of decisions
- Approach: **A — deterministic command-replay** (re-simulation), no snapshots.
- Scope: **view-only** playback + **manual speed selection**; launched via CLI argument.
- Commands: **base class + derived types**, routed through a dedicated `CommandManager` queue
and a single `Simulation::apply` chokepoint; sim mutators made non-public to **enforce** the
chokepoint. UI fan-in still uses `EventManager`.
- Timing: queue **drained once per frame before the tick batch**, whole queue FIFO, each command
tick-tagged; **build-while-paused preserved**.
- Determinism: **RNG-state checksum** in the file every **30 ticks + after each command**;
**full-state per-tick hashing** in the Catch2 double-run test. Known RNG-only blind spot
accepted for now.
- Platform: **Windows-first**; file format + version/config-hash make a later cross-platform
pass contained.
- Seed: **random**, generated outside the sim, written to the header.
- Config: **config hash** in the header, validated on playback.
- File: **line-oriented append-friendly text**, kept in `data/`, **one file per run**,
**retain everything**.
- Restart: **a boundary** — new file, new seed.
- Replay mode: `CommandManager` `addCommand` is a no-op + pre-filled; gate the two sim-state
polls (schematic choices, game-over); passive "replay ended" instead of the game-over dialog;
keep view + speed.
## Implementation plan
Ordered to de-risk: prove determinism first, then build the command path, then recording, then
playback. Each phase is independently testable and leaves the game in a working state. Phases
0 → 1 → 2 → 3 are strictly sequential; Phase 4 tests can start as soon as their subject exists.
### Phase 0 — Determinism foundation & verification (no replay yet)
The whole feature rests on a deterministic sim, so prove that before building on it.
- Add a `mt19937` state **fingerprint** (fold its serialized state into a 64-bit value).
- Add a **full-state checksum** path (positions, HP, velocities, belt items, building buffers,
scalars), used by tests; each subsystem contributes via its own `appendChecksum(Hasher&)` so
no state knowledge is duplicated.
- Add a Catch2 **double-run determinism test**: run a scripted sequence twice from the same
seed, assert per-tick **full-state** checksums match.
- **Files:** new `lib/sim` checksum helper; small additions to `Simulation`, `BeltSystem`,
`BuildingSystem`, ECS state; new test.
- **Exit criteria:** the double-run test passes. If it fails, fix the nondeterminism here before
proceeding.
### Phase 1 — Command model + chokepoint (no recording yet) — DONE
Reshape mutations to flow through one path; behaviour unchanged.
- Defined `Command` base + derived types (`PlaceBuilding`, `Demolish`, `RotateInPlace`,
`SetRecipe`, `SetShipLayout`, `SetSiteSplitterFilters`, `SetSplitterFilters`,
`ClearBeltTiles`, `ApplySchematicChoice`, `Reset`) in `lib`, each with a `playerId` (always 0
now). `PlaceBuilding` is atomic (carries optional config — see the refinement note above).
- Added `CommandManager` (FIFO queue, `enqueue`/`drain`) in `lib`, holding a `Simulation&`.
- Added `Simulation::apply(const Command&)` dispatching by `CommandKind` to the underlying
mutators — the single chokepoint. The `Simulation` player-action mutators are **private**
(compile-time enforced; tests reach them via the `SimulationTestAccess` friend) — see the
decision note above.
- Wired the drain: `GameWorldView::onFrame` calls `CommandManager::drain()` once per frame,
before the tick batch (runs even at 0× → build-while-paused preserved). A drained `Reset`
triggers the view reset.
- Refactored every UI mutation site: `GameWorldView` owns the `CommandManager` and enqueues
directly; `MainWindow` and `SelectedBuildingPanel` emit `CommandRequestedEvent` (carrying a
`shared_ptr<const Command>`) which `GameWorldView` subscribes to and enqueues.
- **Files:** new `lib/sim/Command.h`, `CommandManager.{h,cpp}`; `CommandRequestedEvent.h`;
`Simulation.{h,cpp}` (`apply`); `GameWorldView.{h,cpp}`, `MainWindow.cpp`,
`SelectedBuildingPanel.cpp`; new `CommandTest.cpp`.
- **Exit criteria:** game plays identically (including build-while-paused); determinism test
still passes; `[command]` equivalence tests pass; no production call site can mutate the sim
directly (compile-enforced: the `Simulation` mutators are private, tests excepted via
`SimulationTestAccess`).
### Phase 2 — Recording — DONE
- `ReplayRecorder` (lib) writes the **line-oriented append file**: header (`version`, `build`,
`seed`, `config_hash`, `timestamp`) then `---`, then one tick-tagged line per command
interleaved with `# checksum <tick> <hex>` lines. Each line is flushed, so a crash mid-run
leaves a valid partial file. `CommandSerializer` produces the per-command text (length-prefixed
variable parts; `ShipLayoutConfig`/filters serialized inline). The build tag is
`__DATE__ " " __TIME__`; the config hash is a 64-bit FNV over the `*.toml` files in the config
dir (re-hashed on playback to detect mismatch).
- **Random seed** generated in `main` (and on each restart in `MainWindow`) via
`std::random_device`; `Simulation` retains it (`getSeed()`) for the header.
- **Recorder hooked at the chokepoint:** `CommandManager` owns an optional `ReplayRecorder`;
`drain()` records each applied command (tick-tagged) + a post-apply RNG checksum, and
`recordTickCheckpoint()` (called per tick from the `onFrame` loop) writes a checksum every 30
ticks. A drained `Reset` rolls the recorder to a new file (restart = boundary).
- **Lifecycle:** `GameWorldView` attaches the recorder at construction (opens the first file with
the initial seed + a tick-0 checksum); files live in `<data>/replays`, named
`<timestamp>_<seed>.replay`; everything is retained.
- **Files:** new `lib/sim/ReplayRecorder.{h,cpp}`, `CommandSerializer.{h,cpp}`; `Simulation`
(`getSeed`); `CommandManager` (recorder + tick checkpoint); `main.cpp` (seed);
`MainWindow.cpp` / `GameWorldView.{h,cpp}` (wiring); new `ReplayRecorderTest.cpp`.
- **Exit criteria met:** recorder + serializer + drain-integration tests pass; the format is
well-formed and flushed per line. (Live GUI recording is wired but not auto-tested here.)
### Phase 3 — Playback — DONE
- `ReplayReader` (lib) parses the file into `{ header, entries }`, where each entry is a command
(with its tick) or a checksum (with its tick), kept in **file order**. `CommandSerializer`
gained the inverse `parseCommand` (round-tripping every verb).
- `--replay <file>` CLI path in `main`: reads the file, **warns** on version / config-hash
mismatch (proceeds anyway), constructs the `Simulation` from the header seed, and threads the
parsed replay through `MainWindow` to `GameWorldView`.
- `ReplayPlayer` (lib) is the playback driver. Rather than reproduce frame batching, it applies
each command at its **exact recorded tick** and verifies checksums **in file order**:
`start()` processes the tick-0 entries, then after every `sim.tick()` `advanceTo(tick)`
consumes that tick's entries (periodic checksum first, then command + its checksum — the order
the file already has). This makes playback independent of replay-time speed/pause.
- `GameWorldView` runs the player in `onFrame` when in replay mode (manual speed/pause kept,
forward-only); `CommandManager` is put in **replay mode** so live input is a no-op. The two
sim-state polls (schematic-choices, game-over) are **gated off**; dialog/escape paths are
input-driven and fall away. A **"REPLAY"** tag plus a passive **"Replay ended"** /
**"Desync at tick N"** overlay replaces the restart dialog.
- **Files:** new `lib/sim/ReplayReader.{h,cpp}`, `ReplayPlayer.{h,cpp}`; `CommandSerializer`
(`parseCommand`); `ReplayRecorder` (shared `computeReplayConfigHash`); `CommandManager`
(replay mode); `main.cpp`; `MainWindow.{h,cpp}`; `GameWorldView.{h,cpp}`; new
`ReplayPlaybackTest.cpp`.
- **Exit criteria met:** the headless `ReplayPlaybackTest` records a scripted run, reads it back,
replays it, and asserts **no desync** and a **byte-identical final state checksum** — including
the periodic-checksum-then-command ordering at a shared tick. (Live GUI playback is wired but
not auto-tested here.)
### Phase 4 — Closing tests & polish — DONE
- **Round-trip:** every command verb serializes → parses → re-serializes identically;
malformed input is rejected (`parseCommand` returns nullptr).
- **Replay-equivalence (headless):** a short scripted run and a **long ~2400-tick run through
waves/combat** each record → read → replay with **no desync** and a **byte-identical final
state checksum**.
- **Desync detection:** corrupting one recorded checksum makes the player report the exact
desync tick.
- **Reset boundary:** a `Reset` drained through `CommandManager` rolls the recorder to a new
file (named by the new seed).
- **Polish:** the end-of-replay / desync overlay dims the world behind the message for
readability; config/version mismatch is warned to the log on launch (its visible consequence,
a desync, is already surfaced by the overlay).
### Status
Record + playback is functionally complete and covered by headless tests. Still deferred (per
this design): snapshots, save/load, backward-seek, cross-platform float hardening, expanding the
file checksum beyond RNG. Known minor rough edge: in replay mode the recipe/layout dialogs and
escape→restart can still open but do nothing (their commands hit the no-op enqueue); fully
disabling that input UI is polish, not correctness.
### Notes
- Phase 1 is the largest (the mutation-site refactor); Phase 0 is the riskiest (it may surface
latent nondeterminism that must be fixed first).
- Still deferred (per this design): snapshots, save/load, backward-seek, cross-platform float
hardening, expanding the file checksum beyond RNG.

287
docs/requirements.md
View File

@@ -4,13 +4,13 @@
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, belt speed, starting building blocks, departure interval, ship orbit factor, rally orbit radius, scrap-per-threat conversion, combat target-selection parameters (target score formula, overclaim penalty formula, target hysteresis), artifact chance formula, artifact win count, view pan speeds (slow and fast horizontal pan speed and pan ramp band width), and an optional building blocks tooltip string (shown as the header bar's building blocks stock hover tooltip, REQ-UI-BLOCKS-TOOLTIP; omitted when unset).
- **buildings.toml** — building block cost and construction time per building type, plus an optional tooltip description string per building type (shown as the build button's hover tooltip, REQ-UI-BUILD-TOOLTIP; omitted when unset).
- **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). An assembler recipe schematic entry may also define an optional `unlock_requires` list of prerequisite schematic ids (REQ-LOCK-PREREQ).
- **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 plain values, required build materials, 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), an optional `unlock_requires` prerequisite list (REQ-LOCK-PREREQ), a layout grid defining the ship's module slots, 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, production time, fill color, glyph, an optional tooltip description string (shown as the module selection button's hover tooltip, REQ-MOD-UI-MODULE-TOOLTIP; omitted when unset), 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), an optional `unlock_requires` prerequisite list (REQ-LOCK-PREREQ), 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).
- **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.
- **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; a distinct beam color per tool type (weapon, repair, salvage) and beam width; overlay and toast colors. Loaded by the UI at startup; the simulation does not read it.
- **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.
@@ -68,7 +68,7 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
## 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). Items emerging from a building's output port are rendered by these same rules on that port's output belt (REQ-MAT-OUTPUT-EMERGE).
- 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`.
@@ -90,34 +90,20 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
- 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.
## Win Condition
- REQ-WIN-ARTIFACT-COUNT: The player has an artifact count, starting at 0 at game start and resetting to 0 on Restart (REQ-CFG-RELOAD). When the player selects an artifact option in the schematic choice dialog (REQ-DEF-SCHEMATIC-DROP), the artifact count increments by 1. When the artifact count reaches `world.toml [world].artifact_win_count`, the player wins and the win screen is shown (REQ-WIN-SCREEN).
- REQ-WIN-SCREEN: When the player wins (REQ-WIN-ARTIFACT-COUNT), the simulation stops and a win screen is shown. The win screen functions identically to the game-over screen (REQ-HQ-GAME-OVER) — it displays the final survival time and offers "Restart" and "Quit" buttons — but with the caption "Won!" instead of the game-over caption.
## 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. The ghost is drawn semi-transparently in the building type's own visuals — its `fill` and `outline` colors and `glyph` from `visuals.toml` — so that different building types are visually distinguishable in builder mode rather than all looking alike. When the current cursor position is invalid, the ghost instead uses the distinct "invalid" color (REQ-BLD-PLACE-VALID), which overrides the per-building coloring.
- REQ-BLD-ROTATE: While in builder mode, pressing Shift+R rotates the ghost 90° clockwise and R rotates it 90° counter-clockwise. Rotation affects the direction of the output port.
- 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 — overriding its per-building coloring (REQ-BLD-GHOST) — when the current cursor position fails any of these conditions.
- 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.
- REQ-BLD-DEMOLISH-CLICK: While in demolish mode (REQ-UI-HOTKEYS, REQ-UI-DEMOLISH-BUTTON), left-clicking a placed factory building or construction site in the game world demolishes it, following the refund rules of REQ-BLD-DEMOLISH — the partial refund for built buildings and the full refund for still-queued construction sites. Clicking a building that cannot be demolished (the HQ or a player defence station, per REQ-BLD-DEMOLISH), or clicking empty world space, has no effect. Demolish mode stays active after a demolition so the player can demolish further buildings without re-entering the mode; it is exited via the Q toggle (REQ-UI-HOTKEYS) or the Demolish button (REQ-UI-DEMOLISH-BUTTON).
- REQ-BLD-DEMOLISH-BOX: While in demolish mode (REQ-UI-HOTKEYS, REQ-UI-DEMOLISH-BUTTON), the player can click and drag a selection box in the game world. A selection rectangle is drawn while dragging, using the same box-drag gesture and coverage semantics as the multi-select box (REQ-UI-MULTI-SELECT). On mouse up, every placed factory building and construction site covered by the box is demolished, each following the refund rules of REQ-BLD-DEMOLISH — the partial refund for built buildings and the full refund for still-queued construction sites. Buildings that cannot be demolished (the HQ and player defence stations, per REQ-BLD-DEMOLISH) are excluded from the box demolition; ships and defence stations are never affected.
- REQ-BLD-SITE-CONFIG: A construction site — a building that has been placed but is still queued or under construction (REQ-BLD-QUEUE) — can be selected and configured exactly like the equivalent operational building, before it finishes building. Whatever configuration the building type supports is available on the site: the recipe for a Miner or Assembler (REQ-UI-SELECT-BUTTON), the produced-ship schematic and its module layout for a Shipyard (REQ-UI-SELECT-BUTTON, REQ-MOD-UI-PREVIEW, REQ-MOD-UI-DIALOG), and the output filters for a Splitter (REQ-BLD-SPLITTER) — all set through the same Selected Building Panel controls (REQ-UI-CONFIG-INLINE). Only currently unlocked recipes and schematics are offered, exactly as for operational buildings (REQ-LOCK-UI-RECIPE, REQ-LOCK-UI-SCHEMATIC, REQ-LOCK-UI-SPLITTER). The configuration is stored on the construction site and carries over unchanged when construction completes, so the building becomes operational already configured. A construction site has no input/output buffers and runs no production cycle, so the buffer and production-progress portions of the panel (REQ-UI-SINGLE-SELECTION, REQ-UI-PRODUCTION-PROGRESS) are not shown for it; only its construction progress (REQ-UI-CONSTRUCTION-PROGRESS) and its configuration controls appear. (Blueprint placement already applies a stored recipe or schematic to a construction site on placement per REQ-UI-BLUEPRINT-PLACE; this requirement additionally lets the player set or change that configuration directly on an existing site.)
- REQ-BLD-COPY-CONFIG: **Copy building settings (hold Shift).** While the Shift key is held, the player can copy one building's settings onto other buildings of the same type, so several identical machines can be set up without opening each one's panel. This gesture is available only in the default selection mode; while a builder, blueprint placement, or demolish mode is active it is disabled, so it never clashes with placement or demolition clicks.
- **Shift + right-click** a building copies its current settings into a temporary cache, along with the building's type. The settings copied are whatever that building type supports: the selected recipe (Miner, Assembler), the selected schematic together with its module layout (Shipyard), or the two output filters (Splitter, REQ-BLD-SPLITTER). Copying succeeds only when there is something to copy — a Miner or Assembler with a recipe selected, a Shipyard with a schematic selected, or any Splitter (whose output filters, even when empty/accept-all, always constitute valid settings). Shift + right-clicking a configurable building with nothing yet selected, a building type that has no settings at all (Smelter, Reprocessing Plant, Salvage Bay, belt/tunnel tiles, the HQ), or empty world space, has no effect and leaves any existing cache unchanged.
- **Shift + left-click** a building of the **same type** as the cached one applies the cached settings to it, exactly as if the player had made that selection through the selected building panel — with the same effects as a normal selection change (buffer clearing per REQ-MAT-INPUT-BUFFER and REQ-MAT-OUTPUT-BUFFER, and, for a Shipyard, in-progress cycle cancellation per REQ-BLD-SHIPYARD). This can be repeated on any number of same-type buildings while Shift stays held. Shift + left-clicking a building of a different type than the cached one, any building while the cache is empty, or empty world space, has no effect.
- Both operational buildings and construction sites take part as source and target (REQ-BLD-SITE-CONFIG); settings applied to a construction site carry over unchanged when it finishes building.
- **Releasing Shift clears the temporary cache.** It is never persisted and does not survive Shift being released; the next copy starts fresh.
- Because the cached settings were already valid on a same-type source building, they remain valid and available on the target (a selected recipe/schematic stays unlocked per REQ-LOCK-UI-RECIPE and REQ-LOCK-UI-SCHEMATIC; splitter filter item types stay unlocked per REQ-LOCK-UI-SPLITTER).
## Building Types
@@ -125,17 +111,17 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
- 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 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. It has an output buffer whose holding capacity is defined by the `output_buffer_capacity` field of the `salvage_bay` entry in `buildings.toml` (rather than by a production cycle, since the Salvage Bay has no recipe). A ship at the bay hands over one unit of scrap per tick while the buffer has free space; a full buffer blocks further drop-off until space frees up (consistent with the buffer-full semantics of REQ-MAT-OUTPUT-BUFFER). Held scrap is pushed 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). A belt accepts items only through a non-output edge (REQ-MAT-ACCEPT-DIR).
- REQ-BLD-SPLITTER: **Splitter** (1×1): Distributes incoming items between two output directions. Incoming items are accepted only through the splitter's non-output edges (REQ-MAT-ACCEPT-DIR). 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:
- 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 R/Shift+R. Items arriving from an adjacent belt tile on a non-output edge (i.e. not the mouth edge in the entry's facing direction — see REQ-MAT-ACCEPT-DIR) 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 R/Shift+R. 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-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.
@@ -146,27 +132,9 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
## Material Transport & Buffers
- REQ-MAT-BELT-ONLY: Materials are transported exclusively via belts, splitters, and tunnels, with one exception: two directly adjacent buildings whose output and input ports meet transfer items straight between them without an intervening transport tile (REQ-MAT-DIRECT-COUPLE).
- 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. An accepted item does not enter the building instantly; it is removed from the belt and travels inward across the input port's footprint cell on that port's own input belt before being added to the buffer (REQ-MAT-INPUT-INTAKE).
- REQ-MAT-INPUT-INTAKE: Accepted input items travel into a building as an animation rather than vanishing off the belt instantly — the input-side mirror of REQ-MAT-OUTPUT-EMERGE. Each input port has its own **input belt** — a virtual belt tile occupying the input port's footprint cell (the body cell the feeding belt points into), oriented in the port's inward flow direction, with progress 0.0 at the outer edge adjacent to the feeding belt and 0.5 at the tile centre. It reuses the belt subsystem: movement at belt speed (REQ-GW-BELT-SPEED), item rendering and spacing (REQ-GW-TILE-SIZE), and capacity/packing (REQ-GW-BELT-CAPACITY), but restricted to the 0.0→0.5 half of the tile. This applies to every building that pulls items from adjacent belts into an input buffer (Smelter, Assembler, Reprocessing Plant, Shipyard); a building may run several input belts at once when belts feed it from more than one side. The HQ is included with the one difference noted below.
- **Acceptance & reservation.** The acceptance test of REQ-MAT-INPUT-PORTS is unchanged — an item is accepted only if it is a required input whose per-material input buffer has space — except that "has space" now counts both the items already buffered **and** the items of that material currently travelling on the building's input belts (reserved but not yet arrived), so the total (buffered + in-transit) never exceeds that material's buffer cap (REQ-MAT-INPUT-BUFFER). An item that fails this test is not placed on an input belt and stays on the feeding belt exactly as before, so items that are not required inputs never enter the building.
- **Feeding.** An accepted item is removed from the feeding belt on the same tick it would have been taken without this animation, and placed on the input belt at progress 0.0, reserving a slot in its per-material buffer. (An input belt may also be fed directly by an adjacent producer's output belt rather than by a real belt — see REQ-MAT-DIRECT-COUPLE — with the same reservation and entry rules.) A new item is placed only when the input belt's entry slot at progress 0.0 is free (per REQ-GW-BELT-CAPACITY spacing — no in-transit item within a quarter tile of 0.0). The 0.0→0.5 span holds at most three in-transit items (progress 0.0, 0.25, 0.5); the reservation limit above may permit fewer.
- **Travel & arrival.** An in-transit item advances from progress 0.0 to 0.5 at belt speed. On reaching progress 0.5 it leaves the input belt and is added to its per-material input buffer, turning its reservation into buffered stock; only then does it count toward starting a production cycle (REQ-MAT-CYCLE). Because the slot was reserved on entry, arrival always succeeds — there is no deadlock.
- **Reservation may delay production.** A reserved item occupies buffer capacity for its whole 0.0→0.5 travel without yet being consumable, so an input-starved building may briefly wait for an in-transit item to arrive before it can start a cycle. This is accepted.
- **Clearing.** Clearing the input buffers on a recipe or schematic change (REQ-MAT-INPUT-BUFFER) also discards any items currently travelling on the input belts and releases their reservations.
- **HQ.** The HQ has no input buffer (REQ-HQ-BELT-INPUT); a building block accepted at an HQ input port travels its input belt the same way but reserves nothing, and is added to the global building blocks stock (REQ-MAT-GLOBAL-STOCK) on reaching progress 0.5.
- **Intake rendering (no pop-out).** Mirror of the emergence rendering in REQ-MAT-OUTPUT-EMERGE: the building is rendered over the input belt, so an in-transit item is occluded while inside the footprint and is only visible as it crosses the outer edge — appearing to sink into the port. The portion inside the footprint is hidden, and the item disappears at the tile centre (progress 0.5) as it enters the buffer.
- 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 do not appear on the outgoing belt instantly; each item leaves the building by first emerging across the output port tile on that port's own output belt and then transferring onto the adjacent real belt tile (REQ-MAT-OUTPUT-EMERGE). The adjacent belt's direction is otherwise unconstrained (it may flow away from the building or perpendicular to it), except that a belt oriented with its own output edge facing back into the building refuses the transfer and the item stays stuck at the port (REQ-MAT-ACCEPT-DIR, REQ-MAT-OUTPUT-EMERGE).
- REQ-MAT-OUTPUT-EMERGE: Items emerge from a building output port as an animation rather than popping directly onto the outgoing belt. Each output port has its own **output belt** — a virtual belt tile occupying the output port tile, oriented in the port's facing direction, with progress 0.0 at the tile's inner edge and 1.0 at the outer (port) edge adjacent to the next real belt tile. It reuses the belt subsystem: movement at belt speed (REQ-GW-BELT-SPEED), item rendering and spacing (REQ-GW-TILE-SIZE), and capacity/packing (REQ-GW-BELT-CAPACITY), but restricted to the 0.5→1.0 half of the tile. This applies to every building that outputs items onto belts (Miner, Smelter, Assembler, Reprocessing Plant, Salvage Bay); it does not apply to the Shipyard, which spawns a ship rather than a belt item (REQ-SHP-SPAWN-PLAYER).
- **Feeding.** While the output buffer (REQ-MAT-OUTPUT-BUFFER) holds an item that has not yet begun emerging and the output belt's entry slot at progress 0.5 is free (per REQ-GW-BELT-CAPACITY spacing — no emerging item within a quarter tile of progress 0.5), the next buffered item is placed on the output belt at progress 0.5. Because only the 0.5→1.0 span is used, the output belt holds at most three emerging items (progress 0.5, 0.75, 1.0); once that span is full the building places no further items on it even if the output buffer still holds more.
- **Cosmetic hold.** An emerging item still counts as residing in the output buffer (REQ-MAT-GLOBAL-STOCK) for the whole animation; it only leaves the building when it transfers onto a real belt tile at progress 1.0. The output belt therefore adds no inventory capacity beyond the output buffer, and clearing the output buffer on a recipe or schematic change (REQ-MAT-OUTPUT-BUFFER) also removes any items currently emerging.
- **Travel & handoff.** An emerging item advances from progress 0.5 to 1.0 at belt speed. At progress 1.0 it attempts to transfer onto the adjacent real belt tile using the normal belt hand-off and accept-direction rules (REQ-MAT-OUTPUT-PORT, REQ-MAT-ACCEPT-DIR): the transfer succeeds only if a transport tile exists there, is not oriented with its output edge facing back into the building, and has free space. On success the item leaves the output buffer and becomes an ordinary item on that belt tile. If instead the output port tile is a directly adjacent building's input edge, the item transfers straight into that building (REQ-MAT-DIRECT-COUPLE).
- **Stuck items.** If there is no next real belt tile and no directly-coupled building (REQ-MAT-DIRECT-COUPLE), or the transfer is refused or blocked, the emerging item stops at progress 1.0 and is rendered there (still counted in the output buffer). Following items pile up behind it at progress 0.75 and 0.5 per the packing above, and once the 0.5→1.0 span is full no further items emerge until the front item transfers.
- **Emergence rendering (no pop-in).** An emerging item must not simply appear at progress 0.5. The output port tile's building is rendered over the output belt, so an emerging item is occluded while inside the footprint and is revealed progressively as it slides past the port edge — appearing to physically emerge from the building. The portion of the item still within the output port tile is hidden; the portion past the outer edge is drawn.
- REQ-MAT-DIRECT-COUPLE: **Direct port coupling.** Two directly adjacent buildings whose ports meet transfer items between them with no intervening transport tile. A direct coupling exists at a shared edge where a producer building's output port tile (the tile it pushes toward, REQ-MAT-OUTPUT-PORT) is a body cell of a consumer building, and the producer's output direction carries the item across that edge into the consumer through one of the consumer's input edges (any perimeter edge other than the consumer's own output port, per REQ-MAT-INPUT-PORTS). Over a direct coupling the two virtual belts chain end to end: an item that reaches progress 1.0 on the producer's output belt at the shared edge (REQ-MAT-OUTPUT-EMERGE) is handed, instead of onto a real belt tile, directly onto the consumer's input belt at progress 0.0 (REQ-MAT-INPUT-INTAKE) and continues inward to the consumer's buffer — so the item appears to slide continuously across the shared edge from one building into the next.
- **Acceptance.** The hand-off obeys the consumer's normal input rules (REQ-MAT-INPUT-PORTS, REQ-MAT-INPUT-INTAKE): it succeeds only if the item is a required input of the consumer whose per-material buffer has space (reservation-aware — buffered + in-transit below the cap) and the consumer's input belt entry at progress 0.0 is free. On success the item leaves the producer's output buffer and reserves a slot in the consumer's input buffer, exactly as a belt-fed intake would. If the consumer does not accept the item — it is not one of its inputs, or the buffer is full, or the input-belt entry is occupied — the item stays stuck at the producer's output port at progress 1.0, exactly as when a downstream belt is blocked (REQ-MAT-OUTPUT-EMERGE stuck items).
- **Scope.** Direct coupling is the only case in which materials move between buildings without a belt, splitter, or tunnel (REQ-MAT-BELT-ONLY); it bridges only two buildings that are directly adjacent with meeting output/input ports. Transport tiles feeding a building (belt, splitter, or tunnel exit) continue to work through the normal pull, and a producer still hands off to a transport tile placed in the gap as before; a single such tile between two buildings is unaffected by this requirement.
- REQ-MAT-ACCEPT-DIR: A transport tile (belt, splitter, tunnel entry, or tunnel exit) accepts an incoming item only through a non-output edge; an item that would enter through one of the tile's output edges is refused. For a belt or a tunnel entry/exit the sole output edge is the one in its facing direction; for a splitter either of its two output directions is an output edge. This applies both to items pushed from an adjacent transport tile and to items deposited by a building's output port (REQ-MAT-OUTPUT-PORT).
- 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.
@@ -175,43 +143,32 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
## 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 derived from the ship's threat cost (REQ-MOD-THREAT) for its as-built layout, multiplied by `world.toml [world].scrap_per_threat` (default 0.01) and rounded to the nearest integer (at least 1 for any ship whose threat cost is greater than 0); for stations it is defined as `stations.toml [player_station].scrap_drop_formula` and `[enemy_station].scrap_drop_formula`. A scrap drop carries an amount; salvage modules collect it one scrap per cycle (REQ-SHP-SALVAGE), and the drop is removed from the world once its remaining amount reaches zero or `world.toml [world].scrap_despawn_seconds` seconds have elapsed since it was dropped, whichever comes first.
- 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 plain values in `ships.toml`: HP (`[ship.health].hp`), max linear speed (`[ship.movement].speed`), sensor range (`[ship.sensors].range`), main acceleration (`[ship.movement].main_acceleration`, tiles/s²), maneuvering acceleration (`[ship.movement].maneuvering_acceleration`, tiles/s²), angular acceleration (`[ship.movement].angular_acceleration`, rad/s²), max rotation speed (`[ship.movement].max_rotation_speed`, 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-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`) is applied along the ship's current facing direction only. The maneuvering acceleration (`maneuvering_acceleration`) can be applied in any direction independently of the facing direction, enabling lateral or braking movement without rotating. The angular acceleration (`angular_acceleration`) controls how quickly the ship rotates. Linear speed is capped at the ship's `speed` value; rotation rate is capped at the ship's `max_rotation_speed` 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-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-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 weapon fire event (REQ-SHP-FIRING), repair-tool activation (REQ-SHP-REPAIR), and salvage activation (REQ-SHP-SALVAGE) produces a visual beam drawn from the acting ship's position to the target for 0.3 seconds; repair and salvage beams have the same duration as weapon beams. The beam is rendered in the tool type's beam color from `visuals.toml` (a distinct color for weapon, repair, and salvage beams). 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; for a scrap pile: half its rendered size). The offset is chosen once per activation 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 its effect over its lifetime). Beams follow the acting ship 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 acting ship 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.
- REQ-SHP-RALLY: After spawning, 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 begins collecting from it, one scrap per cycle (see below). Once the ship's cargo pool 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.
- 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. 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 loiter at the **rally point** — the midpoint between the two player defence stations (center of their Y-span, at the player defence stations' X position). While at the rally point, ships still engage any enemy that enters sensor range. 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, move to it; 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; after delivery, resume patrol. If an enemy ship enters sensor range while not currently targeting or carrying scrap, turn back (move toward the asteroid) until the enemy is no longer in sensor range, then resume patrol. Ships with salvage modules are vulnerable to enemy ships while operating.
All salvage modules on a ship deposit into a single shared **cargo pool** whose size is the ship's cargo capacity stat (REQ-MOD-CARGO-CAPACITY). Each salvage module instance still runs its own collection cycle independently, with its own collection range (`collection_range`) and collection rate (`collection_rate`, in collection cycles per second). A module starts a collection cycle when it is off cooldown, the shared cargo pool has free space, and a scrap pile is within its `collection_range`. Free space is measured against the pool's current contents **plus the collection cycles already in flight toward the pool** (scrap claimed by cycles whose effect delay has not yet elapsed); each in-flight cycle is registered against the ship so that concurrent modules on the same ship never start more cycles than the remaining capacity can hold. Starting a cycle emits a collection beam toward that scrap pile (REQ-SHP-FIRING-BEAM) and begins a 0.15-second effect delay (half the beam duration); the module's cooldown of `1 / collection_rate` seconds begins at cycle start, not at effect application. When the delay expires, exactly 1 scrap is removed from the targeted pile and added to the ship's cargo pool — unless the pile has already been fully depleted or despawned, or the pool is now full, in which case the collection is silently dropped. A scrap pile worth more than 1 (REQ-RES-SCRAP-DROP) is depleted one scrap per cycle and persists, with its remaining amount decremented, until it is fully collected or despawns. A ship with multiple salvage modules can therefore run multiple collection cycles concurrently (one per ready module), and instances of different module types may have different ranges and rates. The ship navigates based on the maximum collection range across all installed salvage modules.
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.
- 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, move to it and repair. If an enemy ship enters sensor range while not currently repairing, turn back (move toward the asteroid) until the enemy is no longer in sensor range, then resume patrol. The player can configure the target priority per shipyard:
- Defence stations first / ships first / nearest target.
Salvage collection cycles and delivery are processed 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) — when no more urgent behavior applies, hold with the fleet (REQ-SHP-STANDBY) rather than charging the enemy, so damaged allies stay within 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 — except that it holds its ground and keeps repairing while a damaged friendly remains within sensor range (REQ-SHP-RETREAT), retreating only once there is nothing left to repair — then resumes patrol.
Each repair module instance operates independently: it has its own repair rate (`repair_rate`, in repair cycles per second), per-cycle heal amount (`repair_amount_hp`), and repair range (`repair_range`). A module starts a repair cycle when it is off cooldown and a valid repair target is in range. To choose the target, the module first considers 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`. If no valid target is found within range, the module idles and starts no cycle. On starting a cycle, the module emits a repair beam toward the chosen target (REQ-SHP-FIRING-BEAM) and begins a 0.15-second effect delay (half the beam duration); the module's cooldown of `1 / repair_rate` seconds begins at cycle start, not at effect application. When the delay expires, `repair_amount_hp` HP is restored to the targeted entity, clamped to its maximum HP — unless that entity is no longer damaged or has been destroyed, in which case the heal is silently dropped. A ship with multiple repair modules can therefore run multiple repair cycles concurrently, healing different targets. Navigation is driven solely by the behavior-level target; individual module fallback targets do not affect which direction the ship moves. Repair cycles are processed regardless of which behavior the ship is currently executing.
- REQ-SHP-STANDBY: **Ships with at least one repair module hold with their fleet when idle**, whether or not they also carry weapon modules. Standby is a low-priority fallback — above the baseline forward advance (REQ-SHP-COMBAT/REQ-SHP-ENEMY-AI advance) but below rally (REQ-SHP-RALLY), so it only wins when no attack, repair, salvage, rally, or retreat behavior applies. A standing-by ship navigates toward the centroid of its other same-faction ships, falling back to the centroid of its own defence stations, and holding position when it has no allies. This keeps repair ships among the allies they exist to heal instead of advancing alone into the enemy. Armed repair ships therefore still rally and depart on the normal schedule (REQ-SHP-RALLY); standby only governs them once rally no longer applies.
- 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 — with one exception: a weaponless ship that has at least one repair module does **not** retreat under condition (b) while a damaged friendly (player ship or player defence station, excluding itself) is within its sensor range, so it can keep repairing under fire; it retreats only when no such repair target remains in range. Condition (a) still forces a low-HP repair ship to retreat regardless of available repair targets. 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.
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.
- REQ-SHP-ENEMY-AI: **Enemy ships** — engage the closest valid target (player defence station, HQ, or player ship) within their sensor range. If no target is in sensor range, they move toward the asteroid (leftward in world coordinates).
- 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
@@ -222,23 +179,23 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
- `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.
- `unlock_requires` — optional list of prerequisite schematic ids that must already be unlocked before this module's schematic can drop (REQ-LOCK-PREREQ). Defaults to empty.
- `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 values. A module with base stat values is a capability module — each placed instance grants the ship an independent weapon, salvage bay, or repair tool with its own state (cooldown, target). A ship may have multiple capability module instances of the same or different types. Base stat values per capability type:
- **Weapon** (`[module.weapon]`): `damage`, `attack_range`, `attack_rate`.
- **Salvage** (`[module.salvage]`): `collection_range` (tiles), `cargo_capacity` (integer scrap units; contributes to the ship's cargo capacity stat per REQ-MOD-CARGO-CAPACITY), `collection_rate` (collection cycles per second; each cycle collects 1 scrap).
- **Repair** (`[module.repair]`): `repair_rate` (repair cycles per second), `repair_amount_hp` (HP restored per repair cycle), `repair_range` (tiles).
- Zero or more **passive stat modifiers** (`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.
- 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 R rotates the module ghost 90° counter-clockwise and Shift+R rotates it 90° clockwise. Rotation transforms the surface mask grid identically to building rotation (REQ-BLD-ROTATE).
- 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
@@ -250,34 +207,30 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
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 production-seconds **per unit**) is determined by the recipe that produces it:
- **Miner recipe**: `duration_seconds / output_amount`, where `output_amount` is the number of units produced per cycle.
- **Smelter recipe**: `(duration_seconds + Σ (input_threat × input_amount)) / output_amount`, where the sum is over all inputs.
- **Assembler recipe**: `(duration_seconds + Σ (input_threat × input_amount)) / output_amount`, where the sum is over all inputs.
- **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. (Reprocessing output amounts are 1 in practice, so per-unit division is already implicit in the formula.)
- **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 eligible recipes, and the threat is committed only once every eligible recipe is computable (so a shallow shortcut recipe that resolves earlier than a deeper base recipe cannot lower the item's threat). The reprocessing path is only used when no other recipe exists. If recipe cycles prevent full resolution, the max over the currently computable subset is used as a fallback.
- **Scrap-consuming recipe fallback**: a non-reprocessing recipe that takes `scrap` as an input participates in an item's threat computation only if no scrap-free recipe (miner, smelter, or assembler) produces that item. This mirrors the reprocessing fallback rule and prevents the scrap-to-ingot smelter recipe from inflating basic material threats via the max rule.
- 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 the constant `1 / world.toml [world].scrap_per_threat`. This is the exact inverse of the scrap-drop conversion in REQ-RES-SCRAP-DROP, so a destroyed ship drops scrap worth precisely its own threat cost. Because scrap threat is now a fixed constant, it no longer depends on any ship's threat cost, removing the potential circularity with REQ-MOD-THREAT for ships built from reprocessing-only materials.
- 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 value — the hull stat value (for hull stats) or the capability module's base stat value (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 the module's multiplicative modifier value.
- `total_additive` = sum of all additive modifier values from all passive module instances. Each additive value is the module's additive modifier value.
- `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 modifiers follow the naming convention: a module may define `added_<stat>` (additive) and/or `multiplied_<stat>` (multiplicative) under `[module.<category>]`. The category determines what the modifier targets:
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.
- `[module.cargo]` — modifiers (`added_cargo_capacity`/`multiplied_cargo_capacity`) apply to the ship's **cargo capacity**, a ship-level stat (see REQ-MOD-CARGO-CAPACITY).
Example: `[module.sensor].added_sensor_range` adds to the ship's sensor range. `[module.weapon].multiplied_damage` multiplies the damage of every weapon module instance on the ship.
- REQ-MOD-CARGO-CAPACITY: **Cargo capacity** is a first-class ship stat — the total number of scrap units the ship can hold in the single shared cargo pool used by its salvage modules (REQ-SHP-SALVAGE). Unlike other ship stats it has no hull base formula; its `base` (per REQ-MOD-STAT-CALC) is the **sum** of the `cargo_capacity` base values of every cargo-providing capability module instance on the ship — currently each salvage module's `cargo_capacity` value. Passive modifiers targeting `cargo_capacity` are declared under the `[module.cargo]` category and apply to this ship-level sum (`final = base × total_multiplier + total_additive`); they are not salvage-category modifiers and therefore scale the whole pool rather than any single instance. A ship whose cargo capacity is 0 (no cargo-providing module) is given no cargo pool.
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: For a selected shipyard (operational building or construction site), the selected building panel always shows a small non-interactive **ship layout preview** widget below the schematic selection button (REQ-UI-SELECT-BUTTON) and a "Configure" button below the preview. Both are **disabled while no schematic is selected**, and enabled once one is; the preview then shows an empty placeholder in place of a layout grid. When a schematic is selected, 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. For non-shipyard buildings, neither the preview nor the "Configure" button is shown.
- 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:
@@ -287,11 +240,7 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
- **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-AUTO-DIALOG: When the player selects a schematic for a shipyard (operational building or construction site) through the schematic selection dialog (REQ-UI-SELECT-BUTTON), and the chosen schematic **differs** from the shipyard's current schematic, the layout configuration dialog (REQ-MOD-UI-DIALOG) opens automatically and immediately once the selection dialog closes — exactly as if the player had then clicked "Configure". Re-selecting the schematic already set does not reopen the dialog. This auto-open applies only to the manual schematic selection dialog; schematic changes applied via the copy-settings gesture (REQ-BLD-COPY-CONFIG) or blueprint placement (REQ-UI-BLUEPRINT-PLACE) do **not** auto-open the dialog. The player may still cancel the auto-opened dialog (REQ-MOD-UI-DIALOG), which leaves the newly selected schematic in place with its default empty layout; the "Configure" button (REQ-MOD-UI-PREVIEW) remains available to open the dialog again later.
- REQ-MOD-UI-MODULE-TOOLTIP: Each module selection button in the layout configuration dialog (REQ-MOD-UI-DIALOG) shows a hover tooltip with the descriptive text defined for that module type in `modules.toml` (the optional per-module tooltip field). If a module type defines no tooltip text, its button shows no tooltip. The "Remove" button is not a module type and has no config-defined tooltip.
- 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, 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.
- 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
@@ -301,14 +250,13 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
- Maneuvering acceleration
- Angular acceleration
- Max rotation speed
- Cargo capacity — shown only when the ship's cargo capacity (REQ-MOD-CARGO-CAPACITY) is greater than 0
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 (HP/s) = Σ(repair_rate_i × repair_amount_hp_i) across all repair module instances; maximum range = max(repair_range_i) across all repair 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.
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.
@@ -335,43 +283,40 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
- 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). Before drawing schematic picks, an artifact roll is made: evaluate `world.toml [world].artifact_chance_formula` with `x` set to the level of the destroyed station set, clamp the result to [0, 1], then compare against a uniform random value in [0, 1). If the roll succeeds, the dialog presents one **artifact option** plus two schematic picks drawn from the eligible pool; otherwise it presents three schematic picks. Up to three (or two, if an artifact option is present) schematic options are drawn uniformly at random **without replacement** from the eligible drop pool. If the pool contains fewer than the required number of entries, only that many schematic options are shown (the artifact option is always shown if the roll succeeded). The eligible drop pool contains:
- All **ship schematics** and **module schematics** whose `unlock_at_station_level` is ≥ 0 and ≤ the level of the destroyed station set, and which have not yet been unlocked.
- 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.
In addition to the conditions above, a schematic is included in the eligible drop pool only when every prerequisite in its optional `unlock_requires` list is currently satisfied (REQ-LOCK-PREREQ). Because the pool is rebuilt for each drop, a schematic gated behind prerequisites first appears only after all of its prerequisites have themselves been unlocked.
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 in the dialog displays: the schematic name (ship `id` from `ships.toml`, module `id` from `modules.toml`, or assembler recipe `id` from `recipes.toml`) and the schematic type (ship, module, or assembler recipe). The artifact option (if present) is displayed as a distinct entry with the name "Artifact".
Each option additionally displays a vertical list of recipe names labeled "Unlocks recipes:", showing which miner and assembler recipes would newly become implicitly unlocked (REQ-LOCK-IMPLICIT) if this option were selected — specifically, the 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, its `materials` are added to the base set per REQ-LOCK-IMPLICIT step 1a before recomputation.
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.
Each recipe is listed by its `id` (using the same display convention as the assembler recipe-selection dialog), sorted alphabetically. Hovering a recipe in this list displays the recipe info tooltip described for a recipe in REQ-UI-SELECT-TOOLTIP (the recipe name; the name and quantity of each input item; the completion time; and the name and quantity of the produced output item). If no recipes would be newly unlocked, the list shows "None".
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. If the player selects the artifact option, the player's artifact count is incremented by 1 (REQ-WIN-ARTIFACT-COUNT) and the dialog closes; no schematic is applied. Otherwise, the selected schematic is applied and the dialog closes:
The player selects one option by clicking it. The selected schematic is applied and the dialog closes:
For a **ship or module 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)).
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 dialog (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).
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-PREREQ: A ship schematic, module schematic, or assembler recipe schematic may optionally define `unlock_requires` — a list of prerequisite schematic ids (a ship `id`, module `id`, or assembler recipe `id`) that must already be unlocked before this schematic may enter the drop pool. A prerequisite is **satisfied** only when the schematic it names is currently **explicitly unlocked** (REQ-LOCK-EXPLICIT) — that is, the referenced schematic either started unlocked with `unlock_at_station_level = -1` or has been awarded via a drop. This prerequisite check is applied in addition to the per-schematic conditions in REQ-DEF-SCHEMATIC-DROP: a schematic enters the eligible drop pool only when its `unlock_at_station_level` condition is met, it has not yet been unlocked/awarded, and every id in its `unlock_requires` is satisfied. `unlock_requires` defaults to empty (no prerequisites), which reproduces the prior behaviour. The check is re-evaluated against the current explicit-unlock set every time a drop pool is built (after each REQ-DEF-SCHEMATIC-DROP and on Restart per REQ-CFG-RELOAD), so a gated schematic becomes eligible in the first drop after its last prerequisite is unlocked. Every id listed in any `unlock_requires` must resolve to a schematic that is itself explicitly unlockable (a ship, module, or assembler recipe schematic defined in config); an id that names no such schematic is a configuration error that fails config load with a descriptive message (config is loaded at startup and reloaded on Restart, REQ-CFG-RELOAD). A schematic that lists itself, or a cycle of mutually dependent prerequisites, is not a load error but can never become eligible, since no schematic in the cycle can be the first to unlock.
- 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 recipe-selection dialog by virtue of REQ-LOCK-EXPLICIT; their inputs are also added to the implicit set in this step.
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 dialogs (REQ-UI-SELECT-BUTTON).
- 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 dialog (REQ-UI-SELECT-BUTTON).
- 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).
@@ -379,10 +324,11 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
## 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 formula.
- 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.
@@ -397,7 +343,7 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
## 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. The building block cost of an expansion is defined by the formula `world.toml [expansion].cost_building_blocks_formula`, where `x` is the number of expansions already purchased (0 for the first expansion, incrementing by 1 for each subsequent expansion). The formula is evaluated at purchase time and its result is floored to an integer number of building blocks.
- REQ-EXP-COST: Each expansion adds `world.toml [expansion].columns_per_expansion` columns and costs `[expansion].cost_building_blocks` building blocks.
## UI
@@ -422,24 +368,15 @@ The screen is divided into two columns: a main column (75% width) containing the
(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, the current global building blocks stock, and the artifact count (REQ-WIN-ARTIFACT-COUNT) displayed as `Artifacts: x/y` (where `x` is the current artifact count and `y` is `world.toml [world].artifact_win_count`) on the left, the boss wave counter and boss countdown (REQ-UI-BOSS-STATUS) and an asteroid expansion button (REQ-UI-EXPAND-BUTTON) to the left of the speed buttons, and game speed controls on the right.
- REQ-UI-BLOCKS-TOOLTIP: The header bar's building blocks stock display (REQ-UI-HEADER) shows a hover tooltip with the descriptive text defined in `world.toml [world].building_blocks_tooltip` — intended to tell the player what building blocks are used for and how to obtain them. If the field is unset, the stock display shows no tooltip. This tooltip is distinct from the build/module button tooltips (REQ-UI-BUILD-TOOLTIP, REQ-MOD-UI-MODULE-TOOLTIP).
- 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-EXPAND-BUTTON: The header bar shows an asteroid expansion button captioned `Expand: <x> Blocks`, where `<x>` is the current expansion cost computed from `world.toml [expansion].cost_building_blocks_formula` at the current number of purchased expansions (REQ-EXP-COST). Clicking the button unlocks the next asteroid expansion (REQ-EXP-UNLOCK, REQ-GW-ASTEROID-EXPAND), spending that many building blocks from the global stock. The button is disabled when the player cannot currently afford the cost (consistent with REQ-UI-BUILD-DISABLED). The caption updates as the cost changes with each purchased expansion.
- 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).
- REQ-UI-MODAL-DIM: While a modal dialog, menu, or full-screen state screen is open on top of the game, a transparent black overlay (a dim/scrim) is drawn over the **entire game window** — the header bar, the game world view, and the side panel column — behind that modal, so the game reads as inactive while the modal holds focus. The overlay is shown for every modal that auto-pauses the simulation — the escape menu (REQ-UI-GAME-MENU), the recipe/schematic selection dialog (REQ-UI-SELECT-BUTTON), the layout configuration dialog (REQ-MOD-UI-DIALOG), and the schematic choice dialog (REQ-DEF-SCHEMATIC-DROP) — as well as the game-over screen (REQ-HQ-GAME-OVER) and the win screen (REQ-WIN-SCREEN), which end rather than pause the game. When modals are nested (for example the Create Blueprint name dialog (REQ-MOD-UI-BLUEPRINT-CREATE) opened from the layout configuration dialog), only a single dim is shown over the game window; nested modals do not stack additional overlays. The dim color and opacity are read from `visuals.toml [overlays]` (a semi-transparent black modal-dim color), consistent with the other overlay colors. The overlay is presentation-only and has no effect on the simulation.
### Game World
- REQ-UI-SCROLL: The player scrolls the view horizontally across the scrollable area by pressing A (scroll left) and D (scroll right). The pan speed is not constant; it varies with the view's position per REQ-UI-SCROLL-SPEED.
- REQ-UI-SCROLL-SPEED: The horizontal pan speed varies with position so the player crosses the empty middle of the world quickly while retaining fine control near the asteroid and near the front line. Two pan speeds are read from `world.toml [scroll]`: `pan_speed_slow_tiles_per_second` (the base speed, used while the view is over the asteroid and player buffer zone) and `pan_speed_fast_tiles_per_second` (the faster speed, used while the view is over the contest zone). Both are expressed in tiles per second and apply equally to the A and D scroll directions. The current pan speed is a function of the view's horizontal center X (REQ-GW-REGIONS defines the regions):
- **Flat regions:** while the view center is left of the contest zone (over the asteroid or player buffer zone) and outside any ramp band, the pan speed is the slow speed; while the view center is inside the contest zone and outside any ramp band, the pan speed is the fast speed.
- **Ramp bands:** a transition ramp band of width `world.toml [scroll].pan_ramp_band_width_tiles` tiles straddles each contest-zone boundary (the player defence stations on the left, the enemy defence stations on the right), centered on the boundary with half the band width on each side. While the view center is within a ramp band, the pan speed is linearly interpolated between the slow speed at the band's outer (non-contest-zone) edge and the fast speed at the band's inner (contest-zone) edge, by the view center's fractional position across the band. This produces smooth speed changes when entering and exiting the fast contest-zone range rather than an abrupt jump.
- **Narrow contest zone:** should the two ramp bands overlap (a contest zone narrower than the band width), each ramp is clamped at the contest-zone center so the bands do not cross; the fast plateau then reduces to a single point at the center and the peak speed there may be below the fast speed.
Because the contest-zone boundaries shift as the scrollable area grows with each push (REQ-GW-PUSH-EXPAND, REQ-GW-SCROLL-LIMIT), the ramp bands are recomputed from the current contest-zone boundaries. This is a presentation-only concern and does not affect the simulation, consistent with REQ-UI-NO-ZOOM.
- 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.
@@ -448,18 +385,14 @@ The screen is divided into two columns: a main column (75% width) containing the
- **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×).
- **A / D** — scroll the view left / right (REQ-UI-SCROLL).
- **Q** — context-sensitive. If a build mode is active (builder mode or blueprint placement mode), pressing Q exits it. Otherwise, pressing Q toggles demolish mode: it enters demolish mode if inactive, or exits demolish mode if already active. (See also REQ-UI-DEMOLISH-BUTTON for the equivalent button.)
- **R / Shift+R** — in builder mode, rotate the ghost counter-clockwise / clockwise (REQ-BLD-ROTATE).
- **T** — create a temporary blueprint from the current selection and enter its placement mode (REQ-UI-BLUEPRINT-TEMP).
- **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).
- **Build mode selection** — pressing a build hotkey activates builder mode for the corresponding building type, equivalent to clicking its build button (REQ-BLD-BUILDER-MODE):
- **1** — Belt, **2** — Splitter, **3** — Tunnel Entry, **4** — Tunnel Exit.
- **Shift+1** — Miner, **Shift+2** — Smelter, **Shift+3** — Assembler, **Shift+4** — Shipyard, **Shift+5** — Salvage Bay, **Shift+6** — Reprocessing Plant.
- **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 **F3** key. 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-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).
@@ -478,61 +411,43 @@ The screen is divided into two columns: a main column (75% width) containing the
### Selected Building Panel
- REQ-UI-EMPTY-SELECTION: When nothing is selected (no building, construction site, ship, defence station, or scrap pile), 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). For a selected construction site, the recipe/schematic selection (and, for a shipyard, the layout preview and "Configure" button) are shown but the buffer rows are omitted (REQ-BLD-SITE-CONFIG).
- 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. A box-drag that covers at least one building selects buildings (any scrap piles within the box are ignored); a box-drag that covers no buildings but does cover scrap piles selects those scrap piles instead (REQ-UI-SCRAP-MULTI-SELECT).
- 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. The panel additionally shows the **total building block cost** of the selection — the sum of each selected building's placement cost (`buildings.toml [[building]].cost`, per REQ-BLD-COST), counting only player-placeable buildings (buildings with a button in the build button grid); non-player-placeable buildings (the HQ and defence stations) are excluded from the total, consistent with the blueprint total (REQ-UI-BLUEPRINT-BUTTON). Construction sites count at their building type's full placement cost regardless of construction progress.
- REQ-UI-CONFIG-INLINE: Recipe and schematic configuration for a selected building is shown within this panel. Recipe selection (miner, assembler) and schematic selection (shipyard) use the selection button and dialog (REQ-UI-SELECT-BUTTON) rather than an inline control. For shipyards, the panel additionally shows the ship layout preview and "Configure" button below the schematic selection button (REQ-MOD-UI-PREVIEW).
- REQ-UI-SELECT-BUTTON: **Recipe and schematic selection control.** Recipe selection (Miner ore type, Assembler recipe) and schematic selection (Shipyard) are each presented in the selected building panel as a single **selection button** whose caption is the name of the currently selected recipe or schematic, or a placeholder ("Select recipe" / "Select schematic") when none is selected. Clicking the button opens a modal **selection dialog** that pauses the game (speed set to 0×; on close, the speed is restored to what it was before the dialog was opened). The dialog contains a grid of option buttons, one per selectable option — only options that are currently unlocked are shown (REQ-LOCK-UI-RECIPE for recipes, REQ-LOCK-UI-SCHEMATIC for schematics). Hovering an option button shows the selection info tooltip (REQ-UI-SELECT-TOOLTIP). Clicking an option button selects that recipe/schematic, closes the dialog, and updates the selection button's caption in the selected building panel. The dialog can be dismissed without changing the current selection (e.g. closing it without clicking an option). Selecting a new recipe or schematic has the same effects as before (REQ-MAT-INPUT-BUFFER, REQ-MAT-OUTPUT-BUFFER, REQ-BLD-SHIPYARD).
- REQ-UI-SELECT-TOOLTIP: **Selection info tooltip.** Hovering an option button in the selection dialog (REQ-UI-SELECT-BUTTON), and hovering the selection button in the selected building panel when a selection is set, displays an info tooltip:
- For a **recipe** (Miner or Assembler): the recipe name; the name and quantity of each input item (no inputs are listed for miner recipes, which consume nothing); the completion time (`duration_seconds`); and the name and quantity of the produced output item.
- For a **ship schematic** (Shipyard): the ship's `display_name`; the name and quantity of each base required material (`[ship.schematic].materials`, excluding any module contributions); the base production time (`[ship.schematic].production_time_seconds`); and "Produces: 1 <ship display name>".
- 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 a scrap pile instead establishes a scrap selection (REQ-UI-SCRAP-CLICK-SELECT). Clicking empty world space (no building, ship, defence station, or scrap pile) 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 from 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-SHIP-BEHAVIOR: The ship stats panel (REQ-UI-SHIP-STATS-PANEL) additionally displays the selected ship's **current behavior** — a single label naming the top-priority behavior currently governing the ship's navigation, as resolved by the fixed-priority behavior arbitration. Only the winning behavior is named; lower-priority behaviors that are suppressed are not shown, and neither are the salvage/repair cycles that run regardless of the active behavior (REQ-SHP-SALVAGE, REQ-SHP-REPAIR). The label updates live as the ship's behavior changes, and it is always shown (independent of debug draw mode, unlike the threat-cost line of REQ-UI-SHIP-STATS-PANEL). This applies to both player and enemy ships (REQ-UI-ENTITY-CLICK-SELECT); enemy ships only ever show **Engaging** or **Advancing**. The behavior labels (all wrapped in `tr()`) are:
- **Retreating** — the ship is retreating (REQ-SHP-RETREAT).
- **Engaging** — the ship is engaging a combat target (player: REQ-SHP-COMBAT; enemy: REQ-SHP-ENEMY-AI).
- **Salvaging** — the ship is executing salvage navigation: seeking scrap, collecting, or delivering to a Salvage Bay (REQ-SHP-SALVAGE).
- **Repairing** — the ship is navigating to a repair target (REQ-SHP-REPAIR).
- **Rallying** — the ship is moving to or orbiting the rally point (REQ-SHP-RALLY).
- **Standby** — the ship is holding with its fleet (REQ-SHP-STANDBY).
- **Advancing** — the ship is executing the baseline forward advance with no higher-priority behavior active (player: REQ-SHP-COMBAT advance toward the enemy; enemy: REQ-SHP-ENEMY-AI advance toward the asteroid).
- 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.
- REQ-UI-SCRAP-CLICK-SELECT: The player can click any scrap pile (REQ-RES-SCRAP-DROP) in the game world to select it. Scrap forms its own selection category: clicking a scrap pile clears any existing selection and establishes a scrap selection containing only that pile. Scrap piles cannot participate in a selection together with buildings, ships, or defence stations. Hit-testing prioritizes actors over scrap: when a building, ship, or defence station lies under the cursor at the same point as a scrap pile, that object is selected in preference to the scrap; a scrap pile is selected only when no building, ship, or defence station is under the cursor. A selected scrap pile that despawns or is fully collected (REQ-RES-SCRAP-DROP) is removed from the selection; once the last selected pile is gone, the selection becomes empty (REQ-UI-EMPTY-SELECTION).
- REQ-UI-SCRAP-MULTI-SELECT: Multiple scrap piles can be selected by box-drag or by Ctrl+clicking individual piles to add or remove them from the selection, mirroring building multi-select (REQ-UI-MULTI-SELECT). A scrap selection contains only scrap piles. Because scrap cannot mix with other object types (REQ-UI-SCRAP-CLICK-SELECT), Ctrl+clicking a scrap pile while a building, ship, or defence station selection is active first clears that selection and begins a scrap selection; conversely, selecting a building, ship, or defence station while a scrap selection is active clears the scrap selection. Box-drag disambiguation between buildings and scrap follows REQ-UI-MULTI-SELECT (a box covering any building selects buildings; a box covering scrap but no buildings selects the scrap).
- REQ-UI-SCRAP-PANEL: When one or more scrap piles are selected, the selected building panel shows the **total remaining scrap amount** across all selected piles — the sum of the piles' current remaining amounts (REQ-RES-SCRAP-DROP), e.g. "Scrap: 47". The same summed-amount display is used whether one pile or many are selected; no per-pile detail and no pile count are shown. The displayed total updates as selected piles are partially collected or despawn (REQ-UI-SCRAP-CLICK-SELECT).
### 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-TOOLTIP: Each building-type button shows a hover tooltip with the descriptive text defined for that building type in `buildings.toml` (the optional per-building tooltip field). This tooltip is distinct from the recipe/schematic selection tooltip (REQ-UI-SELECT-TOOLTIP). If a building type defines no tooltip text, its button shows no tooltip. The Demolish button (REQ-UI-DEMOLISH-BUTTON) is not a building type and has no config-defined tooltip.
- 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 the Q demolish toggle (REQ-UI-HOTKEYS). The button is shown in a visually active/pressed state while demolish mode is active.
- 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). The panel has no Save or Load buttons; blueprints are persisted automatically (REQ-UI-BLUEPRINT-SAVE) and restored at startup (REQ-UI-BLUEPRINT-LOAD).
- 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. A selected player-placeable building may be either an operational building or a construction site (a building placed but not yet fully built, REQ-BLD-SITE-CONFIG); both count toward this condition and are captured identically (REQ-UI-BLUEPRINT-STORAGE). 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-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-TEMP: Pressing the **T** key (REQ-UI-HOTKEYS) creates a **temporary blueprint** from the current selection and immediately enters blueprint placement mode for it, without opening the naming dialog. It has effect only when at least one player-placeable building is currently selected — the same condition as REQ-UI-BLUEPRINT-CREATE; pressing T with an empty selection, or a selection containing only non-player-placeable buildings (HQ, defence stations), does nothing. Entering this mode replaces any currently active build, blueprint placement, or demolish mode. The temporary blueprint is captured exactly as a saved blueprint (REQ-UI-BLUEPRINT-STORAGE), silently excluding any non-player-placeable buildings from the selection, but it is never named, never shown in the blueprint panel (REQ-UI-BLUEPRINT-PANEL), and never persisted to `blueprints.toml` (REQ-UI-BLUEPRINT-SAVE). Placement behaves identically to a saved blueprint's placement mode (REQ-UI-BLUEPRINT-MODE, REQ-UI-BLUEPRINT-PLACE): a ghost is rendered per building, R / Shift+R rotate the entire constellation, placement follows the same per-building validity and total-cost rules, and after a successful placement the mode stays active so the blueprint can be placed again. Right-clicking in the game world exits placement mode, at which point the temporary blueprint is discarded.
- 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), and for splitters the two output filters (each a list of item types; an empty list means accept-all), at the time of capture. A source building may be either an operational building or a construction site (REQ-BLD-SITE-CONFIG); a construction site is captured identically, storing whatever configuration it currently holds and never any buffer or construction-progress state. If no recipe or schematic was selected at capture time, none is stored; for a splitter with no filters set, no filter lists are stored. This structure maps directly to a TOML representation (e.g. one `[[building]]` array entry per constituent building, with the splitter filters as `filter_a`/`filter_b` arrays of item-type ids).
- 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). A valid ghost uses its building type's semi-transparent per-building coloring (REQ-BLD-GHOST); an invalid ghost uses the distinct "invalid" color, as in single-building builder mode. Pressing R / Shift+R 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-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. If splitter output filters are stored, they are applied to the construction site immediately and carry over when it finishes building (REQ-BLD-SITE-CONFIG). 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-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: On application shutdown, all current blueprints are serialized to a file named `blueprints.toml` located in the same directory as the application executable. The TOML structure matches REQ-UI-BLUEPRINT-STORAGE. Write errors are silently ignored on shutdown (no button, no dialog).
- 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: At application startup, blueprints are loaded from `blueprints.toml` in the same directory as the application executable, populating the blueprint list (in the order they appear in the file). 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. There is no Load button and no runtime reload.
- 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
@@ -541,7 +456,7 @@ A separate executable target (`balancing`) that links against `lib` but contains
### 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. Ship stats are the plain values from `ships.toml`; defence station formula evaluation uses the station levels specified in the arena config.
- 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
@@ -551,7 +466,7 @@ A separate executable target (`balancing`) that links against `lib` but contains
- **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), 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.
- 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.
@@ -559,24 +474,20 @@ A separate executable target (`balancing`) that links against `lib` but contains
### 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. 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-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, a "Start All" button, and a "Log" 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-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-LOG: The "Log" button is placed in the header to the right of the "Start All" button. It is enabled whenever the main window's controls are enabled — including while simulations are running (it captures a live snapshot) — and, like all main window controls, is disabled only while an arena is being inspected (REQ-BAL-UI-WINDOW). Clicking it writes the current state of every arena to a file named `balancing_log.md` in the tool's current working directory, replacing (overwriting) any previous content of that file. The log captures, for every arena in `balancing.toml` order, exactly the information shown in that arena's widget (REQ-BAL-UI-WIDGET) at the moment the button is clicked. Each arena is written as its own section:
- A heading with the arena name followed by the arena's current state — `not started`, `running`, or `ended` (corresponding to the widget border colors of REQ-BAL-UI-WIDGET-BORDER). For an `ended` arena, the heading also includes the battle duration (REQ-BAL-UI-WIDGET), for example `ended, 42.3 s`.
- A markdown table with one column per team (team 1 left, team 2 right). Each team's column header shows the team name — prefixed with `[WON]` when that team won, matching REQ-BAL-UI-WIDGET — the team's accumulated threat level, and the team's remaining EHP percentage (REQ-BAL-UI-WIDGET).
- Below the header, each table row holds one of that team's entries, in the same order and text format as the widget (REQ-BAL-UI-WIDGET): the HQ first, then ship types, then defence stations, formatted `surviving/total TypeName` for ship entries and `surviving/total TypeName Llevel` for the HQ and defence station entries. When the two teams have different numbers of entries, the shorter column's remaining cells are left blank.
- 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, then directly below the header the team's **accumulated threat level** — the sum, across the team's configured ship entries, of each entry's `count` multiplied by the threat cost (REQ-MOD-THREAT) of one ship of that entry computed from its level-independent module layout. Only ships contribute; the HQ and defence stations are excluded. This value is static: it is computed once from the full configured roster and does not change as ships are destroyed during the fight. Directly below the threat level, the column shows the team's **remaining EHP percentage** — the sum of the current HP of all of the team's ships and defence stations, divided by the sum of their maximum HP, expressed as a percentage rounded to a whole number. Maximum HP is the final per-entity maximum (REQ-MOD-STAT-CALC), so module HP bonuses such as armor plates are included. (The game has no damage mitigation, so effective HP equals raw HP.) The HQ is excluded from both sums. A destroyed ship or station contributes 0 to the numerator and its maximum HP to the denominator, so the value measures how much of the team's fielded durability remains: it starts at 100% and decreases as units take damage or are destroyed. Unlike the static threat level, this value updates live as the simulation progresses. If the team has neither ships nor defence stations (the denominator is 0), the percentage is shown as `n/a`. Below the EHP percentage, the column shows 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` for ship entries and `surviving/total TypeName Llevel` for the HQ and defence station entries — for example `2/3 Fighter`, `1/1 HQ L1`, or `2/2 Enemy Station L3`. The surviving count updates live as the simulation progresses. When the fight ends, the winning team's name header is prefixed with `[WON]`. When the fight has ended, the widget also displays the arena's **battle duration** — an arena-level value (not per team) giving the game time the fight lasted, computed as the number of simulated ticks at completion multiplied by the simulation's fixed tick duration (the same tick-based simulation as the main game, REQ-BAL-SIM-ENV). This is game time, not wall-clock time, so it is independent of how fast the arena was simulated (non-inspected arenas run at maximum tick rate, REQ-BAL-SIM-SPEED). It is shown in seconds with one decimal place, for example `Duration: 42.3 s`. The battle duration is shown only for completed (ended) runs; it is not shown while the arena is not started or 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, including the arena's battle duration once the fight has ended (REQ-BAL-UI-WIDGET).
- 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.

15
src/CMakeLists.txt
View File

@@ -1,4 +1,4 @@
set(TARGET_BASE_NAME "${PRODUCT_NAME}")
set(TARGET_BASE_NAME "DotaFactory")
set(TARGET_APP_NAME "${TARGET_BASE_NAME}")
set(TARGET_LIB_NAME "${TARGET_BASE_NAME}_lib")
@@ -183,19 +183,6 @@ target_compile_definitions(${TARGET_APP_NAME} PRIVATE
)
target_link_libraries(${TARGET_APP_NAME} ${TARGET_UI_NAME})
# Embed the Windows version resource so the version shows on the executable's
# Details tab (right-click -> Properties). Values come from cmake/version.cmake
# (version numbers) and the product identity variables in the top-level
# CMakeLists.txt. MSVC compiles the .rc automatically once it is a target source.
if (WIN32)
configure_file(
"${CMAKE_SOURCE_DIR}/cmake/version.rc.in"
"${CMAKE_CURRENT_BINARY_DIR}/version.rc"
@ONLY
)
target_sources(${TARGET_APP_NAME} PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/version.rc")
endif ()
unset(APP_FILES)
unset(RELATIVE_HDRS)
unset(RELATIVE_SRCS)

53
src/app/main.cpp
View File

@@ -1,7 +1,4 @@
#include <memory>
#include <optional>
#include <random>
#include <string>
#include <QApplication>
#include <QDir>
@@ -11,8 +8,6 @@
#include "logging.h"
#include "LogManager.h"
#include "MainWindow.h"
#include "ReplayReader.h"
#include "ReplayRecorder.h"
#include "Simulation.h"
int main(int argc, char *argv[])
@@ -36,54 +31,10 @@ int main(int argc, char *argv[])
QDir().mkdir(dataDir.dirName());
}
// Optional "--replay <file>" launches view-only playback of a recorded run.
std::optional<std::string> replayPath;
for (int i = 1; i + 1 < argc; ++i)
{
if (std::string(argv[i]) == "--replay")
{
replayPath = argv[i + 1];
break;
}
}
GameConfig config = ConfigLoader::loadFromDirectory(CONFIG_DIR);
std::unique_ptr<Simulation> sim = std::make_unique<Simulation>(std::move(config));
unsigned int seed = 0;
std::shared_ptr<ParsedReplay> replay;
if (replayPath.has_value())
{
std::optional<ParsedReplay> parsed = readReplayFile(*replayPath);
if (!parsed.has_value())
{
LOG_ERROR("Failed to read replay file: " + *replayPath);
return 1;
}
// Warn (but proceed) on identity mismatches: a different config or build
// can desync playback (see docs/replay_design.md).
if (parsed->header.version != 1)
{
LOG_WARNING_STREAM(<< "Replay format version " << parsed->header.version
<< " differs from 1; playback may fail");
}
if (computeReplayConfigHash(CONFIG_DIR) != parsed->header.configHash)
{
LOG_WARNING("Replay config hash mismatch; playback may desync");
}
seed = parsed->header.seed;
replay = std::make_shared<ParsedReplay>(std::move(*parsed));
}
else
{
// Random seed generated outside the sim so the Simulation stays a pure
// function of (seed, config, commands); written to the replay header
// (see docs/replay_design.md "Seed and config").
seed = std::random_device{}();
}
std::unique_ptr<Simulation> sim = std::make_unique<Simulation>(std::move(config), seed);
MainWindow window(sim.get(), std::string(CONFIG_DIR), replay);
MainWindow window(sim.get(), std::string(CONFIG_DIR));
window.show();
const int ret = application.exec();

149
src/balancing/ArenaSimulation.cpp
View File

@@ -2,8 +2,6 @@
#include <algorithm>
#include <cassert>
#include <cmath>
#include <string>
#include <QVector2D>
@@ -16,12 +14,9 @@
#include "EntityAdmin.h"
#include "FactionComponent.h"
#include "HealthComponent.h"
#include "HqProxyComponent.h"
#include "ModuleOwnerComponent.h"
#include "MovementIntentSystem.h"
#include "PositionComponent.h"
#include "RepairSystem.h"
#include "SalvagerSystem.h"
#include "ScrapSystem.h"
#include "ShipIdentityComponent.h"
#include "ShipSystem.h"
@@ -29,7 +24,6 @@
#include "StationBodyComponent.h"
#include "StationsConfig.h"
#include "SurfaceMask.h"
#include "ThreatCostCalculator.h"
#include "WeaponComponent.h"
ArenaSimulation::ArenaSimulation(const GameConfig& gameConfig,
@@ -57,80 +51,20 @@ ArenaSimulation::ArenaSimulation(const GameConfig& gameConfig,
m_rng);
m_shipSystem = std::make_unique<ShipSystem>(m_gameConfig, m_admin);
// Arena fights are symmetric and aggressive: player-faction ships must not
// retreat (REQ-BAL-SIM-AI). Only one faction would otherwise get retreat.
m_shipSystem->setRetreatEnabled(false);
m_aiSystem = std::make_unique<AiSystem>(m_gameConfig);
m_aiSystem = std::make_unique<AiSystem>();
m_movementIntentSystem = std::make_unique<MovementIntentSystem>();
m_dynamicBodySystem = std::make_unique<DynamicBodySystem>();
m_combatSystem = std::make_unique<CombatSystem>(m_gameConfig);
m_scrapSystem = std::make_unique<ScrapSystem>(m_admin);
m_salvagerSystem = std::make_unique<SalvagerSystem>(m_admin);
m_repairSystem = std::make_unique<RepairSystem>(m_admin);
// Static accumulated threat per team: sum of count * per-ship threat cost
// (REQ-MOD-THREAT) over the configured ship roster. Ships only; HQ and
// defence stations are excluded. Level-independent, so computed once here.
for (int ti = 0; ti < 2; ++ti)
{
double teamThreat = 0.0;
for (const ArenaShipEntry& shipEntry : m_arenaConfig.teams[ti].ships)
{
const std::vector<PlacedModule>& modules = shipEntry.layout
? shipEntry.layout->placedModules
: std::vector<PlacedModule>{};
const double shipThreat = calculateShipThreatCost(
m_gameConfig.threatCosts, m_gameConfig, shipEntry.schematicId, modules);
teamThreat += shipThreat * shipEntry.count;
}
m_teamThreat[ti] = teamThreat;
}
placeStructures();
spawnShips();
computeTeamMaxEhp();
m_shipSystem->triggerRallyDeparture();
updateStatus();
}
std::string ArenaStatus::TeamStatus::ehpPercentText() const
{
if (maxEhp <= 0.0)
{
return "n/a";
}
const int percent = static_cast<int>(std::lround(100.0 * currentEhp / maxEhp));
return std::to_string(percent) + "%";
}
void ArenaSimulation::computeTeamMaxEhp()
{
m_teamMaxEhp[0] = 0.0;
m_teamMaxEhp[1] = 0.0;
// Ships contribute their full max HP.
m_admin.forEach<ShipIdentityComponent, FactionComponent, HealthComponent>(
[this](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const FactionComponent& f, const HealthComponent& h)
{
m_teamMaxEhp[f.isEnemy ? 1 : 0] += static_cast<double>(h.maxHp);
});
// Defence stations contribute their full max HP; the HQ is excluded.
m_admin.forEach<StationBodyComponent, FactionComponent, HealthComponent>(
[this](entt::entity e, const StationBodyComponent& /*sb*/,
const FactionComponent& f, const HealthComponent& h)
{
if (m_admin.hasAll<HqProxyComponent>(e))
{
return;
}
m_teamMaxEhp[f.isEnemy ? 1 : 0] += static_cast<double>(h.maxHp);
});
}
ArenaSimulation::~ArenaSimulation() = default;
BuildingId ArenaSimulation::allocateBuildingId()
@@ -161,8 +95,6 @@ void ArenaSimulation::placeStructures()
}
m_team1HqEntity = m_admin.spawnStation(anchor, hqParsed.footprint, absCells,
hp, hp, false);
// Tag as an HQ so it is excluded from repair targeting (REQ-SHP-REPAIR).
m_admin.addComponent<HqProxyComponent>(m_team1HqEntity);
m_buildingSystem->registerTileOccupancy(absCells, allocateBuildingId());
}
@@ -182,8 +114,6 @@ void ArenaSimulation::placeStructures()
}
m_team2HqEntity = m_admin.spawnStation(anchor, hqParsed.footprint, absCells,
hp, hp, true);
// Tag as an HQ so it is excluded from repair targeting (REQ-SHP-REPAIR).
m_admin.addComponent<HqProxyComponent>(m_team2HqEntity);
m_buildingSystem->registerTileOccupancy(absCells, allocateBuildingId());
}
@@ -270,7 +200,7 @@ void ArenaSimulation::spawnShips()
for (int i = 0; i < entry.count; ++i)
{
const QVector2D pos(xDist(m_rng), yDist(m_rng));
m_shipSystem->spawn(entry.schematicId, pos, false,
m_shipSystem->spawn(entry.schematicId, entry.level, pos, false,
entry.layout);
}
}
@@ -287,7 +217,7 @@ void ArenaSimulation::spawnShips()
for (int i = 0; i < entry.count; ++i)
{
const QVector2D pos(xDist(m_rng), yDist(m_rng));
m_shipSystem->spawn(entry.schematicId, pos, true,
m_shipSystem->spawn(entry.schematicId, entry.level, pos, true,
entry.layout);
}
}
@@ -320,17 +250,18 @@ ArenaStatus ArenaSimulation::status() const
void ArenaSimulation::tick()
{
// Ship behavior systems (tick step 7): evaluate, select winner, execute.
// Module + combat systems emit their tool beams into a shared buffer.
// Ship behavior systems (tick step 7).
m_shipSystem->clearMovementIntents();
m_aiSystem->tick(m_admin, *m_buildingSystem, *m_scrapSystem);
std::vector<BeamFiredEvent> beamFiredEvents;
m_salvagerSystem->tick(m_currentTick, *m_scrapSystem, *m_buildingSystem, beamFiredEvents);
m_repairSystem->tick(m_currentTick, beamFiredEvents);
m_aiSystem->tickHomeReturnBehavior(m_admin);
m_aiSystem->tickThreatResponseBehavior(m_admin, *m_buildingSystem);
m_aiSystem->tickRepairBehavior(m_admin, *m_buildingSystem);
m_aiSystem->tickRepairTools(m_admin);
m_aiSystem->tickSalvageBehavior(m_admin, *m_scrapSystem, *m_buildingSystem);
// Combat resolution (tick step 8).
m_combatSystem->tick(m_currentTick, m_admin, *m_buildingSystem, beamFiredEvents);
m_beamFiredEvents.insert(m_beamFiredEvents.end(), beamFiredEvents.begin(), beamFiredEvents.end());
std::vector<WeaponFiredEvent> weaponFiredEvents;
m_combatSystem->tick(m_currentTick, m_admin, *m_buildingSystem, weaponFiredEvents);
m_weaponFiredEvents.insert(m_weaponFiredEvents.end(), weaponFiredEvents.begin(), weaponFiredEvents.end());
m_combatSystem->applyPendingDamage(m_currentTick, m_admin);
// Deaths (tick step 9, simplified).
@@ -369,11 +300,15 @@ void ArenaSimulation::tickDeaths()
{
const ShipIdentityComponent& si = m_admin.get<ShipIdentityComponent>(deadEntity);
const PositionComponent& pos = m_admin.get<PositionComponent>(deadEntity);
if (si.scrapDrop > 0)
for (const ShipDef& def : m_gameConfig.ships.ships)
{
const Tick despawnAt = m_currentTick
+ secondsToTicks(m_gameConfig.world.scrapDespawnSeconds);
m_scrapSystem->spawn(pos.value, si.scrapDrop, despawnAt);
if (def.id == si.schematicId && def.loot.scrapDrop > 0)
{
const Tick despawnAt = m_currentTick
+ secondsToTicks(m_gameConfig.world.scrapDespawnSeconds);
m_scrapSystem->spawn(pos.value, def.loot.scrapDrop, despawnAt);
break;
}
}
m_shipSystem->despawn(deadEntity);
}
@@ -433,13 +368,10 @@ void ArenaSimulation::tickDeaths()
});
m_admin.forEach<StationBodyComponent, FactionComponent>(
[this, &team1HasUnits, &team2HasUnits](entt::entity e,
[&team1HasUnits, &team2HasUnits](entt::entity /*e*/,
const StationBodyComponent& /*sb*/,
const FactionComponent& f)
{
// The HQ carries a StationBodyComponent but is not a defence station;
// its destruction is a separate end condition (REQ-BAL-SIM-END).
if (m_admin.hasAll<HqProxyComponent>(e)) { return; }
if (f.isEnemy) { team2HasUnits = true; }
else { team1HasUnits = true; }
});
@@ -461,10 +393,10 @@ void ArenaSimulation::tickOnce()
}
}
std::vector<BeamFiredEvent> ArenaSimulation::drainBeamFiredEvents()
std::vector<WeaponFiredEvent> ArenaSimulation::drainWeaponFiredEvents()
{
std::vector<BeamFiredEvent> result;
result.swap(m_beamFiredEvents);
std::vector<WeaponFiredEvent> result;
result.swap(m_weaponFiredEvents);
return result;
}
@@ -518,41 +450,11 @@ void ArenaSimulation::updateStatus()
ArenaStatus newStatus;
newStatus.finished = m_finished;
newStatus.winnerTeam = m_winnerTeam;
newStatus.durationSeconds = ticksToSeconds(m_currentTick);
// Live remaining HP of each team's ships and defence stations (HQ excluded);
// the EHP-percentage numerator (denominator is the fixed m_teamMaxEhp).
double currentEhp[2] = {0.0, 0.0};
m_admin.forEach<ShipIdentityComponent, FactionComponent, HealthComponent>(
[&currentEhp](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const FactionComponent& f, const HealthComponent& h)
{
if (h.hp > 0.0f)
{
currentEhp[f.isEnemy ? 1 : 0] += static_cast<double>(h.hp);
}
});
m_admin.forEach<StationBodyComponent, FactionComponent, HealthComponent>(
[this, &currentEhp](entt::entity e, const StationBodyComponent& /*sb*/,
const FactionComponent& f, const HealthComponent& h)
{
if (m_admin.hasAll<HqProxyComponent>(e))
{
return;
}
if (h.hp > 0.0f)
{
currentEhp[f.isEnemy ? 1 : 0] += static_cast<double>(h.hp);
}
});
for (int ti = 0; ti < 2; ++ti)
{
ArenaStatus::TeamStatus& teamStatus = newStatus.teams[ti];
teamStatus.name = m_arenaConfig.teams[ti].name;
teamStatus.threatLevel = m_teamThreat[ti];
teamStatus.currentEhp = currentEhp[ti];
teamStatus.maxEhp = m_teamMaxEhp[ti];
// HQ entry (always first).
{
@@ -571,7 +473,7 @@ void ArenaSimulation::updateStatus()
{
ArenaStatus::Entry entry;
entry.displayName = shipEntry.schematicId;
// Ships no longer carry a level (level suffix stays empty).
entry.level = shipEntry.level;
entry.total = shipEntry.count;
int surviving = 0;
@@ -583,6 +485,7 @@ void ArenaSimulation::updateStatus()
{
if (f.isEnemy == isEnemyTeam
&& si.schematicId == shipEntry.schematicId
&& si.level == shipEntry.level
&& h.hp > 0.0f)
{
++surviving;

36
src/balancing/ArenaSimulation.h
View File

@@ -3,7 +3,6 @@
#include <atomic>
#include <memory>
#include <mutex>
#include <optional>
#include <random>
#include <string>
#include <vector>
@@ -14,7 +13,7 @@
#include "BuildingId.h"
#include "entt/entity/entity.hpp"
#include "BeamFiredEvent.h"
#include "WeaponFiredEvent.h"
#include "GameConfig.h"
#include "Tick.h"
@@ -23,8 +22,6 @@ class BuildingSystem;
class CombatSystem;
class DynamicBodySystem;
class MovementIntentSystem;
class RepairSystem;
class SalvagerSystem;
class ShipSystem;
class ScrapSystem;
@@ -33,9 +30,7 @@ struct ArenaStatus
struct Entry
{
std::string displayName;
// Level suffix shown in the widget/inspect display. Set for the HQ and
// defence stations; empty for ships, which no longer have a level.
std::optional<int> level;
int level;
int total;
int surviving;
};
@@ -43,25 +38,12 @@ struct ArenaStatus
struct TeamStatus
{
std::string name;
double threatLevel = 0.0; // accumulated threat of the team's configured ships
// Remaining durability of the team's ships and defence stations (HQ
// excluded). currentEhp is summed live; maxEhp is the fixed full-HP
// baseline. See ehpPercentText() for the displayed value.
double currentEhp = 0.0;
double maxEhp = 0.0;
std::vector<Entry> entries; // HQ first, then ships, then stations
// Remaining EHP as a whole-number percentage ("NN%"), or "n/a" when the
// team has no ships or stations (maxEhp == 0).
std::string ehpPercentText() const;
};
TeamStatus teams[2];
bool finished = false;
int winnerTeam = -1; // 0 or 1 when finished; -1 while running
// Game time the fight has lasted (simulated ticks * fixed tick duration).
// Meaningful once finished; the battle duration shown for completed runs.
double durationSeconds = 0.0;
};
class ArenaSimulation
@@ -76,7 +58,7 @@ public:
void requestStop();
void tickOnce();
std::vector<BeamFiredEvent> drainBeamFiredEvents();
std::vector<WeaponFiredEvent> drainWeaponFiredEvents();
ArenaStatus status() const;
bool isFinished() const;
@@ -94,7 +76,6 @@ private:
BuildingId allocateBuildingId();
void placeStructures();
void spawnShips();
void computeTeamMaxEhp();
void tick();
void tickDeaths();
void updateStatus();
@@ -115,8 +96,6 @@ private:
std::unique_ptr<DynamicBodySystem> m_dynamicBodySystem;
std::unique_ptr<CombatSystem> m_combatSystem;
std::unique_ptr<ScrapSystem> m_scrapSystem;
std::unique_ptr<SalvagerSystem> m_salvagerSystem;
std::unique_ptr<RepairSystem> m_repairSystem;
entt::entity m_team1HqEntity;
entt::entity m_team2HqEntity;
@@ -125,14 +104,7 @@ private:
int m_winnerTeam;
std::atomic<bool> m_stopRequested;
// Static accumulated threat per team, computed once from the configured roster.
double m_teamThreat[2] = {0.0, 0.0};
// Full-HP baseline per team (ships + defence stations, HQ excluded), computed
// once after spawning; the EHP-percentage denominator.
double m_teamMaxEhp[2] = {0.0, 0.0};
std::vector<BeamFiredEvent> m_beamFiredEvents;
std::vector<WeaponFiredEvent> m_weaponFiredEvents;
mutable std::mutex m_statusMutex;
ArenaStatus m_status;

139
src/balancing/ArenaView.cpp
View File

@@ -2,16 +2,13 @@
#include <algorithm>
#include <cmath>
#include <functional>
#include <optional>
#include <QKeyEvent>
#include <QMouseEvent>
#include <QPainter>
#include <QPoint>
#include "ArenaSimulation.h"
#include "AttackBehavior.h"
#include "Building.h"
#include "BuildingSystem.h"
#include "EntityHitTest.h"
@@ -22,13 +19,9 @@
#include "GameSpeedChangedEvent.h"
#include "HealthComponent.h"
#include "PositionComponent.h"
#include "RepairBehavior.h"
#include "SalvageScrapBehavior.h"
#include "ScrapSystem.h"
#include "SensorRangeComponent.h"
#include "ShipIdentityComponent.h"
#include "StationBodyComponent.h"
#include "ScrapDataComponent.h"
namespace
{
@@ -40,11 +33,11 @@ ArenaView::ArenaView(ArenaSimulation* sim, const VisualsConfig* visuals,
: QOpenGLWidget(parent)
, m_sim(sim)
, m_visuals(visuals)
, m_wallMs(0)
, m_gameSpeedMultiplier(1.0)
, m_prevNonZeroSpeed(1.0)
, m_rng(std::random_device{}())
, m_finishedEmitted(false)
, m_debugDraw(false)
{
setFocusPolicy(Qt::StrongFocus);
@@ -98,6 +91,7 @@ void ArenaView::togglePause()
void ArenaView::onFrame()
{
const qint64 elapsed = m_frameTimer.restart();
m_wallMs += elapsed;
{
const int ticks = m_tickDriver.advance(
@@ -110,22 +104,20 @@ void ArenaView::onFrame()
// Emit fire events via EventManager
{
const std::vector<BeamFiredEvent> fires = m_sim->drainBeamFiredEvents();
for (const BeamFiredEvent& fe : fires)
const std::vector<WeaponFiredEvent> fires = m_sim->drainWeaponFiredEvents();
for (const WeaponFiredEvent& fe : fires)
{
EventManager::getInstance()->sendEventImmediately(
std::make_shared<BeamFiredEvent>(fe));
std::make_shared<WeaponFiredEvent>(fe));
}
}
// Expire old beams. Lifetime is measured in game ticks so beams stay
// visible while the simulation is paused or slowed (REQ-SHP-FIRING-BEAM).
// Expire old beams
{
const Tick now = m_sim->currentTick();
std::vector<ActiveBeam> live;
for (const ActiveBeam& b : m_activeBeams)
{
if (now - b.event.emittedAt < kBeamLifetimeTicks)
if (m_wallMs - b.emittedWallMs < kBeamLifetimeMs)
{
live.push_back(b);
}
@@ -141,7 +133,7 @@ void ArenaView::onFrame()
update();
}
void ArenaView::handleEvent(std::shared_ptr<const BeamFiredEvent> event)
void ArenaView::handleEvent(std::shared_ptr<const WeaponFiredEvent> event)
{
float maxRadius = 0.125f;
if (m_sim->admin().isValid(event->target)
@@ -152,11 +144,6 @@ void ArenaView::handleEvent(std::shared_ptr<const BeamFiredEvent> event)
sb.footprint.height());
maxRadius = shorter / 2.0f;
}
else if (m_sim->admin().isValid(event->target)
&& m_sim->admin().hasAll<ScrapDataComponent>(event->target))
{
maxRadius = 0.1f;
}
std::uniform_real_distribution<float> angleDist(0.0f, 6.28318530f);
std::uniform_real_distribution<float> radiusDist(0.0f, maxRadius);
@@ -165,6 +152,7 @@ void ArenaView::handleEvent(std::shared_ptr<const BeamFiredEvent> event)
ActiveBeam beam;
beam.event = *event;
beam.emittedWallMs = m_wallMs;
beam.targetOffset = QVector2D(radius * std::cos(angle),
radius * std::sin(angle));
m_activeBeams.push_back(beam);
@@ -179,11 +167,6 @@ void ArenaView::paintGL()
drawBuildings(painter);
drawStations(painter);
drawScrap(painter);
if (m_debugDraw)
{
drawDebugSensorRanges(painter);
drawDebugTargetLines(painter);
}
drawShips(painter);
drawBeams(painter);
}
@@ -266,16 +249,6 @@ void ArenaView::mousePressEvent(QMouseEvent* event)
QOpenGLWidget::mousePressEvent(event);
}
void ArenaView::keyPressEvent(QKeyEvent* event)
{
if (event->key() == Qt::Key_F3)
{
m_debugDraw = !m_debugDraw;
return;
}
QOpenGLWidget::keyPressEvent(event);
}
// ---------------------------------------------------------------------------
// Rendering
// ---------------------------------------------------------------------------
@@ -445,106 +418,14 @@ void ArenaView::drawShips(QPainter& painter)
});
}
void ArenaView::drawDebugSensorRanges(QPainter& painter)
{
painter.setBrush(Qt::NoBrush);
m_sim->admin().forEach<ShipIdentityComponent, PositionComponent, SensorRangeComponent>(
[&](entt::entity /*e*/, const ShipIdentityComponent& si,
const PositionComponent& pos, const SensorRangeComponent& sensor)
{
const std::map<std::string, ShipVisuals>::const_iterator it =
m_visuals->ships.find(si.schematicId);
if (it == m_visuals->ships.end()) { return; }
const QPointF center = worldToWidget(pos.value);
const qreal radiusPx = static_cast<qreal>(sensor.value_tiles)
* static_cast<qreal>(tilePx());
QColor circleColor = it->second.outline;
circleColor.setAlpha(77);
painter.setPen(QPen(circleColor, 1));
painter.drawEllipse(center, radiusPx, radiusPx);
});
}
void ArenaView::drawDebugTargetLines(QPainter& painter)
{
// Draw a thin translucent line from a ship to a target, colored by the ship's
// team to match the per-side HQ/station colors used elsewhere in the arena
// (team 1 player, team 2 enemy). Shared by the attack, repair and salvage lines.
const std::function<void(bool, const QVector2D&, const QVector2D&)> drawTargetLine =
[&](bool isEnemy, const QVector2D& from, const QVector2D& to)
{
const BuildingType visType = isEnemy
? BuildingType::EnemyDefenceStation
: BuildingType::PlayerDefenceStation;
const std::map<BuildingType, BuildingVisuals>::const_iterator it =
m_visuals->buildings.find(visType);
if (it == m_visuals->buildings.end()) { return; }
QColor lineColor = it->second.fill;
lineColor.setAlpha(128);
painter.setPen(QPen(lineColor, 1));
painter.drawLine(worldToWidget(from), worldToWidget(to));
};
m_sim->admin().forEach<ShipIdentityComponent, PositionComponent,
FactionComponent, AttackBehavior>(
[&](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& fac,
const AttackBehavior& attack)
{
if (!attack.currentTarget.has_value()) { return; }
const std::optional<QVector2D> targetPos =
entityPosition(*attack.currentTarget);
if (!targetPos.has_value()) { return; }
drawTargetLine(fac.isEnemy, pos.value, *targetPos);
});
m_sim->admin().forEach<ShipIdentityComponent, PositionComponent,
FactionComponent, RepairBehavior>(
[&](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& fac,
const RepairBehavior& repair)
{
if (!repair.currentTarget.has_value()) { return; }
const std::optional<QVector2D> targetPos =
entityPosition(*repair.currentTarget);
if (!targetPos.has_value()) { return; }
drawTargetLine(fac.isEnemy, pos.value, *targetPos);
});
m_sim->admin().forEach<ShipIdentityComponent, PositionComponent,
FactionComponent, SalvageScrapBehavior>(
[&](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& fac,
const SalvageScrapBehavior& salvage)
{
if (!salvage.scrapTarget.has_value()) { return; }
drawTargetLine(fac.isEnemy, pos.value, *salvage.scrapTarget);
});
}
void ArenaView::drawBeams(QPainter& painter)
{
painter.setPen(QPen(m_visuals->beams.color, m_visuals->beams.widthPx));
for (const ActiveBeam& beam : m_activeBeams)
{
const std::optional<QVector2D> shooterPos = entityPosition(beam.event.shooter);
const std::optional<QVector2D> targetPos = entityPosition(beam.event.target);
if (!shooterPos.has_value() || !targetPos.has_value()) { continue; }
QColor color = m_visuals->beams.weaponColor;
switch (beam.event.kind)
{
case BeamKind::Weapon: color = m_visuals->beams.weaponColor; break;
case BeamKind::Repair: color = m_visuals->beams.repairColor; break;
case BeamKind::Salvage: color = m_visuals->beams.salvageColor; break;
}
painter.setPen(QPen(color, m_visuals->beams.widthPx));
painter.drawLine(worldToWidget(*shooterPos),
worldToWidget(*targetPos + beam.targetOffset));
}

19
src/balancing/ArenaView.h
View File

@@ -10,7 +10,7 @@
#include <QVector2D>
#include "EventHandler.h"
#include "BeamFiredEvent.h"
#include "WeaponFiredEvent.h"
#include "entt/entity/entity.hpp"
#include "EntitySelectedEvent.h"
@@ -22,7 +22,7 @@ class ArenaSimulation;
class QPainter;
class ArenaView : public QOpenGLWidget,
public EventHandler<BeamFiredEvent>
public EventHandler<WeaponFiredEvent>
{
Q_OBJECT
@@ -39,21 +39,18 @@ public:
protected:
void paintGL() override;
void mousePressEvent(QMouseEvent* event) override;
void keyPressEvent(QKeyEvent* event) override;
private slots:
void onFrame();
private:
void handleEvent(std::shared_ptr<const BeamFiredEvent> event) override;
void handleEvent(std::shared_ptr<const WeaponFiredEvent> event) override;
void drawTiles(QPainter& painter);
void drawBuildings(QPainter& painter);
void drawStations(QPainter& painter);
void drawScrap(QPainter& painter);
void drawShips(QPainter& painter);
void drawDebugSensorRanges(QPainter& painter);
void drawDebugTargetLines(QPainter& painter);
void drawBeams(QPainter& painter);
float tilePx() const;
@@ -66,19 +63,19 @@ private:
struct ActiveBeam
{
BeamFiredEvent event;
WeaponFiredEvent event;
qint64 emittedWallMs;
QVector2D targetOffset;
};
// Beam lifetime in game ticks so beams freeze with the simulation when
// paused or slowed, instead of fading on wall-clock time (REQ-SHP-FIRING-BEAM).
static constexpr Tick kBeamLifetimeTicks = secondsToTicks(0.3);
static constexpr qint64 kBeamLifetimeMs = 300;
ArenaSimulation* m_sim;
const VisualsConfig* m_visuals;
TickDriver m_tickDriver;
QElapsedTimer m_frameTimer;
qint64 m_wallMs;
std::mt19937 m_rng;
double m_gameSpeedMultiplier;
double m_prevNonZeroSpeed;
@@ -89,6 +86,4 @@ private:
bool m_finishedEmitted;
std::optional<entt::entity> m_selectedEntity;
bool m_debugDraw;
};

44
src/balancing/ArenaWidget.cpp
View File

@@ -33,9 +33,6 @@ void ArenaWidget::buildLayout(const std::string& arenaName)
m_titleLabel->setFont(titleFont);
titleRow->addWidget(m_titleLabel);
m_durationLabel = new QLabel(this);
titleRow->addWidget(m_durationLabel);
titleRow->addStretch();
m_inspectButton = new QPushButton(tr("Inspect"), this);
@@ -64,10 +61,6 @@ void ArenaWidget::buildLayout(const std::string& arenaName)
headerFont.setBold(true);
m_team1Header->setFont(headerFont);
team1Layout->addWidget(m_team1Header);
m_team1Threat = new QLabel(this);
team1Layout->addWidget(m_team1Threat);
m_team1Ehp = new QLabel(this);
team1Layout->addWidget(m_team1Ehp);
m_team1Content = new QLabel(this);
team1Layout->addWidget(m_team1Content);
team1Layout->addStretch();
@@ -78,10 +71,6 @@ void ArenaWidget::buildLayout(const std::string& arenaName)
m_team2Header = new QLabel(this);
m_team2Header->setFont(headerFont);
team2Layout->addWidget(m_team2Header);
m_team2Threat = new QLabel(this);
team2Layout->addWidget(m_team2Threat);
m_team2Ehp = new QLabel(this);
team2Layout->addWidget(m_team2Ehp);
m_team2Content = new QLabel(this);
team2Layout->addWidget(m_team2Content);
team2Layout->addStretch();
@@ -106,29 +95,12 @@ void ArenaWidget::resetToGrey()
setStyleSheet("ArenaWidget { border: 2px solid #999999; padding: 8px; }");
}
ArenaWidget::State ArenaWidget::getState() const
{
if (m_wasFinished)
{
return State::Ended;
}
if (m_running)
{
return State::Running;
}
return State::NotStarted;
}
void ArenaWidget::updateStatus(const ArenaStatus& status)
{
m_lastStatus = status;
for (int ti = 0; ti < 2; ++ti)
{
const ArenaStatus::TeamStatus& team = status.teams[ti];
QLabel* header = (ti == 0) ? m_team1Header : m_team2Header;
QLabel* threat = (ti == 0) ? m_team1Threat : m_team2Threat;
QLabel* ehp = (ti == 0) ? m_team1Ehp : m_team2Ehp;
QLabel* content = (ti == 0) ? m_team1Content : m_team2Content;
if (status.finished && status.winnerTeam == ti)
@@ -140,9 +112,6 @@ void ArenaWidget::updateStatus(const ArenaStatus& status)
header->setText(QString::fromStdString(team.name));
}
threat->setText(tr("Threat: %1").arg(QString::number(team.threatLevel, 'f', 0)));
ehp->setText(tr("EHP: %1").arg(QString::fromStdString(team.ehpPercentText())));
QString lines;
for (const ArenaStatus::Entry& entry : team.entries)
{
@@ -150,22 +119,15 @@ void ArenaWidget::updateStatus(const ArenaStatus& status)
{
lines += "\n";
}
lines += QString("%1/%2 %3")
lines += QString("%1/%2 %3 L%4")
.arg(entry.surviving)
.arg(entry.total)
.arg(QString::fromStdString(entry.displayName));
if (entry.level.has_value())
{
lines += QString(" L%1").arg(entry.level.value());
}
.arg(QString::fromStdString(entry.displayName))
.arg(entry.level);
}
content->setText(lines);
}
m_durationLabel->setText(status.finished
? tr("Duration: %1 s").arg(QString::number(status.durationSeconds, 'f', 1))
: QString());
if (status.finished && !m_wasFinished)
{
m_wasFinished = true;

16
src/balancing/ArenaWidget.h
View File

@@ -14,35 +14,19 @@ class ArenaWidget : public QFrame
Q_OBJECT
public:
enum class State
{
NotStarted,
Running,
Ended
};
ArenaWidget(int arenaIndex, const std::string& arenaName, QWidget* parent = nullptr);
void updateStatus(const ArenaStatus& status);
void startSimulation();
void resetToGrey();
const ArenaStatus& getLastStatus() const { return m_lastStatus; }
State getState() const;
private:
void buildLayout(const std::string& arenaName);
int m_arenaIndex;
ArenaStatus m_lastStatus;
QLabel* m_titleLabel;
QLabel* m_durationLabel;
QLabel* m_team1Header;
QLabel* m_team2Header;
QLabel* m_team1Threat;
QLabel* m_team2Threat;
QLabel* m_team1Ehp;
QLabel* m_team2Ehp;
QLabel* m_team1Content;
QLabel* m_team2Content;
QPushButton* m_inspectButton;

2
src/balancing/BalancingConfig.cpp
View File

@@ -125,6 +125,8 @@ BalancingConfig loadBalancingConfig(const std::string& path)
ArenaShipEntry entry;
entry.schematicId = requireString((*shipTbl)["schematic"],
sPrefix + ".schematic");
entry.level = static_cast<int>(
requireInt((*shipTbl)["level"], sPrefix + ".level"));
entry.count = static_cast<int>(
requireInt((*shipTbl)["count"], sPrefix + ".count"));

1
src/balancing/BalancingConfig.h
View File

@@ -18,6 +18,7 @@ struct ArenaStationEntry
struct ArenaShipEntry
{
std::string schematicId;
int level;
int count;
std::optional<ShipLayoutConfig> layout;
};

115
src/balancing/BalancingWindow.cpp
View File

@@ -1,70 +1,13 @@
#include "BalancingWindow.h"
#include <algorithm>
#include <QFile>
#include <QHBoxLayout>
#include <QMessageBox>
#include <QTextStream>
#include <QVBoxLayout>
#include "ConfigLoader.h"
#include "InspectWindow.h"
#include "VisualsLoader.h"
namespace
{
// Escapes characters that would break a markdown table cell.
QString escapeCell(const QString& text)
{
QString escaped = text;
escaped.replace("|", "\\|");
return escaped;
}
QString stateText(ArenaWidget::State state)
{
switch (state)
{
case ArenaWidget::State::NotStarted:
return QStringLiteral("not started");
case ArenaWidget::State::Running:
return QStringLiteral("running");
case ArenaWidget::State::Ended:
return QStringLiteral("ended");
}
return QString();
}
// Team column header: "[WON] Name — threat N", matching the arena widget.
QString teamHeaderCell(const ArenaStatus& status, int teamIndex)
{
const ArenaStatus::TeamStatus& team = status.teams[teamIndex];
QString header = QString::fromStdString(team.name);
if (status.finished && status.winnerTeam == teamIndex)
{
header = QStringLiteral("[WON] ") + header;
}
header += QStringLiteral(" - threat %1").arg(QString::number(team.threatLevel, 'f', 0));
header += QStringLiteral(" - EHP %1").arg(QString::fromStdString(team.ehpPercentText()));
return escapeCell(header);
}
// Single entry line: "surviving/total DisplayName [L<level>]", matching the arena widget.
QString entryCell(const ArenaStatus::Entry& entry)
{
QString cell = QString("%1/%2 %3")
.arg(entry.surviving)
.arg(entry.total)
.arg(QString::fromStdString(entry.displayName));
if (entry.level.has_value())
{
cell += QStringLiteral(" L%1").arg(entry.level.value());
}
return escapeCell(cell);
}
}
BalancingWindow::BalancingWindow(const BalancingConfig& balancingConfig,
GameConfig gameConfig,
const std::string& configDir,
@@ -88,16 +31,13 @@ BalancingWindow::BalancingWindow(const BalancingConfig& balancingConfig,
QHBoxLayout* buttonRow = new QHBoxLayout();
m_reloadButton = new QPushButton(tr("Reload Config"), this);
m_startAllButton = new QPushButton(tr("Start All"), this);
m_logButton = new QPushButton(tr("Log"), this);
buttonRow->addWidget(m_reloadButton);
buttonRow->addWidget(m_startAllButton);
buttonRow->addWidget(m_logButton);
buttonRow->addStretch();
mainLayout->addLayout(buttonRow);
connect(m_reloadButton, &QPushButton::clicked, this, &BalancingWindow::reloadConfig);
connect(m_startAllButton, &QPushButton::clicked, this, &BalancingWindow::startAll);
connect(m_logButton, &QPushButton::clicked, this, &BalancingWindow::writeLog);
m_scrollArea = new QScrollArea(this);
m_scrollArea->setWidgetResizable(true);
@@ -315,7 +255,6 @@ void BalancingWindow::setMainControlsEnabled(bool enabled)
{
m_reloadButton->setEnabled(enabled);
m_startAllButton->setEnabled(enabled);
m_logButton->setEnabled(enabled);
for (ArenaEntry& entry : m_arenas)
{
for (QPushButton* btn : entry.widget->findChildren<QPushButton*>())
@@ -352,58 +291,4 @@ void BalancingWindow::updateButtons()
m_reloadButton->setEnabled(!anyRunning);
m_startAllButton->setEnabled(!allRunning);
m_logButton->setEnabled(true);
}
void BalancingWindow::writeLog()
{
QFile file(QStringLiteral("balancing_log.md"));
if (!file.open(QIODevice::WriteOnly | QIODevice::Truncate | QIODevice::Text))
{
QMessageBox::warning(this, tr("Log Failed"),
tr("Could not open balancing_log.md for writing."));
return;
}
QTextStream out(&file);
out.setCodec("UTF-8");
out << "# Balancing Log\n";
for (const ArenaEntry& entry : m_arenas)
{
const ArenaStatus& status = entry.widget->getLastStatus();
const ArenaWidget::State state = entry.widget->getState();
QString stateSuffix = stateText(state);
if (state == ArenaWidget::State::Ended)
{
stateSuffix += QStringLiteral(", %1 s")
.arg(QString::number(status.durationSeconds, 'f', 1));
}
out << "\n## Arena: " << QString::fromStdString(entry.config.name)
<< " (" << stateSuffix << ")\n\n";
out << "| " << teamHeaderCell(status, 0) << " | "
<< teamHeaderCell(status, 1) << " |\n";
out << "|---|---|\n";
const std::size_t rowCount = std::max(status.teams[0].entries.size(),
status.teams[1].entries.size());
for (std::size_t row = 0; row < rowCount; ++row)
{
QString leftCell;
if (row < status.teams[0].entries.size())
{
leftCell = entryCell(status.teams[0].entries[row]);
}
QString rightCell;
if (row < status.teams[1].entries.size())
{
rightCell = entryCell(status.teams[1].entries[row]);
}
out << "| " << leftCell << " | " << rightCell << " |\n";
}
}
}

2
src/balancing/BalancingWindow.h
View File

@@ -46,7 +46,6 @@ private slots:
void pollStatuses();
void reloadConfig();
void startAll();
void writeLog();
private:
void startArena(int index);
@@ -73,7 +72,6 @@ private:
unsigned int m_nextSeed;
QPushButton* m_reloadButton;
QPushButton* m_startAllButton;
QPushButton* m_logButton;
QScrollArea* m_scrollArea;
QTimer* m_pollTimer;

39
src/balancing/InspectWindow.cpp
View File

@@ -14,7 +14,6 @@
#include "HealthComponent.h"
#include "InspectWindowClosedEvent.h"
#include "ModuleOwnerComponent.h"
#include "SelectedBehaviorComponent.h"
#include "ShipIdentityComponent.h"
#include "ShipStatsCalculator.h"
#include "ShipStatsPanel.h"
@@ -53,9 +52,6 @@ InspectWindow::InspectWindow(ArenaSimulation* sim, const GameConfig* config,
nameLabel->setFont(nameFont);
headerLayout->addWidget(nameLabel);
m_durationLabel = new QLabel(header);
headerLayout->addWidget(m_durationLabel);
headerLayout->addStretch();
const char* labels[] = { "0x", "0.5x", "1x", "2x", "10x" };
@@ -95,10 +91,6 @@ InspectWindow::InspectWindow(ArenaSimulation* sim, const GameConfig* config,
headerFont.setBold(true);
m_team1Header->setFont(headerFont);
team1Layout->addWidget(m_team1Header);
m_team1Threat = new QLabel(infoPanel);
team1Layout->addWidget(m_team1Threat);
m_team1Ehp = new QLabel(infoPanel);
team1Layout->addWidget(m_team1Ehp);
m_team1Content = new QLabel(infoPanel);
team1Layout->addWidget(m_team1Content);
team1Layout->addStretch();
@@ -108,10 +100,6 @@ InspectWindow::InspectWindow(ArenaSimulation* sim, const GameConfig* config,
m_team2Header = new QLabel(infoPanel);
m_team2Header->setFont(headerFont);
team2Layout->addWidget(m_team2Header);
m_team2Threat = new QLabel(infoPanel);
team2Layout->addWidget(m_team2Threat);
m_team2Ehp = new QLabel(infoPanel);
team2Layout->addWidget(m_team2Ehp);
m_team2Content = new QLabel(infoPanel);
team2Layout->addWidget(m_team2Content);
team2Layout->addStretch();
@@ -206,16 +194,10 @@ void InspectWindow::pollStatus()
void InspectWindow::updateInfoPanel(const ArenaStatus& status)
{
m_durationLabel->setText(status.finished
? tr("Duration: %1 s").arg(QString::number(status.durationSeconds, 'f', 1))
: QString());
for (int ti = 0; ti < 2; ++ti)
{
const ArenaStatus::TeamStatus& team = status.teams[ti];
QLabel* header = (ti == 0) ? m_team1Header : m_team2Header;
QLabel* threat = (ti == 0) ? m_team1Threat : m_team2Threat;
QLabel* ehp = (ti == 0) ? m_team1Ehp : m_team2Ehp;
QLabel* content = (ti == 0) ? m_team1Content : m_team2Content;
if (status.finished && status.winnerTeam == ti)
@@ -227,9 +209,6 @@ void InspectWindow::updateInfoPanel(const ArenaStatus& status)
header->setText(QString::fromStdString(team.name));
}
threat->setText(tr("Threat: %1").arg(QString::number(team.threatLevel, 'f', 0)));
ehp->setText(tr("EHP: %1").arg(QString::fromStdString(team.ehpPercentText())));
QString lines;
for (const ArenaStatus::Entry& entry : team.entries)
{
@@ -237,14 +216,11 @@ void InspectWindow::updateInfoPanel(const ArenaStatus& status)
{
lines += "\n";
}
lines += QString("%1/%2 %3")
lines += QString("%1/%2 %3 L%4")
.arg(entry.surviving)
.arg(entry.total)
.arg(QString::fromStdString(entry.displayName));
if (entry.level.has_value())
{
lines += QString(" L%1").arg(entry.level.value());
}
.arg(QString::fromStdString(entry.displayName))
.arg(entry.level);
}
content->setText(lines);
}
@@ -273,14 +249,13 @@ void InspectWindow::handleEvent(std::shared_ptr<const EntitySelectedEvent> event
const ShipIdentityComponent& identity = admin.get<ShipIdentityComponent>(entity);
const HealthComponent& health = admin.get<HealthComponent>(entity);
m_entityTitleLabel->setText(tr("Ship: %1")
.arg(QString::fromStdString(identity.schematicId)));
m_entityTitleLabel->setText(tr("Ship: %1 (Lv %2)")
.arg(QString::fromStdString(identity.schematicId))
.arg(identity.level));
m_entityTitleLabel->show();
const ShipStats stats = buildShipStatsFromEntity(admin, entity);
m_entityStatsPanel->refreshFromLive(stats, health.hp);
m_entityStatsPanel->setBehavior(
admin.get<SelectedBehaviorComponent>(entity).winner);
m_entityStatsPanel->show();
m_stationStatsLabel->hide();
}
@@ -358,8 +333,6 @@ void InspectWindow::refreshEntityStats()
{
const ShipStats stats = buildShipStatsFromEntity(admin, entity);
m_entityStatsPanel->refreshFromLive(stats, health.hp);
m_entityStatsPanel->setBehavior(
admin.get<SelectedBehaviorComponent>(entity).winner);
}
else if (admin.hasAll<StationBodyComponent>(entity))
{

5
src/balancing/InspectWindow.h
View File

@@ -54,13 +54,8 @@ private:
ArenaView* m_arenaView;
std::vector<QPushButton*> m_speedButtons;
QLabel* m_durationLabel;
QLabel* m_team1Header;
QLabel* m_team2Header;
QLabel* m_team1Threat;
QLabel* m_team2Threat;
QLabel* m_team1Ehp;
QLabel* m_team2Ehp;
QLabel* m_team1Content;
QLabel* m_team2Content;
QTimer* m_pollTimer;

40
src/lib/config/BlueprintSerializer.cpp
View File

@@ -51,24 +51,6 @@ std::string serialize(const std::vector<Blueprint>& blueprints)
bldTbl.insert("offset_x", static_cast<int64_t>(b.offset.x()));
bldTbl.insert("offset_y", static_cast<int64_t>(b.offset.y()));
bldTbl.insert("recipe_id", b.recipeId);
if (!b.splitterFilterA.empty())
{
toml::array filterArr;
for (const ItemType& item : b.splitterFilterA)
{
filterArr.push_back(item.id);
}
bldTbl.insert("filter_a", std::move(filterArr));
}
if (!b.splitterFilterB.empty())
{
toml::array filterArr;
for (const ItemType& item : b.splitterFilterB)
{
filterArr.push_back(item.id);
}
bldTbl.insert("filter_b", std::move(filterArr));
}
if (b.shipLayout.has_value())
{
toml::array modArr;
@@ -156,28 +138,6 @@ std::vector<Blueprint> deserialize(const std::string& tomlContent)
bb.offset.setX(static_cast<int>((*bldTbl)["offset_x"].value_or(int64_t{0})));
bb.offset.setY(static_cast<int>((*bldTbl)["offset_y"].value_or(int64_t{0})));
bb.recipeId = (*bldTbl)["recipe_id"].value_or(std::string{});
const toml::array* filterAArr = (*bldTbl)["filter_a"].as_array();
if (filterAArr)
{
for (std::size_t k = 0; k < filterAArr->size(); ++k)
{
const std::optional<std::string> itemId =
(*filterAArr)[k].value<std::string>();
if (itemId) { bb.splitterFilterA.push_back(ItemType{*itemId}); }
}
}
const toml::array* filterBArr = (*bldTbl)["filter_b"].as_array();
if (filterBArr)
{
for (std::size_t k = 0; k < filterBArr->size(); ++k)
{
const std::optional<std::string> itemId =
(*filterBArr)[k].value<std::string>();
if (itemId) { bb.splitterFilterB.push_back(ItemType{*itemId}); }
}
}
const toml::array* modArr = (*bldTbl)["modules"].as_array();
if (modArr)
{

22
src/lib/config/BuildingsConfig.h
View File

@@ -1,6 +1,5 @@
#pragma once
#include <optional>
#include <string>
#include <vector>
@@ -19,30 +18,9 @@ struct BuildingDef
// Stored as raw strings here; parsing into per-cell tiles + output ports
// happens when buildings are placed, not at load time.
std::vector<std::string> surfaceMask;
// Output-buffer holding size for buildings without a recipe-driven buffer.
// Only the Salvage Bay sets this (REQ-BLD-SALVAGE-BAY).
std::optional<int> outputBufferCapacity;
// Optional hover-tooltip text for the build button (REQ-UI-BUILD-TOOLTIP).
std::optional<std::string> tooltip;
};
struct BuildingsConfig
{
std::vector<BuildingDef> buildings;
// Returns the definition for the given building type, or nullptr if the
// type has no entry in buildings.toml.
const BuildingDef* findBuildingDef(BuildingType type) const
{
for (const BuildingDef& def : buildings)
{
if (def.type == type)
{
return &def;
}
}
return nullptr;
}
};

197
src/lib/config/ConfigLoader.cpp
View File

@@ -4,7 +4,6 @@
#include <sstream>
#include <stdexcept>
#include <string>
#include <unordered_set>
#include <utility>
#include <vector>
@@ -265,32 +264,24 @@ WorldConfig ConfigLoader::loadWorld(const std::string& path)
cfg.refundPercentage = static_cast<int>(requireInt(tbl["world"]["refund_percentage"], file, "world.refund_percentage"));
cfg.startingBuildingBlocks = static_cast<int>(requireInt(tbl["world"]["starting_building_blocks"], file, "world.starting_building_blocks"));
cfg.scrapDespawnSeconds = requireDouble(tbl["world"]["scrap_despawn_seconds"], file, "world.scrap_despawn_seconds");
cfg.scrapPerThreat = requireDouble(tbl["world"]["scrap_per_threat"], file, "world.scrap_per_threat");
cfg.tileSize_m = requireDouble(tbl["world"]["tile_size_m"], file, "world.tile_size_m");
cfg.beltSpeed_tps = requireDouble(tbl["world"]["belt_speed_mps"], file, "world.belt_speed_mps") / cfg.tileSize_m;
cfg.tunnelMaxDistance_tiles = static_cast<int>(requireInt(tbl["world"]["tunnel_max_distance_tiles"], file, "world.tunnel_max_distance_tiles"));
cfg.departureIntervalSeconds = requireDouble(tbl["world"]["departure_interval_seconds"], file, "world.departure_interval_seconds");
cfg.orbitFactor = requireDouble(tbl["world"]["orbit_factor"], file, "world.orbit_factor");
cfg.rallyOrbitRadius_tiles = requireDouble(tbl["world"]["rally_orbit_radius_tiles"], file, "world.rally_orbit_radius_tiles");
if (const std::optional<std::string> tip =
tbl["world"]["building_blocks_tooltip"].value<std::string>())
{
cfg.buildingBlocksTooltip = *tip;
}
cfg.regions.asteroidWidth_tiles = static_cast<int>(requireInt(tbl["regions"]["asteroid_width_tiles"], file, "regions.asteroid_width_tiles"));
cfg.regions.playerBufferWidth_tiles = static_cast<int>(requireInt(tbl["regions"]["player_buffer_width_tiles"], file, "regions.player_buffer_width_tiles"));
cfg.regions.contestZoneWidth_tiles = static_cast<int>(requireInt(tbl["regions"]["contest_zone_width_tiles"], file, "regions.contest_zone_width_tiles"));
cfg.regions.enemyBufferWidth_tiles = static_cast<int>(requireInt(tbl["regions"]["enemy_buffer_width_tiles"], file, "regions.enemy_buffer_width_tiles"));
cfg.expansion.columnsPerExpansion_tiles = static_cast<int>(requireInt(tbl["expansion"]["columns_per_expansion_tiles"], file, "expansion.columns_per_expansion_tiles"));
cfg.expansion.costBuildingBlocksFormula = requireFormula(tbl["expansion"]["cost_building_blocks_formula"], file, "expansion.cost_building_blocks_formula");
cfg.expansion.columnsPerExpansion_tiles = static_cast<int>(requireInt(tbl["expansion"]["columns_per_expansion_tiles"], file, "expansion.columns_per_expansion_tiles"));
cfg.expansion.costBuildingBlocks = static_cast<int>(requireInt(tbl["expansion"]["cost_building_blocks"], file, "expansion.cost_building_blocks"));
cfg.push.pushExpandColumns_tiles = static_cast<int>(requireInt(tbl["push"]["push_expand_columns_tiles"], file, "push.push_expand_columns_tiles"));
cfg.push.bossAdvanceSeconds = requireDouble(tbl["push"]["boss_advance_seconds"], file, "push.boss_advance_seconds");
cfg.waves.threatRateFormula = requireFormula(tbl["waves"]["threat_rate_formula"], file, "waves.threat_rate_formula");
cfg.waves.shipLevelFormula = requireFormula(tbl["waves"]["ship_level_formula"], file, "waves.ship_level_formula");
cfg.waves.gapMinSeconds = requireDouble(tbl["waves"]["gap_min_seconds"], file, "waves.gap_min_seconds");
cfg.waves.gapMaxSeconds = requireDouble(tbl["waves"]["gap_max_seconds"], file, "waves.gap_max_seconds");
cfg.waves.spawnDurationSeconds = requireDouble(tbl["waves"]["spawn_duration_seconds"], file, "waves.spawn_duration_seconds");
@@ -304,17 +295,6 @@ WorldConfig ConfigLoader::loadWorld(const std::string& path)
throw makeError(file, "waves", "gap_min_seconds > gap_max_seconds");
}
cfg.targeting.targetScoreFormula = requireFormula(tbl["targeting"]["target_score_formula"], file, "targeting.target_score_formula");
cfg.targeting.overclaimPenaltyFormula = requireFormula(tbl["targeting"]["overclaim_penalty_formula"], file, "targeting.overclaim_penalty_formula");
cfg.targeting.hysteresis = requireDouble(tbl["targeting"]["target_hysteresis"], file, "targeting.target_hysteresis");
cfg.artifacts.artifactChanceFormula = requireFormula(tbl["artifacts"]["artifact_chance_formula"], file, "artifacts.artifact_chance_formula");
cfg.artifacts.artifactWinCount = static_cast<int>(requireInt(tbl["artifacts"]["artifact_win_count"], file, "artifacts.artifact_win_count"));
cfg.scroll.panSpeedSlow_tps = requireDouble(tbl["scroll"]["pan_speed_slow_tiles_per_second"], file, "scroll.pan_speed_slow_tiles_per_second");
cfg.scroll.panSpeedFast_tps = requireDouble(tbl["scroll"]["pan_speed_fast_tiles_per_second"], file, "scroll.pan_speed_fast_tiles_per_second");
cfg.scroll.panRampBandWidth_tiles = static_cast<int>(requireInt(tbl["scroll"]["pan_ramp_band_width_tiles"], file, "scroll.pan_ramp_band_width_tiles"));
return cfg;
}
@@ -343,17 +323,6 @@ BuildingsConfig ConfigLoader::loadBuildings(const std::string& path)
def.constructionTimeSeconds = requireDouble(mt["construction_time_seconds"], file, elemPath + ".construction_time_seconds");
def.surfaceMask = requireStringArray(mt["surface_mask"], file, elemPath + ".surface_mask");
if (mt.contains("output_buffer_capacity"))
{
def.outputBufferCapacity = static_cast<int>(
requireInt(mt["output_buffer_capacity"], file, elemPath + ".output_buffer_capacity"));
}
if (mt.contains("tooltip"))
{
def.tooltip = requireString(mt["tooltip"], file, elemPath + ".tooltip");
}
const std::optional<BuildingType> parsedType = parseBuildingType(def.id);
if (!parsedType)
{
@@ -405,11 +374,6 @@ RecipesConfig ConfigLoader::loadRecipes(const std::string& path)
{
def.unlockAtStationLevel = static_cast<int>(*level);
}
if (mt.contains("unlock_requires"))
{
def.unlockRequires = requireStringArray(mt["unlock_requires"], file,
elemPath + ".unlock_requires");
}
}
// inputs may be omitted (e.g. miner recipes). An empty array is fine.
@@ -449,10 +413,6 @@ ShipsConfig ConfigLoader::loadShips(const std::string& path)
ShipDef def;
def.id = requireString(mt["id"], file, elemPath + ".id");
def.unlockAtStationLevel = static_cast<int>(requireInt(mt["unlock_at_station_level"], file, elemPath + ".unlock_at_station_level"));
if (mt.contains("unlock_requires"))
{
def.unlockRequires = requireStringArray(mt["unlock_requires"], file, elemPath + ".unlock_requires");
}
def.layout = requireStringArray(mt["layout"], file, elemPath + ".layout");
// Schematic
@@ -463,6 +423,8 @@ ShipsConfig ConfigLoader::loadShips(const std::string& path)
const toml::array& materials = requireArray(bpMt["materials"], file, bpPath + ".materials");
def.schematic.materials = parseIngredients(materials, file, bpPath + ".materials");
def.schematic.playerProductionLevel = static_cast<int>(requireInt(
bpMt["player_production_level"], file, bpPath + ".player_production_level"));
def.schematic.productionTimeSeconds = requireDouble(
bpMt["production_time_seconds"], file, bpPath + ".production_time_seconds");
}
@@ -472,7 +434,7 @@ ShipsConfig ConfigLoader::loadShips(const std::string& path)
const std::string hPath = elemPath + ".health";
const toml::table& hTable = requireTable(mt["health"], file, hPath);
toml::table& hMt = const_cast<toml::table&>(hTable);
def.health.hp = static_cast<float>(requireDouble(hMt["hp"], file, hPath + ".hp"));
def.health.hpFormula = requireFormula(hMt["hp_formula"], file, hPath + ".hp_formula");
}
// Movement
@@ -480,11 +442,11 @@ ShipsConfig ConfigLoader::loadShips(const std::string& path)
const std::string mPath = elemPath + ".movement";
const toml::table& mTable = requireTable(mt["movement"], file, mPath);
toml::table& mMt = const_cast<toml::table&>(mTable);
def.movement.speed_mps = static_cast<float>(requireDouble(mMt["speed_mps"], file, mPath + ".speed_mps"));
def.movement.mainAcceleration_mpss = static_cast<float>(requireDouble(mMt["main_acceleration_mpss"], file, mPath + ".main_acceleration_mpss"));
def.movement.maneuveringAcceleration_mpss = static_cast<float>(requireDouble(mMt["maneuvering_acceleration_mpss"], file, mPath + ".maneuvering_acceleration_mpss"));
def.movement.angularAcceleration_radpss = static_cast<float>(requireDouble(mMt["angular_acceleration_radpss"], file, mPath + ".angular_acceleration_radpss"));
def.movement.maxRotationSpeed_radps = static_cast<float>(requireDouble(mMt["max_rotation_speed_radps"], file, mPath + ".max_rotation_speed_radps"));
def.movement.speedFormula = requireFormula(mMt["speed_mps_formula"], file, mPath + ".speed_mps_formula");
def.movement.mainAccelerationFormula = requireFormula(mMt["main_acceleration_mpss_formula"], file, mPath + ".main_acceleration_mpss_formula");
def.movement.maneuveringAccelerationFormula = requireFormula(mMt["maneuvering_acceleration_mpss_formula"], file, mPath + ".maneuvering_acceleration_mpss_formula");
def.movement.angularAccelerationFormula = requireFormula(mMt["angular_acceleration_radpss_formula"], file, mPath + ".angular_acceleration_radpss_formula");
def.movement.maxRotationSpeedFormula = requireFormula(mMt["max_rotation_speed_radps_formula"], file, mPath + ".max_rotation_speed_radps_formula");
}
// Sensor
@@ -492,7 +454,15 @@ ShipsConfig ConfigLoader::loadShips(const std::string& path)
const std::string snsPath = elemPath + ".sensor";
const toml::table& snsTable = requireTable(mt["sensor"], file, snsPath);
toml::table& snsMt = const_cast<toml::table&>(snsTable);
def.sensor.sensorRange_m = static_cast<float>(requireDouble(snsMt["sensor_range_m"], file, snsPath + ".sensor_range_m"));
def.sensor.sensorRangeFormula = requireFormula(snsMt["sensor_range_m_formula"], file, snsPath + ".sensor_range_m_formula");
}
// Loot
{
const std::string lPath = elemPath + ".loot";
const toml::table& lTable = requireTable(mt["loot"], file, lPath);
toml::table& lMt = const_cast<toml::table&>(lTable);
def.loot.scrapDrop = static_cast<int>(requireInt(lMt["scrap_drop"], file, lPath + ".scrap_drop"));
}
// Optional: default_modules (REQ-WAV-DEFAULT-MODULES)
@@ -570,8 +540,8 @@ static const StatEntry kKnownStats[] = {
{"weapon", "attack_range", "_m"},
{"weapon", "attack_rate", "_hz"},
{"salvage", "collection_range", "_m"},
{"salvage", "cargo_capacity", ""},
{"salvage", "collection_rate", "_hz"},
{"cargo", "cargo_capacity", ""},
{"repair", "repair_rate", "_hz"},
{"repair", "repair_range", "_m"},
};
@@ -604,21 +574,14 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
def.id = requireString(mt["id"], file, elemPath + ".id");
def.unlockAtStationLevel = static_cast<int>(
mt["unlock_at_station_level"].value_or<int64_t>(-1));
if (mt.contains("unlock_requires"))
{
def.unlockRequires = requireStringArray(mt["unlock_requires"], file, elemPath + ".unlock_requires");
}
def.surfaceMask = requireStringArray(mt["surface_mask"], file, elemPath + ".surface_mask");
def.playerProductionLevel = static_cast<int>(requireInt(
mt["player_production_level"], file, elemPath + ".player_production_level"));
def.productionTimeSeconds = requireDouble(
mt["production_time_seconds"], file, elemPath + ".production_time_seconds");
def.fillColor = requireString(mt["fill_color"], file, elemPath + ".fill_color");
def.glyph = requireString(mt["glyph"], file, elemPath + ".glyph");
if (mt.contains("tooltip"))
{
def.tooltip = requireString(mt["tooltip"], file, elemPath + ".tooltip");
}
// Materials
{
const toml::array& materials = requireArray(mt["materials"], file, elemPath + ".materials");
@@ -636,15 +599,15 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
elemPath + "." + se.category);
toml::table& catMt = const_cast<toml::table&>(catTable);
const std::string addedKey = std::string("added_") + se.stat + se.addedKeySuffix;
const std::string multipliedKey = std::string("multiplied_") + se.stat + se.addedKeySuffix;
const std::string addedKey = std::string("added_") + se.stat + se.addedKeySuffix + "_formula";
const std::string multipliedKey = std::string("multiplied_") + se.stat + se.addedKeySuffix + "_formula";
if (catMt.contains(addedKey))
{
ModuleStatModifier mod;
mod.stat = se.stat;
mod.modifierType = "additive";
mod.value = requireDouble(catMt[addedKey], file,
mod.formula = requireFormula(catMt[addedKey], file,
elemPath + "." + se.category + "." + addedKey);
def.statModifiers.push_back(std::move(mod));
}
@@ -654,7 +617,7 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
ModuleStatModifier mod;
mod.stat = se.stat;
mod.modifierType = "multiplicative";
mod.value = requireDouble(catMt[multipliedKey], file,
mod.formula = requireFormula(catMt[multipliedKey], file,
elemPath + "." + se.category + "." + multipliedKey);
def.statModifiers.push_back(std::move(mod));
}
@@ -666,16 +629,16 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
const std::string wPath = elemPath + ".weapon";
const toml::table& wTable = requireTable(mt["weapon"], file, wPath);
toml::table& wMt = const_cast<toml::table&>(wTable);
if (wMt.contains("damage") || wMt.contains("attack_range_m")
|| wMt.contains("attack_rate_hz"))
if (wMt.contains("damage_formula") || wMt.contains("attack_range_m_formula")
|| wMt.contains("attack_rate_hz_formula"))
{
ModuleWeaponCapability cap;
cap.damage = static_cast<float>(requireDouble(wMt["damage"],
file, wPath + ".damage"));
cap.attackRange_m = static_cast<float>(requireDouble(wMt["attack_range_m"],
file, wPath + ".attack_range_m"));
cap.attackRate_hz = static_cast<float>(requireDouble(wMt["attack_rate_hz"],
file, wPath + ".attack_rate_hz"));
cap.damageFormula = requireFormula(wMt["damage_formula"],
file, wPath + ".damage_formula");
cap.attackRangeFormula = requireFormula(wMt["attack_range_m_formula"],
file, wPath + ".attack_range_m_formula");
cap.attackRateFormula = requireFormula(wMt["attack_rate_hz_formula"],
file, wPath + ".attack_rate_hz_formula");
def.weaponCapability = std::move(cap);
}
}
@@ -686,16 +649,16 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
const std::string sPath = elemPath + ".salvage";
const toml::table& sTable = requireTable(mt["salvage"], file, sPath);
toml::table& sMt = const_cast<toml::table&>(sTable);
if (sMt.contains("collection_range_m") || sMt.contains("cargo_capacity")
|| sMt.contains("collection_rate_hz"))
if (sMt.contains("collection_range_m_formula") || sMt.contains("cargo_capacity_formula")
|| sMt.contains("collection_rate_hz_formula"))
{
ModuleSalvageCapability cap;
cap.collectionRange_m = static_cast<float>(requireDouble(sMt["collection_range_m"],
file, sPath + ".collection_range_m"));
cap.cargoCapacity = static_cast<float>(requireDouble(sMt["cargo_capacity"],
file, sPath + ".cargo_capacity"));
cap.collectionRate_hz = static_cast<float>(requireDouble(sMt["collection_rate_hz"],
file, sPath + ".collection_rate_hz"));
cap.collectionRangeFormula = requireFormula(sMt["collection_range_m_formula"],
file, sPath + ".collection_range_m_formula");
cap.cargoCapacityFormula = requireFormula(sMt["cargo_capacity_formula"],
file, sPath + ".cargo_capacity_formula");
cap.collectionRateFormula = requireFormula(sMt["collection_rate_hz_formula"],
file, sPath + ".collection_rate_hz_formula");
def.salvageCapability = std::move(cap);
}
}
@@ -706,15 +669,13 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
const std::string rPath = elemPath + ".repair";
const toml::table& rTable = requireTable(mt["repair"], file, rPath);
toml::table& rMt = const_cast<toml::table&>(rTable);
if (rMt.contains("repair_rate_hz") || rMt.contains("repair_range_m"))
if (rMt.contains("repair_rate_hz_formula") || rMt.contains("repair_range_m_formula"))
{
ModuleRepairCapability cap;
cap.repairRate_hz = static_cast<float>(requireDouble(rMt["repair_rate_hz"],
file, rPath + ".repair_rate_hz"));
cap.repairAmountHp = static_cast<float>(requireDouble(rMt["repair_amount_hp"],
file, rPath + ".repair_amount_hp"));
cap.repairRange_m = static_cast<float>(requireDouble(rMt["repair_range_m"],
file, rPath + ".repair_range_m"));
cap.repairRateFormula = requireFormula(rMt["repair_rate_hz_formula"],
file, rPath + ".repair_rate_hz_formula");
cap.repairRangeFormula = requireFormula(rMt["repair_range_m_formula"],
file, rPath + ".repair_range_m_formula");
def.repairCapability = std::move(cap);
}
}
@@ -725,67 +686,6 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
return cfg;
}
namespace
{
// Throws if any id in requiredIds is not a valid explicitly-unlockable schematic.
void checkUnlockRequires(const std::vector<std::string>& requiredIds,
const std::unordered_set<std::string>& schematicIds,
const std::string& file,
const std::string& path)
{
for (const std::string& requiredId : requiredIds)
{
if (schematicIds.count(requiredId) == 0)
{
throw makeError(file, path,
"references unknown schematic '" + requiredId + "'");
}
}
}
// Validates that every id listed in an `unlock_requires` (REQ-LOCK-PREREQ)
// resolves to an explicitly-unlockable schematic: a ship, a module, or an
// assembler recipe that carries `unlock_at_station_level` (a recipe schematic,
// per REQ-LOCK-EXPLICIT). An unresolved id is a config error surfaced at load.
void validateUnlockRequires(const GameConfig& cfg)
{
std::unordered_set<std::string> schematicIds;
for (const ShipDef& def : cfg.ships.ships)
{
schematicIds.insert(def.id);
}
for (const ModuleDef& def : cfg.modules.modules)
{
schematicIds.insert(def.id);
}
for (const RecipeDef& def : cfg.recipes.recipes)
{
if (def.building == BuildingType::Assembler && def.unlockAtStationLevel.has_value())
{
schematicIds.insert(def.id);
}
}
for (const ShipDef& def : cfg.ships.ships)
{
checkUnlockRequires(def.unlockRequires, schematicIds, "ships.toml",
"ship '" + def.id + "'.unlock_requires");
}
for (const ModuleDef& def : cfg.modules.modules)
{
checkUnlockRequires(def.unlockRequires, schematicIds, "modules.toml",
"module '" + def.id + "'.unlock_requires");
}
for (const RecipeDef& def : cfg.recipes.recipes)
{
checkUnlockRequires(def.unlockRequires, schematicIds, "recipes.toml",
"recipe '" + def.id + "'.unlock_requires");
}
}
} // namespace
GameConfig ConfigLoader::loadFromDirectory(const std::string& configDir)
{
GameConfig cfg;
@@ -795,7 +695,6 @@ GameConfig ConfigLoader::loadFromDirectory(const std::string& configDir)
cfg.ships = loadShips(configDir + "/ships.toml");
cfg.stations = loadStations(configDir + "/stations.toml");
cfg.modules = loadModules(configDir + "/modules.toml");
validateUnlockRequires(cfg);
cfg.threatCosts = computeThreatCostTable(cfg);
return cfg;
}

16
src/lib/config/Formula.cpp
View File

@@ -4,14 +4,6 @@
#include "tinyexpr.h"
namespace
{
// tinyexpr has no built-in min/max; expose them so config formulas can
// clamp (e.g. a floored overclaim penalty "max(0.5, 1 - 0.1*x)").
double formulaMin(double a, double b) { return a < b ? a : b; }
double formulaMax(double a, double b) { return a > b ? a : b; }
}
Formula::Formula(Formula&& other) noexcept
: m_source(std::move(other.m_source))
, m_x(std::move(other.m_x))
@@ -45,14 +37,11 @@ Formula Formula::compile(const std::string& source)
result.m_x = std::make_unique<double>(0.0);
const te_variable variables[] = {
{ "x", result.m_x.get(), TE_VARIABLE, nullptr },
{ "min", reinterpret_cast<const void*>(&formulaMin), TE_FUNCTION2 | TE_FLAG_PURE, nullptr },
{ "max", reinterpret_cast<const void*>(&formulaMax), TE_FUNCTION2 | TE_FLAG_PURE, nullptr },
{ "x", result.m_x.get(), 0, nullptr },
};
int errorPos = 0;
const int variableCount = static_cast<int>(sizeof(variables) / sizeof(variables[0]));
result.m_expr = te_compile(result.m_source.c_str(), variables, variableCount, &errorPos);
result.m_expr = te_compile(result.m_source.c_str(), variables, 1, &errorPos);
if (result.m_expr == nullptr)
{
@@ -77,4 +66,3 @@ double Formula::evaluate(double x) const
*m_x = x;
return te_eval(m_expr);
}

28
src/lib/config/ModulesConfig.h
View File

@@ -4,6 +4,7 @@
#include <string>
#include <vector>
#include "Formula.h"
#include "RecipesConfig.h"
// A single stat modifier contributed by a module instance.
@@ -12,40 +13,37 @@ struct ModuleStatModifier
{
std::string stat; // e.g. "hp", "speed", "sensor_range"
std::string modifierType; // "additive" or "multiplicative"
double value;
Formula formula;
};
// Capability sections — present when the module grants that capability.
struct ModuleWeaponCapability
{
float damage;
float attackRange_m;
float attackRate_hz;
Formula damageFormula;
Formula attackRangeFormula;
Formula attackRateFormula;
};
struct ModuleSalvageCapability
{
float collectionRange_m;
float cargoCapacity;
float collectionRate_hz;
Formula collectionRangeFormula;
Formula cargoCapacityFormula;
Formula collectionRateFormula;
};
struct ModuleRepairCapability
{
float repairRate_hz; // repair cycles per second
float repairAmountHp; // HP restored per cycle
float repairRange_m;
Formula repairRateFormula;
Formula repairRangeFormula;
};
struct ModuleDef
{
std::string id;
int unlockAtStationLevel;
// Prerequisite schematic ids that must be explicitly unlocked before this
// schematic can enter the drop pool (REQ-LOCK-PREREQ). Empty = none.
std::vector<std::string> unlockRequires;
std::vector<std::string> surfaceMask;
std::vector<RecipeIngredient> materials;
int playerProductionLevel;
double productionTimeSeconds;
std::string fillColor;
std::string glyph;
@@ -54,10 +52,6 @@ struct ModuleDef
std::optional<ModuleWeaponCapability> weaponCapability;
std::optional<ModuleSalvageCapability> salvageCapability;
std::optional<ModuleRepairCapability> repairCapability;
// Optional hover-tooltip text for the module selection button
// (REQ-MOD-UI-MODULE-TOOLTIP).
std::optional<std::string> tooltip;
};
struct ModulesConfig

4
src/lib/config/RecipesConfig.h
View File

@@ -36,10 +36,6 @@ struct RecipeDef
// at game start. >= 0 = locked; schematic enters drop pool at that station
// level once the output item is implicitly unlocked (REQ-LOCK-EXPLICIT).
std::optional<int> unlockAtStationLevel;
// Assembler recipe schematics only. Prerequisite schematic ids that must be
// explicitly unlocked before this schematic can enter the drop pool
// (REQ-LOCK-PREREQ). Empty = none.
std::vector<std::string> unlockRequires;
};
struct RecipesConfig

29
src/lib/config/ShipsConfig.h
View File

@@ -3,48 +3,55 @@
#include <string>
#include <vector>
#include "Formula.h"
#include "RecipesConfig.h" // for RecipeIngredient
#include "ShipLayout.h" // for PlacedModule
// Build materials and base production time (REQ-BLD-SHIPYARD, REQ-DEF-SCHEMATIC-DROP).
// Build materials and initial per-schematic production level
// (REQ-BLD-SHIPYARD, REQ-DEF-SCHEMATIC-DROP).
struct ShipSchematic
{
std::vector<RecipeIngredient> materials;
int playerProductionLevel;
double productionTimeSeconds;
};
struct ShipHealth
{
float hp; // REQ-SHP-STATS
Formula hpFormula; // REQ-SHP-STATS
};
struct ShipMovement
{
float speed_mps; // max linear speed cap, m/s (REQ-SHP-STATS, REQ-SHP-MOVEMENT)
float mainAcceleration_mpss; // forward acceleration, m/s²
float maneuveringAcceleration_mpss;// omnidirectional acceleration, m/s²
float angularAcceleration_radpss; // angular acceleration, rad/s²
float maxRotationSpeed_radps; // angular velocity cap, rad/s
Formula speedFormula; // max linear speed cap, tiles/s (REQ-SHP-STATS, REQ-SHP-MOVEMENT)
Formula mainAccelerationFormula; // forward acceleration, tiles/s²
Formula maneuveringAccelerationFormula;// omnidirectional acceleration, tiles/s²
Formula angularAccelerationFormula; // angular acceleration, rad/s²
Formula maxRotationSpeedFormula; // angular velocity cap, rad/s
};
struct ShipSensor
{
float sensorRange_m; // REQ-SHP-SENSOR, REQ-SHP-STATS
Formula sensorRangeFormula; // REQ-SHP-SENSOR, REQ-SHP-STATS
};
// Scrap dropped on destruction (REQ-RES-SCRAP-DROP).
struct ShipLoot
{
int scrapDrop;
};
struct ShipDef
{
std::string id;
int unlockAtStationLevel;
// Prerequisite schematic ids that must be explicitly unlocked before this
// schematic can enter the drop pool (REQ-LOCK-PREREQ). Empty = none.
std::vector<std::string> unlockRequires;
std::vector<std::string> layout;
ShipSchematic schematic;
ShipHealth health;
ShipMovement movement;
ShipSensor sensor;
ShipLoot loot;
// Module layout used for enemy wave ships (REQ-WAV-DEFAULT-MODULES).
std::vector<PlacedModule> defaultModules;

41
src/lib/config/WorldConfig.h
View File

@@ -1,8 +1,5 @@
#pragma once
#include <optional>
#include <string>
#include "Formula.h"
// Region widths are in tiles (REQ-GW-REGIONS).
@@ -17,8 +14,8 @@ struct WorldRegions
// Asteroid expansion (REQ-EXP-UNLOCK, REQ-EXP-COST).
struct WorldExpansion
{
int columnsPerExpansion_tiles;
Formula costBuildingBlocksFormula; // cost in building blocks; x = expansions already purchased
int columnsPerExpansion_tiles;
int costBuildingBlocks;
};
// Push effects (REQ-PSH-*, REQ-WAV-BOSS-ADVANCE).
@@ -32,6 +29,7 @@ struct WorldPush
struct WorldWaves
{
Formula threatRateFormula; // threat/s as a function of boss wave counter x
Formula shipLevelFormula; // enemy ship level as a function of boss wave counter x
double gapMinSeconds;
double gapMaxSeconds;
double spawnDurationSeconds;
@@ -41,52 +39,19 @@ struct WorldWaves
double bossQuietAfterSeconds; // suppress normal waves this long after boss (REQ-WAV-QUIET)
};
// Ship target selection (claim-aware scoring).
struct WorldTargeting
{
Formula targetScoreFormula; // x = distance / max weapon range; higher = better
Formula overclaimPenaltyFormula; // x = competing claim count; factor in [0,1]
double hysteresis; // fractional margin a challenger must beat the current target by
};
// Artifact win condition (REQ-WIN-ARTIFACT-COUNT, REQ-WIN-SCREEN).
struct WorldArtifacts
{
Formula artifactChanceFormula; // x = station level, result clamped to [0,1]
int artifactWinCount;
};
// View pan speed (REQ-UI-SCROLL-SPEED). Presentation-only; the simulation ignores these.
struct WorldScroll
{
double panSpeedSlow_tps; // tiles/s, used outside the contest zone
double panSpeedFast_tps; // tiles/s, used inside the contest zone
int panRampBandWidth_tiles; // full width of the ramp band straddling each contest-zone boundary
};
struct WorldConfig
{
int heightTiles; // REQ-GW-HEIGHT
int refundPercentage; // REQ-BLD-DEMOLISH
int startingBuildingBlocks; // REQ-HQ-STARTING-BLOCKS
double scrapDespawnSeconds; // REQ-RES-SCRAP-DROP
double scrapPerThreat; // REQ-RES-SCRAP-DROP, REQ-THREAT-SCRAP (scrap dropped per unit threat)
double tileSize_m; // metres per tile (REQ-GW-TILE-SIZE)
double beltSpeed_tps; // REQ-GW-BELT-SPEED (tiles/s, converted from m/s in config)
int tunnelMaxDistance_tiles; // REQ-BLD-TUNNEL-PAIR
double departureIntervalSeconds; // REQ-SHP-RALLY
double orbitFactor; // REQ-SHP-ORBIT (multiplies tool range for orbit radius)
double rallyOrbitRadius_tiles; // REQ-SHP-ORBIT (fixed orbit radius around the rally point)
// Optional hover-tooltip for the header building blocks stock display
// (REQ-UI-BLOCKS-TOOLTIP). Presentation-only; the simulation ignores it.
std::optional<std::string> buildingBlocksTooltip;
WorldRegions regions;
WorldExpansion expansion;
WorldPush push;
WorldWaves waves;
WorldTargeting targeting;
WorldArtifacts artifacts;
WorldScroll scroll;
};

6
src/lib/core/Blueprint.h
View File

@@ -8,7 +8,6 @@
#include <QString>
#include "BuildingType.h"
#include "ItemType.h"
#include "Rotation.h"
#include "ShipLayout.h"
@@ -19,11 +18,6 @@ struct BlueprintBuilding
QPoint offset; // tile offset from bounding-box center (floor for even sizes)
std::string recipeId; // empty = none selected
std::optional<ShipLayoutConfig> shipLayout;
// Splitter output filters captured at blueprint creation (REQ-UI-BLUEPRINT-STORAGE).
// Empty = accept all. Re-applied to the placed splitter site (REQ-UI-BLUEPRINT-PLACE).
std::vector<ItemType> splitterFilterA;
std::vector<ItemType> splitterFilterB;
};
struct Blueprint

4
src/lib/core/EntityAdmin.cpp
View File

@@ -42,7 +42,7 @@ entt::entity EntityAdmin::spawnShip(QVector2D position, float hp, float maxHp,
float maxSpeed_tpt, float mainAcceleration_tptt,
float maneuveringAcceleration_tptt, float maxAngularAcceleration_rptt,
float maxRotationSpeed_rpt, float sensorRange_tiles,
const std::string& schematicId, bool isEnemy)
int level, const std::string& schematicId, bool isEnemy)
{
entt::entity entity = createEntity();
add<PositionComponent>(entity, PositionComponent{position});
@@ -61,7 +61,7 @@ entt::entity EntityAdmin::spawnShip(QVector2D position, float hp, float maxHp,
0.0f // angularAcceleration_rptt
});
add<SensorRangeComponent>(entity, SensorRangeComponent{sensorRange_tiles});
add<ShipIdentityComponent>(entity, ShipIdentityComponent{schematicId});
add<ShipIdentityComponent>(entity, ShipIdentityComponent{level, schematicId});
add<MovementIntentComponent>(entity, MovementIntentComponent{0, QVector2D(0.0f, 0.0f)});
return entity;
}

2
src/lib/core/EntityAdmin.h
View File

@@ -56,7 +56,7 @@ public:
float maxSpeed_tpt, float mainAcceleration_tptt,
float maneuveringAcceleration_tptt, float maxAngularAcceleration_rptt,
float maxRotationSpeed_rpt, float sensorRange_tiles,
const std::string& schematicId, bool isEnemy);
int level, const std::string& schematicId, bool isEnemy);
entt::entity spawnStation(QPoint anchor, QSize footprint,
const std::vector<QPoint>& bodyCells,

13
src/lib/core/SchematicChoiceOption.h
View File

@@ -7,8 +7,7 @@ enum class SchematicType
{
Ship,
Module,
Recipe,
Artifact
Recipe
};
// One option presented to the player in the schematic choice dialog
@@ -19,9 +18,11 @@ struct SchematicChoiceOption
std::string schematicId;
SchematicType type;
std::string displayName;
bool isNewUnlock;
int targetLevel;
// Ids of miner/assembler recipes that would newly become implicitly
// unlocked (REQ-LOCK-IMPLICIT) if this option is selected. Sorted
// alphabetically by display name; empty if none.
std::vector<std::string> newlyUnlockedRecipeIds;
// Display names of items produced by recipes that would newly become
// implicitly unlocked (REQ-LOCK-IMPLICIT) if this option is selected.
// Deduplicated and sorted alphabetically; empty if none.
std::vector<std::string> newlyUnlockedItemNames;
};

6
src/lib/core/Tick.h
View File

@@ -8,12 +8,6 @@ constexpr int kTickRateHz = 30;
constexpr double kTickDurationMs = 1000.0 / kTickRateHz;
constexpr double kTickDurationSeconds = 1.0 / kTickRateHz;
// Delay between a tool activating (emitting its beam) and its effect being
// applied — half the 0.3 s beam duration. Shared by weapons, repair tools, and
// salvage modules so all three apply their effect mid-beam (REQ-SHP-FIRING,
// REQ-SHP-FIRING-BEAM).
constexpr Tick kBeamImpactDelayTicks = 5;
// Converts a wall-clock duration (in seconds, as it appears in config TOML) to
// an integer tick count. Rounds to nearest to avoid systematic drift from
// repeated conversions.

9
src/lib/ecs/component/AdvanceBehavior.h
View File

@@ -1,9 +0,0 @@
#pragma once
// Baseline fallback behavior, present on every ship. The executor moves the ship
// toward the opposing side (direction derived from FactionComponent), so a ship
// with no better behavior keeps advancing.
struct AdvanceBehavior
{
float score = 0.0f;
};

14
src/lib/ecs/component/AttackBehavior.h
View File

@@ -1,14 +0,0 @@
#pragma once
#include <optional>
#include "entt/entity/entity.hpp"
// Combat behavior for ships with weapons (was ThreatResponseBehaviorComponent).
// The evaluator sets currentTarget; the executor pushes it to in-range weapons.
struct AttackBehavior
{
std::optional<entt::entity> currentTarget;
float orbitRadius_tiles = 0.0f; // REQ-SHP-ORBIT
float score = 0.0f;
};

16
src/lib/ecs/component/BehaviorKind.h
View File

@@ -1,16 +0,0 @@
#pragma once
// Identifies a ship behavior. Written into SelectedBehaviorComponent by the
// AiSystem selection pass so each behavior's executor can tell whether it won.
enum class BehaviorKind
{
None,
Advance,
Standby,
Rally,
Retreat,
Attack,
Repair,
SalvageScrap,
DeliverScrap
};

23
src/lib/ecs/component/BehaviorScores.h
View File

@@ -1,23 +0,0 @@
#pragma once
// Score bands for ship-behavior evaluation. The AiSystem selection pass picks
// the behavior with the highest score per ship; these constants define a single
// comparable scale so the desired priority falls out:
// Retreat > Attack > Repair / Salvage / Deliver > Rally > Standby > Advance.
// Evaluators may return kInactive when their behavior does not apply this tick.
namespace BehaviorScores
{
constexpr float kInactive = 0.0f;
constexpr float kAdvance = 0.05f; // baseline fallback; always present
constexpr float kStandby = 0.10f; // repair-capable ships; hold with the fleet
constexpr float kRally = 0.20f;
constexpr float kDeliver = 0.50f; // cargo full
constexpr float kRepair = 0.55f;
constexpr float kSalvage = 0.55f; // cargo not full and scrap in range
constexpr float kAttack = 0.60f; // healthy and target in sensor range
constexpr float kRetreat = 0.90f;
// Health fraction below which a ship is considered "low HP" — used by the
// Retreat evaluator to trigger retreat (which outscores attack).
constexpr float kLowHpFraction = 0.3f;
}

19
src/lib/ecs/component/CMakeLists.txt
View File

@@ -1,31 +1,24 @@
SET(HDRS
${HDRS}
${CMAKE_CURRENT_SOURCE_DIR}/AdvanceBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/AttackBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/BehaviorKind.h
${CMAKE_CURRENT_SOURCE_DIR}/BehaviorScores.h
${CMAKE_CURRENT_SOURCE_DIR}/CargoComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/DeliverScrapBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/DespawnAtComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/DynamicBodyComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/FacingComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/FactionComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/HealthComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/HomeReturnBehaviorComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/HqProxyComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/MovementIntentComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/PositionComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/RallyBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/RepairBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/RallyBehaviorComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/RepairBehaviorComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/RepairToolComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/RetreatBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/SalvagerComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/SalvageScrapBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/SalvageBehaviorComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/SalvageCargoComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/ScrapDataComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/SelectedBehaviorComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/SensorRangeComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/ShipIdentityComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/StandbyBehavior.h
${CMAKE_CURRENT_SOURCE_DIR}/StationBodyComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/ThreatResponseBehaviorComponent.h
${CMAKE_CURRENT_SOURCE_DIR}/WeaponComponent.h
PARENT_SCOPE
)

10
src/lib/ecs/component/CargoComponent.h
View File

@@ -1,10 +0,0 @@
#pragma once
// Single shared salvage cargo pool for a ship (REQ-MOD-CARGO-CAPACITY). Attached
// to a ship at spawn only when its cargo capacity stat is greater than 0. All of
// the ship's salvage modules deposit into this one pool; delivery draws from it.
struct CargoComponent
{
int maxCapacity;
int current;
};

12
src/lib/ecs/component/DeliverScrapBehavior.h
View File

@@ -1,12 +0,0 @@
#pragma once
#include "BuildingId.h"
// Deliver-scrap behavior (one half of the old SalvageBehaviorComponent). Scored
// high only when cargo is full. The evaluator assigns the nearest SalvageBay;
// SalvagerSystem performs the actual delivery.
struct DeliverScrapBehavior
{
BuildingId deliveryBay = kInvalidBuildingId;
float score = 0.0f;
};

9
src/lib/ecs/component/HomeReturnBehaviorComponent.h Normal file
View File

@@ -0,0 +1,9 @@
#pragma once
#include <QVector2D>
struct HomeReturnBehaviorComponent
{
float retreatHpFraction;
QVector2D homePos;
};

15
src/lib/ecs/component/MovementIntentComponent.h
View File

@@ -2,16 +2,11 @@
#include <QVector2D>
// The winning behavior's executor writes this each tick before movement runs.
// `active` is false when no behavior set a destination (the ship brakes); the
// score-based selection (see architecture.md "Movement Arbitration") decides
// which single executor writes here.
// A ship-behavior system writes this each tick before movement runs; the
// highest-priority write wins. Priority order is fixed globally — see
// architecture.md "Movement Arbitration".
struct MovementIntentComponent
{
bool active = false;
QVector2D target; // straight-line destination, or orbit center when orbitRadius_tiles > 0
float orbitRadius_tiles = 0.0f; // 0 ⇒ go straight to target; >0 ⇒ orbit target at this radius
QVector2D orbitCenterVelocity_tpt; // velocity of the orbit center (0 for a static center); the orbit
// sense is resolved relative to this so a moving target's own motion
// does not bias it
int priority;
QVector2D target;
};

12
src/lib/ecs/component/RallyBehavior.h
View File

@@ -1,12 +0,0 @@
#pragma once
#include <QVector2D>
// Player combat ships loiter at the rally point until the departure timer
// removes this component (ShipSystem::triggerRallyDeparture).
struct RallyBehavior
{
QVector2D rallyPoint;
float orbitRadius_tiles = 0.0f; // REQ-SHP-ORBIT
float score = 0.0f;
};

8
src/lib/ecs/component/RallyBehaviorComponent.h Normal file
View File

@@ -0,0 +1,8 @@
#pragma once
#include <QVector2D>
struct RallyBehaviorComponent
{
QVector2D rallyPoint;
};

16
src/lib/ecs/component/RepairBehavior.h
View File

@@ -1,16 +0,0 @@
#pragma once
#include <optional>
#include "entt/entity/entity.hpp"
// Repair behavior for ships with repair modules. The evaluator picks the nearest
// damaged friendly as currentTarget; the executor moves toward it and assigns
// in-range repair tools. RepairSystem applies the actual healing.
struct RepairBehavior
{
std::optional<entt::entity> currentTarget;
float maxRepairRange_tiles = 0.0f;
float orbitRadius_tiles = 0.0f; // REQ-SHP-ORBIT
float score = 0.0f;
};

11
src/lib/ecs/component/RepairBehaviorComponent.h Normal file
View File

@@ -0,0 +1,11 @@
#pragma once
#include <optional>
#include "entt/entity/entity.hpp"
struct RepairBehaviorComponent
{
std::optional<entt::entity> currentTarget;
float maxRepairRange_tiles = 0.0f;
};

4
src/lib/ecs/component/RepairToolComponent.h
View File

@@ -6,9 +6,7 @@
struct RepairToolComponent
{
float repairAmountHp; // HP restored per repair cycle
int repairIntervalTicks; // cycle period = kTickRateHz / repair-rate (cycles/s); 0 = never
int cooldownTicksRemaining; // ticks until this tool may start its next cycle
float ratePerTick;
float range_tiles;
std::optional<entt::entity> currentTarget;
};

13
src/lib/ecs/component/RetreatBehavior.h
View File

@@ -1,13 +0,0 @@
#pragma once
#include <QVector2D>
// Player-only retreat behavior (replaces HomeReturnBehaviorComponent). Scored
// high when HP is low, or when an enemy is in sensor range and the ship cannot
// fight back. The executor moves the ship to retreatPoint (the rally point).
struct RetreatBehavior
{
float retreatHpFraction = 0.0f;
QVector2D retreatPoint;
float score = 0.0f;
};

14
src/lib/ecs/component/SalvageBehaviorComponent.h Normal file
View File

@@ -0,0 +1,14 @@
#pragma once
#include <optional>
#include <QVector2D>
#include "BuildingId.h"
struct SalvageBehaviorComponent
{
std::optional<QVector2D> scrapTarget;
BuildingId deliveryBay; // kInvalidBuildingId until assigned at a salvage bay
float maxCollectionRange_tiles = 0.0f;
};

10
src/lib/ecs/component/SalvageCargoComponent.h Normal file
View File

@@ -0,0 +1,10 @@
#pragma once
struct SalvageCargoComponent
{
int capacity;
int current;
float collectionRange_tiles;
int collectionIntervalTicks;
int cooldownTicksRemaining;
};

15
src/lib/ecs/component/SalvageScrapBehavior.h
View File

@@ -1,15 +0,0 @@
#pragma once
#include <optional>
#include <QVector2D>
// Collect-scrap behavior (one half of the old SalvageBehaviorComponent). The
// evaluator finds the nearest scrap and sets scrapTarget when cargo is not full.
struct SalvageScrapBehavior
{
std::optional<QVector2D> scrapTarget;
float maxCollectionRange_tiles = 0.0f;
float orbitRadius_tiles = 0.0f; // REQ-SHP-ORBIT
float score = 0.0f;
};

11
src/lib/ecs/component/SalvagerComponent.h
View File

@@ -1,11 +0,0 @@
#pragma once
// Per-instance salvage collection emitter. Each placed salvage module owns one of
// these and runs its own collection cycle on its own cooldown. The collected scrap
// is stored in the owning ship's shared CargoComponent (REQ-SHP-SALVAGE), not here.
struct SalvagerComponent
{
float collectionRange_tiles;
int collectionIntervalTicks;
int cooldownTicksRemaining;
};

11
src/lib/ecs/component/SelectedBehaviorComponent.h
View File

@@ -1,11 +0,0 @@
#pragma once
#include "BehaviorKind.h"
// Result of the AiSystem selection pass: the highest-scoring behavior for a
// ship this tick. Each behavior's executor acts only when it is the winner.
struct SelectedBehaviorComponent
{
BehaviorKind winner = BehaviorKind::None;
float bestScore = 0.0f;
};

4
src/lib/ecs/component/ShipIdentityComponent.h
View File

@@ -4,8 +4,6 @@
struct ShipIdentityComponent
{
int level;
std::string schematicId;
// Scrap dropped on destruction, derived from the ship's as-built threat cost
// at spawn time (REQ-RES-SCRAP-DROP).
int scrapDrop = 0;
};

11
src/lib/ecs/component/StandbyBehavior.h
View File

@@ -1,11 +0,0 @@
#pragma once
// Fallback for ships with a repair capability: instead of charging the enemy
// like AdvanceBehavior, the ship holds with its fleet so damaged allies stay in
// sensor range and it can heal them. Scored just above Advance and below Rally,
// so it only wins when no more urgent behavior applies. The executor decides the
// destination (StandbyExecutor).
struct StandbyBehavior
{
float score = 0.0f;
};

10
src/lib/ecs/component/ThreatResponseBehaviorComponent.h Normal file
View File

@@ -0,0 +1,10 @@
#pragma once
#include <optional>
#include "entt/entity/entity.hpp"
struct ThreatResponseBehaviorComponent
{
std::optional<entt::entity> currentTarget;
};

650
src/lib/ecs/system/AiSystem.cpp
View File

@@ -1,93 +1,587 @@
#include "AiSystem.h"
#include <limits>
#include <optional>
#include <unordered_map>
#include <vector>
#include "GameConfig.h"
#include <QVector2D>
#include "AdvanceBehavior.h"
#include "AttackBehavior.h"
#include "BehaviorKind.h"
#include "DeliverScrapBehavior.h"
#include "Building.h"
#include "BuildingSystem.h"
#include "BuildingType.h"
#include "BuildingId.h"
#include "EntityAdmin.h"
#include "RallyBehavior.h"
#include "RepairBehavior.h"
#include "RetreatBehavior.h"
#include "SalvageScrapBehavior.h"
#include "SelectedBehaviorComponent.h"
#include "StandbyBehavior.h"
#include "FactionComponent.h"
#include "HealthComponent.h"
#include "HomeReturnBehaviorComponent.h"
#include "HqProxyComponent.h"
#include "ModuleOwnerComponent.h"
#include "MovementIntentComponent.h"
#include "PositionComponent.h"
#include "RallyBehaviorComponent.h"
#include "RepairBehaviorComponent.h"
#include "RepairToolComponent.h"
#include "SalvageBehaviorComponent.h"
#include "SalvageCargoComponent.h"
#include "ScrapSystem.h"
#include "SensorRangeComponent.h"
#include "ShipIdentityComponent.h"
#include "StationBodyComponent.h"
#include "ThreatResponseBehaviorComponent.h"
#include "tracing.h"
namespace
// ---------------------------------------------------------------------------
// Shared helpers for repair targeting
// ---------------------------------------------------------------------------
struct RepairableInfo
{
// Records a behavior's score for its owning ship, keeping the highest seen.
// Considered high-priority first, so strict '>' breaks ties toward priority.
template <typename Behavior>
void consider(EntityAdmin& admin, BehaviorKind kind)
{
admin.forEach<Behavior, SelectedBehaviorComponent>(
[kind](entt::entity /*e*/, const Behavior& behavior,
SelectedBehaviorComponent& selected)
{
if (behavior.score > selected.bestScore)
{
selected.bestScore = behavior.score;
selected.winner = kind;
}
});
}
}
entt::entity entity;
QVector2D position;
bool isEnemy;
bool isShip;
float hp;
float maxHp;
};
AiSystem::AiSystem(const GameConfig& config)
: m_attackEvaluator(config.world.targeting)
static std::vector<RepairableInfo> buildRepairables(EntityAdmin& admin)
{
}
std::vector<RepairableInfo> repairables;
void AiSystem::tick(EntityAdmin& admin, const BuildingSystem& buildings,
const ScrapSystem& scraps)
{
TRACE();
// Phase 1: evaluators score behaviors and set their target data.
m_advanceEvaluator.evaluate(admin);
m_standbyEvaluator.evaluate(admin);
m_rallyEvaluator.evaluate(admin);
m_retreatEvaluator.evaluate(admin);
m_attackEvaluator.evaluate(admin);
m_repairEvaluator.evaluate(admin);
m_salvageScrapEvaluator.evaluate(admin, scraps);
m_deliverScrapEvaluator.evaluate(admin, buildings);
// Phase 2: pick the highest-scoring behavior per ship.
selectWinningBehaviors(admin);
// Phase 3: executors run for the winning behavior.
m_advanceExecutor.execute(admin);
m_standbyExecutor.execute(admin);
m_rallyExecutor.execute(admin);
m_retreatExecutor.execute(admin);
m_attackExecutor.execute(admin);
m_repairExecutor.execute(admin);
m_salvageScrapExecutor.execute(admin);
m_deliverScrapExecutor.execute(admin, buildings);
}
void AiSystem::selectWinningBehaviors(EntityAdmin& admin)
{
TRACE();
admin.forEach<SelectedBehaviorComponent>(
[](entt::entity /*e*/, SelectedBehaviorComponent& selected)
admin.forEach<ShipIdentityComponent, PositionComponent, FactionComponent, HealthComponent>(
[&repairables](entt::entity e, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& f,
const HealthComponent& h)
{
selected.winner = BehaviorKind::None;
selected.bestScore = std::numeric_limits<float>::lowest();
repairables.push_back({e, pos.value, f.isEnemy, true, h.hp, h.maxHp});
});
// Highest priority first so ties resolve toward the more urgent behavior.
consider<RetreatBehavior>(admin, BehaviorKind::Retreat);
consider<AttackBehavior>(admin, BehaviorKind::Attack);
consider<RepairBehavior>(admin, BehaviorKind::Repair);
consider<SalvageScrapBehavior>(admin, BehaviorKind::SalvageScrap);
consider<DeliverScrapBehavior>(admin, BehaviorKind::DeliverScrap);
consider<RallyBehavior>(admin, BehaviorKind::Rally);
consider<StandbyBehavior>(admin, BehaviorKind::Standby);
consider<AdvanceBehavior>(admin, BehaviorKind::Advance);
admin.forEach<StationBodyComponent, PositionComponent, FactionComponent, HealthComponent>(
[&repairables](entt::entity e, const StationBodyComponent& /*sb*/,
const PositionComponent& pos, const FactionComponent& f,
const HealthComponent& h)
{
repairables.push_back({e, pos.value, f.isEnemy, false, h.hp, h.maxHp});
});
return repairables;
}
// ---------------------------------------------------------------------------
// tickHomeReturnBehavior (priority 4)
// ---------------------------------------------------------------------------
void AiSystem::tickHomeReturnBehavior(EntityAdmin& admin)
{
TRACE();
admin.forEach<HomeReturnBehaviorComponent, HealthComponent, MovementIntentComponent>(
[](entt::entity /*e*/, const HomeReturnBehaviorComponent& homeReturnBehavior,
const HealthComponent& h, MovementIntentComponent& intent)
{
if (h.hp / h.maxHp < homeReturnBehavior.retreatHpFraction)
{
if (4 > intent.priority)
{
intent = MovementIntentComponent{4, homeReturnBehavior.homePos};
}
}
});
}
// ---------------------------------------------------------------------------
// tickThreatResponseBehavior (priority 3)
// ---------------------------------------------------------------------------
void AiSystem::tickThreatResponseBehavior(EntityAdmin& admin, const BuildingSystem& buildings)
{
TRACE();
// Snapshot all combatant entities for target acquisition.
struct CombatantInfo
{
entt::entity entity;
QVector2D position;
bool isEnemy;
bool isStation;
};
std::vector<CombatantInfo> combatants;
admin.forEach<PositionComponent, FactionComponent, ShipIdentityComponent>(
[&combatants](entt::entity e, const PositionComponent& pos,
const FactionComponent& f, const ShipIdentityComponent& /*si*/)
{
combatants.push_back({e, pos.value, f.isEnemy, false});
});
admin.forEach<PositionComponent, FactionComponent, StationBodyComponent>(
[&combatants](entt::entity e, const PositionComponent& pos,
const FactionComponent& f, const StationBodyComponent& /*sb*/)
{
combatants.push_back({e, pos.value, f.isEnemy, true});
});
admin.forEach<PositionComponent, FactionComponent, HqProxyComponent>(
[&combatants](entt::entity e, const PositionComponent& pos,
const FactionComponent& f, const HqProxyComponent& /*hq*/)
{
combatants.push_back({e, pos.value, f.isEnemy, true});
});
admin.forEach<ThreatResponseBehaviorComponent, PositionComponent, FactionComponent,
SensorRangeComponent, MovementIntentComponent>(
[&](entt::entity e, ThreatResponseBehaviorComponent& threatResponseBehavior,
PositionComponent& pos, FactionComponent& faction,
SensorRangeComponent& sensor, MovementIntentComponent& intent)
{
const float range = sensor.value_tiles;
// Validate current target.
bool targetValid = false;
if (threatResponseBehavior.currentTarget)
{
const entt::entity t = *threatResponseBehavior.currentTarget;
if (admin.isValid(t) && admin.hasAll<PositionComponent>(t))
{
const float dist =
(admin.get<PositionComponent>(t).value - pos.value).length();
if (dist <= range)
{
targetValid = true;
}
}
}
if (!targetValid)
{
threatResponseBehavior.currentTarget = std::nullopt;
float bestDist = range;
for (const CombatantInfo& c : combatants)
{
if (c.entity == e) { continue; }
bool isValidTarget = false;
if (!faction.isEnemy)
{
isValidTarget = c.isEnemy;
}
else
{
isValidTarget = !c.isEnemy;
}
if (!isValidTarget) { continue; }
const float dist = (c.position - pos.value).length();
if (dist < bestDist)
{
bestDist = dist;
threatResponseBehavior.currentTarget = c.entity;
}
}
}
if (threatResponseBehavior.currentTarget)
{
const entt::entity t = *threatResponseBehavior.currentTarget;
QVector2D dest = pos.value;
if (admin.isValid(t) && admin.hasAll<PositionComponent>(t))
{
dest = admin.get<PositionComponent>(t).value;
}
if (3 > intent.priority)
{
intent = MovementIntentComponent{3, dest};
}
}
else
{
if (3 > intent.priority)
{
if (admin.hasAll<RallyBehaviorComponent>(e))
{
intent = MovementIntentComponent{
3, admin.get<RallyBehaviorComponent>(e).rallyPoint};
}
else if (!faction.isEnemy)
{
intent = MovementIntentComponent{
3, QVector2D(pos.value.x() + 1000.0f, pos.value.y())};
}
else
{
intent = MovementIntentComponent{
3, QVector2D(-10000.0f, pos.value.y())};
}
}
}
});
}
// ---------------------------------------------------------------------------
// tickRepairBehavior (priority 2)
// ---------------------------------------------------------------------------
void AiSystem::tickRepairBehavior(EntityAdmin& admin, BuildingSystem& buildings)
{
TRACE();
std::vector<RepairableInfo> repairables = buildRepairables(admin);
// Snapshot enemy ships for threat detection.
struct EnemyInfo
{
QVector2D position;
};
std::vector<EnemyInfo> enemies;
admin.forEach<ShipIdentityComponent, PositionComponent, FactionComponent>(
[&enemies](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& f)
{
if (f.isEnemy)
{
enemies.push_back({pos.value});
}
});
admin.forEach<RepairBehaviorComponent, PositionComponent,
FactionComponent, SensorRangeComponent, MovementIntentComponent>(
[&](entt::entity e, RepairBehaviorComponent& rb,
PositionComponent& pos, FactionComponent& /*faction*/,
SensorRangeComponent& sensor, MovementIntentComponent& intent)
{
// Flee if enemy nearby.
bool enemyNearby = false;
for (const EnemyInfo& enemy : enemies)
{
if ((enemy.position - pos.value).length() <= sensor.value_tiles)
{
enemyNearby = true;
break;
}
}
if (enemyNearby)
{
if (2 > intent.priority)
{
intent = MovementIntentComponent{
2, QVector2D(-10000.0f, pos.value.y())};
}
return;
}
// Validate current target.
bool targetValid = false;
if (rb.currentTarget)
{
const entt::entity t = *rb.currentTarget;
if (admin.isValid(t) && admin.hasAll<HealthComponent>(t))
{
const HealthComponent& th = admin.get<HealthComponent>(t);
if (th.hp > 0.0f && th.hp < th.maxHp)
{
targetValid = true;
}
}
}
if (!targetValid)
{
rb.currentTarget = std::nullopt;
float bestDist = sensor.value_tiles;
for (const RepairableInfo& r : repairables)
{
if (r.entity == e) { continue; }
if (r.isEnemy) { continue; }
if (r.hp >= r.maxHp) { continue; }
const float dist = (r.position - pos.value).length();
if (dist < bestDist)
{
bestDist = dist;
rb.currentTarget = r.entity;
}
}
}
if (!rb.currentTarget)
{
if (2 > intent.priority)
{
intent = MovementIntentComponent{
2, QVector2D(pos.value.x() + 1000.0f, pos.value.y())};
}
return;
}
const entt::entity target = *rb.currentTarget;
QVector2D targetPos = pos.value;
if (admin.isValid(target) && admin.hasAll<PositionComponent>(target))
{
targetPos = admin.get<PositionComponent>(target).value;
}
if (2 > intent.priority)
{
intent = MovementIntentComponent{2, targetPos};
}
});
}
// ---------------------------------------------------------------------------
// tickRepairTools
// ---------------------------------------------------------------------------
void AiSystem::tickRepairTools(EntityAdmin& admin)
{
TRACE();
const std::vector<RepairableInfo> repairables = buildRepairables(admin);
admin.forEach<RepairToolComponent, ModuleOwnerComponent>(
[&](entt::entity /*e*/, RepairToolComponent& rt, const ModuleOwnerComponent& owner)
{
if (!admin.hasAll<RepairBehaviorComponent>(owner.owner)) { return; }
const RepairBehaviorComponent& rb =
admin.get<RepairBehaviorComponent>(owner.owner);
const PositionComponent& ownerPos =
admin.get<PositionComponent>(owner.owner);
// Try the ship's preferred nav target first.
if (rb.currentTarget)
{
const entt::entity preferred = *rb.currentTarget;
if (admin.isValid(preferred) && admin.hasAll<HealthComponent>(preferred)
&& admin.hasAll<PositionComponent>(preferred))
{
HealthComponent& th = admin.get<HealthComponent>(preferred);
const float dist =
(admin.get<PositionComponent>(preferred).value
- ownerPos.value).length();
if (th.hp > 0.0f && th.hp < th.maxHp && dist <= rt.range_tiles)
{
rt.currentTarget = rb.currentTarget;
th.hp = std::min(th.hp + rt.ratePerTick, th.maxHp);
return;
}
}
}
// Preferred target unavailable; scan for nearest damaged friendly in range.
rt.currentTarget = std::nullopt;
float bestDist = rt.range_tiles;
for (const RepairableInfo& r : repairables)
{
if (r.isEnemy) { continue; }
if (r.hp <= 0.0f || r.hp >= r.maxHp) { continue; }
const float dist = (r.position - ownerPos.value).length();
if (dist < bestDist)
{
bestDist = dist;
rt.currentTarget = r.entity;
}
}
if (!rt.currentTarget) { return; }
HealthComponent& targetHealth =
admin.get<HealthComponent>(*rt.currentTarget);
targetHealth.hp = std::min(targetHealth.hp + rt.ratePerTick, targetHealth.maxHp);
});
}
// ---------------------------------------------------------------------------
// tickSalvageBehavior (priority 1)
// ---------------------------------------------------------------------------
void AiSystem::tickSalvageBehavior(EntityAdmin& admin, ScrapSystem& scraps,
BuildingSystem& buildings)
{
TRACE();
// Snapshot enemy ships for threat detection.
struct EnemyShipPos
{
QVector2D position;
};
std::vector<EnemyShipPos> enemyShips;
admin.forEach<ShipIdentityComponent, PositionComponent, FactionComponent>(
[&enemyShips](entt::entity /*e*/, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& f)
{
if (f.isEnemy)
{
enemyShips.push_back({pos.value});
}
});
// Aggregate cargo across all salvage-module children per owning ship.
struct AggregatedCargo
{
int totalCurrent = 0;
int totalCapacity = 0;
};
std::unordered_map<entt::entity, AggregatedCargo> cargoByShip;
admin.forEach<SalvageCargoComponent, ModuleOwnerComponent>(
[&](entt::entity /*ce*/, const SalvageCargoComponent& c, const ModuleOwnerComponent& o)
{
AggregatedCargo& agg = cargoByShip[o.owner];
agg.totalCurrent += c.current;
agg.totalCapacity += c.capacity;
});
const std::vector<ScrapInfo> allScrap = scraps.allScrapInfo();
// Tick down per-module collection cooldowns.
admin.forEach<SalvageCargoComponent>(
[](entt::entity /*e*/, SalvageCargoComponent& c)
{
if (c.cooldownTicksRemaining > 0) { --c.cooldownTicksRemaining; }
});
admin.forEach<SalvageBehaviorComponent, PositionComponent,
SensorRangeComponent, MovementIntentComponent>(
[&](entt::entity e, SalvageBehaviorComponent& salvageBehavior,
PositionComponent& pos,
SensorRangeComponent& sensor, MovementIntentComponent& intent)
{
const float collectRange = salvageBehavior.maxCollectionRange_tiles;
const AggregatedCargo& cargoState = cargoByShip[e];
// Assign nearest SalvageBay if needed.
if (salvageBehavior.deliveryBay == kInvalidBuildingId)
{
const Building* bay = buildings.findNearestBuilding(pos.value,
BuildingType::SalvageBay);
if (bay)
{
salvageBehavior.deliveryBay = bay->id;
}
}
const BuildingId bayId = salvageBehavior.deliveryBay;
QVector2D bayPos = pos.value;
if (bayId != kInvalidBuildingId)
{
const Building* bay = buildings.findBuilding(bayId);
if (bay)
{
bayPos = QVector2D(bay->anchor.x() + bay->footprint.width() / 2.0f,
bay->anchor.y() + bay->footprint.height() / 2.0f);
}
}
const bool cargoFull = (cargoState.totalCurrent >= cargoState.totalCapacity
&& cargoState.totalCapacity > 0);
if (cargoFull)
{
if (1 > intent.priority)
{
intent = MovementIntentComponent{1, bayPos};
}
if (bayId != kInvalidBuildingId
&& (pos.value - bayPos).length() <= 1.0f)
{
// Decrement first non-empty salvage child.
bool delivered = false;
admin.forEach<SalvageCargoComponent, ModuleOwnerComponent>(
[&](entt::entity /*ce*/, SalvageCargoComponent& c,
const ModuleOwnerComponent& o)
{
if (delivered || o.owner != e || c.current <= 0) { return; }
if (buildings.deliverScrapToSalvageBay(bayId))
{
--c.current;
delivered = true;
}
});
}
return;
}
// Retreat if enemy near and cargo empty.
bool retreating = false;
if (cargoState.totalCurrent == 0)
{
for (const EnemyShipPos& enemy : enemyShips)
{
if ((enemy.position - pos.value).length() <= collectRange)
{
if (1 > intent.priority)
{
intent = MovementIntentComponent{
1, QVector2D(-10000.0f, pos.value.y())};
}
retreating = true;
break;
}
}
}
if (retreating) { return; }
// Per-module independent collection: each ready module collects one scrap.
bool anythingCollected = false;
admin.forEach<SalvageCargoComponent, ModuleOwnerComponent>(
[&](entt::entity /*ce*/, SalvageCargoComponent& c,
const ModuleOwnerComponent& o)
{
if (o.owner != e || c.current >= c.capacity
|| c.cooldownTicksRemaining > 0)
{
return;
}
for (const ScrapInfo& si : allScrap)
{
if ((si.position - pos.value).length() > c.collectionRange_tiles) { continue; }
if (scraps.consume(si.entity))
{
++c.current;
c.cooldownTicksRemaining = c.collectionIntervalTicks;
anythingCollected = true;
break;
}
}
});
if (anythingCollected)
{
salvageBehavior.scrapTarget = std::nullopt;
}
// Move toward scrap target or find a new one.
if (salvageBehavior.scrapTarget)
{
if (1 > intent.priority)
{
intent = MovementIntentComponent{1, *salvageBehavior.scrapTarget};
}
}
else
{
float bestDist = sensor.value_tiles;
std::optional<QVector2D> bestPos;
for (const ScrapInfo& si : allScrap)
{
const float dist = (si.position - pos.value).length();
if (dist < bestDist)
{
bestDist = dist;
bestPos = si.position;
}
}
if (bestPos)
{
salvageBehavior.scrapTarget = bestPos;
if (1 > intent.priority)
{
intent = MovementIntentComponent{1, *bestPos};
}
}
else
{
if (1 > intent.priority)
{
intent = MovementIntentComponent{
1, QVector2D(pos.value.x() + 1000.0f, pos.value.y())};
}
}
}
});
}

54
src/lib/ecs/system/AiSystem.h
View File

@@ -1,59 +1,15 @@
#pragma once
#include "AdvanceEvaluator.h"
#include "AdvanceExecutor.h"
#include "AttackEvaluator.h"
#include "AttackExecutor.h"
#include "DeliverScrapEvaluator.h"
#include "DeliverScrapExecutor.h"
#include "RallyEvaluator.h"
#include "RallyExecutor.h"
#include "RepairEvaluator.h"
#include "RepairExecutor.h"
#include "RetreatEvaluator.h"
#include "RetreatExecutor.h"
#include "SalvageScrapEvaluator.h"
#include "SalvageScrapExecutor.h"
#include "StandbyEvaluator.h"
#include "StandbyExecutor.h"
class BuildingSystem;
class EntityAdmin;
class ScrapSystem;
struct GameConfig;
// Orchestrates ship-behavior decision-making in three batched phases:
// 1. evaluators score each behavior and set its target data,
// 2. selectWinningBehaviors picks the highest-scoring behavior per ship,
// 3. executors run for the winning behavior, setting movement intent and
// preferred module targets.
// All world mutation (collection, healing, damage) is left to the module
// systems (SalvagerSystem, RepairSystem, CombatSystem).
class AiSystem
{
public:
explicit AiSystem(const GameConfig& config);
void tick(EntityAdmin& admin, const BuildingSystem& buildings, const ScrapSystem& scraps);
private:
void selectWinningBehaviors(EntityAdmin& admin);
AdvanceEvaluator m_advanceEvaluator;
StandbyEvaluator m_standbyEvaluator;
RallyEvaluator m_rallyEvaluator;
RetreatEvaluator m_retreatEvaluator;
AttackEvaluator m_attackEvaluator;
RepairEvaluator m_repairEvaluator;
SalvageScrapEvaluator m_salvageScrapEvaluator;
DeliverScrapEvaluator m_deliverScrapEvaluator;
AdvanceExecutor m_advanceExecutor;
StandbyExecutor m_standbyExecutor;
RallyExecutor m_rallyExecutor;
RetreatExecutor m_retreatExecutor;
AttackExecutor m_attackExecutor;
RepairExecutor m_repairExecutor;
SalvageScrapExecutor m_salvageScrapExecutor;
DeliverScrapExecutor m_deliverScrapExecutor;
void tickHomeReturnBehavior(EntityAdmin& admin);
void tickThreatResponseBehavior(EntityAdmin& admin, const BuildingSystem& buildings);
void tickRepairBehavior(EntityAdmin& admin, BuildingSystem& buildings);
void tickRepairTools(EntityAdmin& admin);
void tickSalvageBehavior(EntityAdmin& admin, ScrapSystem& scraps, BuildingSystem& buildings);
};

39
src/lib/ecs/system/CMakeLists.txt
View File

@@ -1,28 +1,9 @@
SET(HDRS
${HDRS}
${CMAKE_CURRENT_SOURCE_DIR}/ai/AdvanceEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/AdvanceExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/AttackEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/AttackExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/BehaviorTargeting.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/DeliverScrapEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/DeliverScrapExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/RallyEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/RallyExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/RepairEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/RepairExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/RetreatEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/RetreatExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/SalvageScrapEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/SalvageScrapExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/StandbyEvaluator.h
${CMAKE_CURRENT_SOURCE_DIR}/ai/StandbyExecutor.h
${CMAKE_CURRENT_SOURCE_DIR}/AiSystem.h
${CMAKE_CURRENT_SOURCE_DIR}/CombatSystem.h
${CMAKE_CURRENT_SOURCE_DIR}/DynamicBodySystem.h
${CMAKE_CURRENT_SOURCE_DIR}/MovementIntentSystem.h
${CMAKE_CURRENT_SOURCE_DIR}/RepairSystem.h
${CMAKE_CURRENT_SOURCE_DIR}/SalvagerSystem.h
${CMAKE_CURRENT_SOURCE_DIR}/ScrapSystem.h
${CMAKE_CURRENT_SOURCE_DIR}/ShipSystem.h
PARENT_SCOPE
@@ -30,29 +11,10 @@ SET(HDRS
SET(SRCS
${SRCS}
${CMAKE_CURRENT_SOURCE_DIR}/ai/AdvanceEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/AdvanceExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/AttackEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/AttackExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/BehaviorTargeting.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/DeliverScrapEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/DeliverScrapExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/RallyEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/RallyExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/RepairEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/RepairExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/RetreatEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/RetreatExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/SalvageScrapEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/SalvageScrapExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/StandbyEvaluator.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ai/StandbyExecutor.cpp
${CMAKE_CURRENT_SOURCE_DIR}/AiSystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/CombatSystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/DynamicBodySystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/MovementIntentSystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/RepairSystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/SalvagerSystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ScrapSystem.cpp
${CMAKE_CURRENT_SOURCE_DIR}/ShipSystem.cpp
PARENT_SCOPE
@@ -61,6 +23,5 @@ SET(SRCS
set(LIB_INCLUDE_PATH
${LIB_INCLUDE_PATH}
${CMAKE_CURRENT_SOURCE_DIR}
${CMAKE_CURRENT_SOURCE_DIR}/ai
PARENT_SCOPE
)

21
src/lib/ecs/system/CombatSystem.cpp
View File

@@ -7,9 +7,12 @@
#include "PositionComponent.h"
#include "SensorRangeComponent.h"
#include "ShipIdentityComponent.h"
#include "ThreatResponseBehaviorComponent.h"
#include "tracing.h"
#include "WeaponComponent.h"
static constexpr Tick kWeaponImpactDelayTicks = 5;
CombatSystem::CombatSystem(const GameConfig& config)
: m_config(config)
{
@@ -18,18 +21,21 @@ CombatSystem::CombatSystem(const GameConfig& config)
void CombatSystem::tick(Tick currentTick,
EntityAdmin& admin,
BuildingSystem& /*buildings*/,
std::vector<BeamFiredEvent>& outBeamFiredEvents)
std::vector<WeaponFiredEvent>& outWeaponFiredEvents)
{
TRACE();
// All weapons (ships and stations) are child entities linked via ModuleOwnerComponent.
// AttackExecutor has already set each weapon's preferred (in-range) target; here we
// validate it, fall back to nearest-target acquisition, and fire.
admin.forEach<WeaponComponent, ModuleOwnerComponent>(
[&](entt::entity /*e*/, WeaponComponent& weapon, const ModuleOwnerComponent& owner)
{
if (admin.hasAll<ThreatResponseBehaviorComponent>(owner.owner))
{
weapon.currentTarget =
admin.get<ThreatResponseBehaviorComponent>(owner.owner).currentTarget;
}
const PositionComponent& pos = admin.get<PositionComponent>(owner.owner);
const FactionComponent& faction = admin.get<FactionComponent>(owner.owner);
resolveWeapon(owner.owner, weapon, pos, faction, currentTick, admin, outBeamFiredEvents);
resolveWeapon(owner.owner, weapon, pos, faction, currentTick, admin, outWeaponFiredEvents);
});
}
@@ -40,7 +46,7 @@ void CombatSystem::resolveWeapon(
const FactionComponent& ownFaction,
Tick currentTick,
EntityAdmin& admin,
std::vector<BeamFiredEvent>& out)
std::vector<WeaponFiredEvent>& out)
{
if (weapon.cooldownTicks > 0.0f)
{
@@ -107,10 +113,9 @@ void CombatSystem::resolveWeapon(
const entt::entity targetEntity = *weapon.currentTarget;
m_pendingDamage.push_back({targetEntity, weapon.damage,
currentTick + kBeamImpactDelayTicks});
currentTick + kWeaponImpactDelayTicks});
BeamFiredEvent evt;
evt.kind = BeamKind::Weapon;
WeaponFiredEvent evt;
evt.shooter = shipEntity;
evt.target = targetEntity;
evt.emittedAt = currentTick;

6
src/lib/ecs/system/CombatSystem.h
View File

@@ -7,7 +7,7 @@
#include "Building.h"
#include "FactionComponent.h"
#include "BeamFiredEvent.h"
#include "WeaponFiredEvent.h"
#include "GameConfig.h"
#include "PositionComponent.h"
#include "Tick.h"
@@ -26,7 +26,7 @@ public:
void tick(Tick currentTick,
EntityAdmin& admin,
BuildingSystem& buildings,
std::vector<BeamFiredEvent>& outBeamFiredEvents);
std::vector<WeaponFiredEvent>& outWeaponFiredEvents);
void applyPendingDamage(Tick currentTick, EntityAdmin& admin);
@@ -47,7 +47,7 @@ private:
const FactionComponent& ownFaction,
Tick currentTick,
EntityAdmin& admin,
std::vector<BeamFiredEvent>& out);
std::vector<WeaponFiredEvent>& out);
const GameConfig& m_config;
};

18
src/lib/ecs/system/MovementIntentSystem.cpp
View File

@@ -9,7 +9,6 @@
#include "EntityAdmin.h"
#include "FacingComponent.h"
#include "MovementIntentComponent.h"
#include "OrbitMath.h"
#include "PositionComponent.h"
#include "tracing.h"
@@ -30,7 +29,7 @@ void MovementIntentSystem::tick(EntityAdmin& admin)
[](entt::entity /*e*/, const PositionComponent& pos, const FacingComponent& facing,
DynamicBodyComponent& body, const MovementIntentComponent& intent)
{
if (!intent.active)
if (intent.priority == 0)
{
// No movement intent: brake using available thrust.
const float linearBraking = std::min(body.velocity_tpt.length(),
@@ -46,20 +45,7 @@ void MovementIntentSystem::tick(EntityAdmin& admin)
return;
}
// Resolve the steering destination. For orbit intents, pick the orbit
// sense from the ship's current velocity (so ships circling the same
// target spread to both sides) and aim at a point on the orbit circle.
QVector2D destination = intent.target;
if (intent.orbitRadius_tiles > 0.0f)
{
const float sign = OrbitMath::resolveOrbitSign(
pos.value, intent.target, body.velocity_tpt,
intent.orbitCenterVelocity_tpt);
destination = OrbitMath::computeOrbitDestination(
pos.value, intent.target, intent.orbitRadius_tiles, sign);
}
const QVector2D delta = destination - pos.value;
const QVector2D delta = intent.target - pos.value;
const float dist = delta.length();
if (dist < 0.001f)

109
src/lib/ecs/system/RepairSystem.cpp
View File

@@ -1,109 +0,0 @@
#include "RepairSystem.h"
#include <algorithm>
#include <optional>
#include <vector>
#include <QVector2D>
#include "BehaviorTargeting.h"
#include "EntityAdmin.h"
#include "HealthComponent.h"
#include "ModuleOwnerComponent.h"
#include "PositionComponent.h"
#include "RepairToolComponent.h"
#include "tracing.h"
RepairSystem::RepairSystem(EntityAdmin& admin)
: m_admin(admin)
{
}
void RepairSystem::tick(Tick currentTick, std::vector<BeamFiredEvent>& outBeamFiredEvents)
{
TRACE();
// Apply heals whose mid-beam delay has elapsed (cycles started on prior ticks).
applyPendingHeals(currentTick);
const std::vector<RepairableInfo> repairables = buildRepairables(m_admin);
m_admin.forEach<RepairToolComponent, ModuleOwnerComponent>(
[&](entt::entity /*re*/, RepairToolComponent& tool, const ModuleOwnerComponent& owner)
{
if (tool.cooldownTicksRemaining > 0) { --tool.cooldownTicksRemaining; }
if (tool.cooldownTicksRemaining > 0) { return; }
if (tool.repairIntervalTicks <= 0) { return; }
if (!m_admin.hasAll<PositionComponent>(owner.owner)) { return; }
const QVector2D ownerPos = m_admin.get<PositionComponent>(owner.owner).value;
// Choose a target: honour the executor-set target if it is still valid
// and in range, else fall back to the nearest damaged friendly in range.
std::optional<entt::entity> target;
if (tool.currentTarget)
{
const entt::entity t = *tool.currentTarget;
if (m_admin.isValid(t) && m_admin.hasAll<HealthComponent, PositionComponent>(t))
{
const HealthComponent& th = m_admin.get<HealthComponent>(t);
const float dist =
(m_admin.get<PositionComponent>(t).value - ownerPos).length();
if (th.hp > 0.0f && th.hp < th.maxHp && dist <= tool.range_tiles)
{
target = t;
}
}
}
if (!target)
{
tool.currentTarget = std::nullopt;
float bestDist = tool.range_tiles;
for (const RepairableInfo& r : repairables)
{
if (r.isEnemy) { continue; }
if (r.hp <= 0.0f || r.hp >= r.maxHp) { continue; }
const float dist = (r.position - ownerPos).length();
if (dist < bestDist)
{
bestDist = dist;
tool.currentTarget = r.entity;
}
}
target = tool.currentTarget;
}
if (!target) { return; }
// Start a repair cycle: emit the beam now, apply the heal mid-beam, and
// begin the cooldown at cycle start (not at effect application).
outBeamFiredEvents.push_back(
BeamFiredEvent{BeamKind::Repair, owner.owner, *target, currentTick});
m_pendingHeals.push_back({*target, tool.repairAmountHp,
currentTick + kBeamImpactDelayTicks});
tool.cooldownTicksRemaining = tool.repairIntervalTicks;
});
}
void RepairSystem::applyPendingHeals(Tick currentTick)
{
std::vector<PendingHeal>::iterator it = m_pendingHeals.begin();
while (it != m_pendingHeals.end())
{
if (it->appliesAt <= currentTick)
{
if (m_admin.isValid(it->target) && m_admin.hasAll<HealthComponent>(it->target))
{
HealthComponent& h = m_admin.get<HealthComponent>(it->target);
if (h.hp > 0.0f && h.hp < h.maxHp)
{
h.hp = std::min(h.hp + it->amountHp, h.maxHp);
}
}
it = m_pendingHeals.erase(it);
}
else
{
++it;
}
}
}

36
src/lib/ecs/system/RepairSystem.h
View File

@@ -1,36 +0,0 @@
#pragma once
#include <vector>
#include "BeamFiredEvent.h"
#include "Tick.h"
#include "entt/entity/entity.hpp"
class EntityAdmin;
// World-mutation system for repair modules: each tool runs a cycle on its own
// cooldown. When a cycle starts it picks a target (the RepairExecutor-set target,
// else the nearest damaged friendly in range), emits a repair beam, and schedules
// the heal for mid-beam (kBeamImpactDelayTicks later) — mirroring weapon firing.
// Runs every tick, independent of behavior selection.
class RepairSystem
{
public:
explicit RepairSystem(EntityAdmin& admin);
void tick(Tick currentTick, std::vector<BeamFiredEvent>& outBeamFiredEvents);
private:
struct PendingHeal
{
entt::entity target;
float amountHp;
Tick appliesAt;
};
void applyPendingHeals(Tick currentTick);
EntityAdmin& m_admin;
std::vector<PendingHeal> m_pendingHeals;
};

132
src/lib/ecs/system/SalvagerSystem.cpp
View File

@@ -1,132 +0,0 @@
#include "SalvagerSystem.h"
#include <vector>
#include <QVector2D>
#include "Building.h"
#include "BuildingSystem.h"
#include "CargoComponent.h"
#include "DeliverScrapBehavior.h"
#include "EntityAdmin.h"
#include <map>
#include "ModuleOwnerComponent.h"
#include "PositionComponent.h"
#include "SalvagerComponent.h"
#include "ScrapDataComponent.h"
#include "ScrapSystem.h"
#include "tracing.h"
SalvagerSystem::SalvagerSystem(EntityAdmin& admin)
: m_admin(admin)
{
}
void SalvagerSystem::tick(Tick currentTick, ScrapSystem& scraps, BuildingSystem& buildings,
std::vector<BeamFiredEvent>& outBeamFiredEvents)
{
TRACE();
// Apply collections whose mid-beam delay has elapsed (cycles started earlier).
applyPendingCollections(currentTick, scraps);
const std::vector<ScrapInfo> allScrap = scraps.allScrapInfo();
// Tick down per-module collection cooldowns.
m_admin.forEach<SalvagerComponent>(
[](entt::entity /*e*/, SalvagerComponent& s)
{
if (s.cooldownTicksRemaining > 0) { --s.cooldownTicksRemaining; }
});
// Scrap units already claimed by not-yet-applied collection cycles, so two
// modules don't both target the last unit of the same pile (the claim would be
// dropped at apply time). A pile is available while its amount exceeds its claims.
std::map<entt::entity, int> claimedUnits;
// Collection cycles already in flight toward each ship's shared cargo pool, so
// concurrent modules on the same ship never start more cycles than the remaining
// capacity can hold (REQ-SHP-SALVAGE).
std::map<entt::entity, int> pendingByShip;
for (const PendingCollection& pc : m_pendingCollections)
{
++claimedUnits[pc.scrap];
++pendingByShip[pc.ship];
}
// Cycle start: each ready, in-range module whose ship's pool has free space begins
// a collection cycle — emit the beam now, collect one scrap mid-beam, start the
// cooldown now.
m_admin.forEach<SalvagerComponent, ModuleOwnerComponent>(
[&](entt::entity /*moduleEntity*/, SalvagerComponent& s, const ModuleOwnerComponent& o)
{
if (s.cooldownTicksRemaining > 0 || s.collectionIntervalTicks <= 0) { return; }
if (!m_admin.hasAll<PositionComponent, CargoComponent>(o.owner)) { return; }
const CargoComponent& cargo = m_admin.get<CargoComponent>(o.owner);
if (cargo.current + pendingByShip[o.owner] >= cargo.maxCapacity) { return; }
const QVector2D ownerPos = m_admin.get<PositionComponent>(o.owner).value;
for (const ScrapInfo& si : allScrap)
{
if ((si.position - ownerPos).length() > s.collectionRange_tiles) { continue; }
if (claimedUnits[si.entity] >= m_admin.get<ScrapDataComponent>(si.entity).amount)
{
continue; // every remaining unit of this pile is already spoken for
}
outBeamFiredEvents.push_back(
BeamFiredEvent{BeamKind::Salvage, o.owner, si.entity, currentTick});
m_pendingCollections.push_back({o.owner, si.entity,
currentTick + kBeamImpactDelayTicks});
++claimedUnits[si.entity];
++pendingByShip[o.owner];
s.cooldownTicksRemaining = s.collectionIntervalTicks;
break;
}
});
// Delivery: a ship at its assigned bay hands over one unit of cargo per tick.
m_admin.forEach<DeliverScrapBehavior, PositionComponent>(
[&](entt::entity ship, const DeliverScrapBehavior& deliver, const PositionComponent& pos)
{
if (deliver.deliveryBay == kInvalidBuildingId) { return; }
const Building* bay = buildings.findBuilding(deliver.deliveryBay);
if (!bay) { return; }
const QVector2D bayCenter(bay->anchor.x() + bay->footprint.width() / 2.0f,
bay->anchor.y() + bay->footprint.height() / 2.0f);
if ((pos.value - bayCenter).length() > 1.0f) { return; }
// Hand over one unit from the ship's shared cargo pool.
if (!m_admin.hasAll<CargoComponent>(ship)) { return; }
CargoComponent& cargo = m_admin.get<CargoComponent>(ship);
if (cargo.current <= 0) { return; }
if (buildings.deliverScrapToSalvageBay(deliver.deliveryBay))
{
--cargo.current;
}
});
}
void SalvagerSystem::applyPendingCollections(Tick currentTick, ScrapSystem& scraps)
{
std::vector<PendingCollection>::iterator it = m_pendingCollections.begin();
while (it != m_pendingCollections.end())
{
if (it->appliesAt <= currentTick)
{
if (m_admin.isValid(it->ship) && m_admin.hasAll<CargoComponent>(it->ship))
{
CargoComponent& cargo = m_admin.get<CargoComponent>(it->ship);
if (cargo.current < cargo.maxCapacity && scraps.collectOne(it->scrap))
{
++cargo.current;
}
}
it = m_pendingCollections.erase(it);
}
else
{
++it;
}
}
}

39
src/lib/ecs/system/SalvagerSystem.h
View File

@@ -1,39 +0,0 @@
#pragma once
#include <vector>
#include "BeamFiredEvent.h"
#include "Tick.h"
#include "entt/entity/entity.hpp"
class BuildingSystem;
class EntityAdmin;
class ScrapSystem;
// World-mutation system for salvage modules: each module runs a collection cycle
// on its own cooldown. When a cycle starts it emits a salvage beam toward an
// in-range scrap pile and schedules the collection of one scrap for mid-beam
// (kBeamImpactDelayTicks later) — mirroring weapon firing. Also delivers full
// cargo at a SalvageBay. Runs every tick, independent of behavior selection.
class SalvagerSystem
{
public:
explicit SalvagerSystem(EntityAdmin& admin);
void tick(Tick currentTick, ScrapSystem& scraps, BuildingSystem& buildings,
std::vector<BeamFiredEvent>& outBeamFiredEvents);
private:
struct PendingCollection
{
entt::entity ship;
entt::entity scrap;
Tick appliesAt;
};
void applyPendingCollections(Tick currentTick, ScrapSystem& scraps);
EntityAdmin& m_admin;
std::vector<PendingCollection> m_pendingCollections;
};

23
src/lib/ecs/system/ScrapSystem.cpp
View File

@@ -46,32 +46,13 @@ std::optional<int> ScrapSystem::consume(entt::entity entity)
return amount;
}
bool ScrapSystem::collectOne(entt::entity entity)
{
if (!m_admin.isValid(entity) || !m_admin.hasAll<ScrapDataComponent>(entity))
{
return false;
}
ScrapDataComponent& data = m_admin.get<ScrapDataComponent>(entity);
if (data.amount <= 0)
{
return false;
}
--data.amount;
if (data.amount <= 0)
{
m_admin.destroy(entity);
}
return true;
}
std::vector<ScrapInfo> ScrapSystem::allScrapInfo() const
{
std::vector<ScrapInfo> result;
m_admin.forEach<ScrapDataComponent>(
[&result, this](entt::entity e, const ScrapDataComponent& sd)
[&result, this](entt::entity e, const ScrapDataComponent& /*sd*/)
{
result.push_back(ScrapInfo{e, m_admin.get<PositionComponent>(e).value, sd.amount});
result.push_back(ScrapInfo{e, m_admin.get<PositionComponent>(e).value});
});
return result;
}

6
src/lib/ecs/system/ScrapSystem.h
View File

@@ -15,7 +15,6 @@ struct ScrapInfo
{
entt::entity entity;
QVector2D position;
int amount;
};
class ScrapSystem
@@ -29,11 +28,6 @@ public:
// Removes the scrap and returns its amount, or nullopt if not found.
std::optional<int> consume(entt::entity entity);
// Collects a single scrap unit from the pile: decrements its amount by one,
// destroying the entity once depleted. Returns true if a scrap was collected,
// false if the entity is invalid or already empty (REQ-SHP-SALVAGE).
bool collectOne(entt::entity entity);
// Lightweight snapshot for callers that need to iterate all scrap.
std::vector<ScrapInfo> allScrapInfo() const;

238
src/lib/ecs/system/ShipSystem.cpp
View File

@@ -1,18 +1,11 @@
#include "ShipSystem.h"
#include <algorithm>
#include <cassert>
#include <cmath>
#include <map>
#include <stdexcept>
#include <utility>
#include <vector>
#include "AdvanceBehavior.h"
#include "AttackBehavior.h"
#include "BehaviorScores.h"
#include "CargoComponent.h"
#include "DeliverScrapBehavior.h"
#include "DynamicBodyComponent.h"
#include "EntityAdmin.h"
#include "FactionComponent.h"
@@ -20,18 +13,14 @@
#include "ModuleOwnerComponent.h"
#include "ModulesConfig.h"
#include "MovementIntentComponent.h"
#include "RallyBehavior.h"
#include "RepairBehavior.h"
#include "RallyBehaviorComponent.h"
#include "RepairBehaviorComponent.h"
#include "RepairToolComponent.h"
#include "RetreatBehavior.h"
#include "SalvageScrapBehavior.h"
#include "SalvagerComponent.h"
#include "SelectedBehaviorComponent.h"
#include "SalvageBehaviorComponent.h"
#include "SalvageCargoComponent.h"
#include "SensorRangeComponent.h"
#include "ShipIdentityComponent.h"
#include "StandbyBehavior.h"
#include "ThreatCostCalculator.h"
#include "Tick.h"
#include "ThreatResponseBehaviorComponent.h"
#include "tracing.h"
#include "WeaponComponent.h"
@@ -65,66 +54,71 @@ const ModuleDef* ShipSystem::findModuleDef(const std::string& id) const
return nullptr;
}
entt::entity ShipSystem::spawn(const std::string& schematicId,
entt::entity ShipSystem::spawn(const std::string& schematicId, int level,
QVector2D position, bool isEnemy,
const std::optional<ShipLayoutConfig>& layout)
const std::optional<ShipLayoutConfig>& layout,
const std::map<std::string, int>& moduleLevelOverrides)
{
const ShipDef* def = findShipDef(schematicId);
assert(def != nullptr);
const double x = static_cast<double>(level);
const float tickRate = static_cast<float>(kTickRateHz);
const float tileSize = static_cast<float>(m_config.world.tileSize_m);
float hp = def->health.hp;
float hp = static_cast<float>(def->health.hpFormula.evaluate(x));
float maxHp = hp;
float maxSpeed_tpt = def->movement.speed_mps / tileSize / tickRate;
float mainAcceleration_tptt = def->movement.mainAcceleration_mpss / tileSize / tickRate;
float maneuveringAcceleration_tptt = def->movement.maneuveringAcceleration_mpss
float maxSpeed_tpt = static_cast<float>(def->movement.speedFormula.evaluate(x))
/ tileSize / tickRate;
float mainAcceleration_tptt = static_cast<float>(
def->movement.mainAccelerationFormula.evaluate(x))
/ tileSize / tickRate;
float maneuveringAcceleration_tptt = static_cast<float>(
def->movement.maneuveringAccelerationFormula.evaluate(x))
/ tileSize / tickRate;
float maxAngularAcceleration_rptt = def->movement.angularAcceleration_radpss / tickRate;
float maxRotationSpeed_rpt = def->movement.maxRotationSpeed_radps / tickRate;
float sensorRange_tiles = def->sensor.sensorRange_m / tileSize;
float maxAngularAcceleration_rptt = static_cast<float>(
def->movement.angularAccelerationFormula.evaluate(x))
/ tickRate;
float maxRotationSpeed_rpt = static_cast<float>(
def->movement.maxRotationSpeedFormula.evaluate(x))
/ tickRate;
float sensorRange_tiles = static_cast<float>(
def->sensor.sensorRangeFormula.evaluate(x))
/ tileSize;
entt::entity entity = m_admin.spawnShip(
position, hp, maxHp,
maxSpeed_tpt, mainAcceleration_tptt, maneuveringAcceleration_tptt,
maxAngularAcceleration_rptt, maxRotationSpeed_rpt, sensorRange_tiles,
schematicId, isEnemy);
level, schematicId, isEnemy);
// Determine module list: configured layout takes precedence over default.
const std::vector<PlacedModule>& modules =
layout.has_value() ? layout->placedModules : def->defaultModules;
// Derive the scrap dropped on destruction from the ship's as-built threat cost
// (REQ-RES-SCRAP-DROP): round(threat * scrap_per_threat), floored at 1 for any
// ship with threat > 0. Computed once here since threat is level-independent.
const double threatCost = calculateShipThreatCost(m_config.threatCosts, m_config,
schematicId, modules);
const int scrapDrop = threatCost > 0.0
? std::max(1, static_cast<int>(std::lround(threatCost * m_config.world.scrapPerThreat)))
: 0;
m_admin.get<ShipIdentityComponent>(entity).scrapDrop = scrapDrop;
// --- Pass 1: create capability child entities ----------------------------
std::vector<entt::entity> weaponChildren;
std::vector<entt::entity> salvageChildren;
std::vector<entt::entity> repairChildren;
// Cargo capacity is a ship-level stat (REQ-MOD-CARGO-CAPACITY): its base is the
// sum of every cargo-providing module's contribution, accumulated here.
double cargoCapacityBase = 0.0;
for (const PlacedModule& pm : modules)
{
const ModuleDef* modDef = findModuleDef(pm.moduleId);
if (!modDef) { throw std::runtime_error("unknown module id '" + pm.moduleId + "'"); }
const auto overIt = moduleLevelOverrides.find(pm.moduleId);
const double mx = static_cast<double>(
overIt != moduleLevelOverrides.end() ? overIt->second : modDef->playerProductionLevel);
if (modDef->weaponCapability)
{
WeaponComponent w;
w.damage = modDef->weaponCapability->damage;
w.range_tiles = modDef->weaponCapability->attackRange_m / tileSize;
w.fireRateHz = modDef->weaponCapability->attackRate_hz;
w.damage = static_cast<float>(
modDef->weaponCapability->damageFormula.evaluate(mx));
w.range_tiles = static_cast<float>(
modDef->weaponCapability->attackRangeFormula.evaluate(mx)) / tileSize;
w.fireRateHz = static_cast<float>(
modDef->weaponCapability->attackRateFormula.evaluate(mx));
w.cooldownTicks = 0.0f;
w.currentTarget = std::nullopt;
@@ -136,18 +130,20 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
if (modDef->salvageCapability)
{
cargoCapacityBase += modDef->salvageCapability->cargoCapacity;
SalvagerComponent salvager;
salvager.collectionRange_tiles = modDef->salvageCapability->collectionRange_m / tileSize;
const double rate = modDef->salvageCapability->collectionRate_hz;
salvager.collectionIntervalTicks = (rate > 0.0)
SalvageCargoComponent cargo;
cargo.capacity = static_cast<int>(
modDef->salvageCapability->cargoCapacityFormula.evaluate(mx));
cargo.current = 0;
cargo.collectionRange_tiles = static_cast<float>(
modDef->salvageCapability->collectionRangeFormula.evaluate(mx)) / tileSize;
const double rate = modDef->salvageCapability->collectionRateFormula.evaluate(mx);
cargo.collectionIntervalTicks = (rate > 0.0)
? static_cast<int>(kTickRateHz / rate + 0.5)
: 0;
salvager.cooldownTicksRemaining = 0;
cargo.cooldownTicksRemaining = 0;
entt::entity child = m_admin.createModuleEntity();
m_admin.addComponent<SalvagerComponent>(child, salvager);
m_admin.addComponent<SalvageCargoComponent>(child, cargo);
m_admin.addComponent<ModuleOwnerComponent>(child, ModuleOwnerComponent{entity});
salvageChildren.push_back(child);
}
@@ -155,13 +151,11 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
if (modDef->repairCapability)
{
RepairToolComponent rt;
const double repairRateHz = modDef->repairCapability->repairRate_hz;
rt.repairIntervalTicks = (repairRateHz > 0.0)
? static_cast<int>(kTickRateHz / repairRateHz + 0.5)
: 0;
rt.repairAmountHp = modDef->repairCapability->repairAmountHp;
rt.cooldownTicksRemaining = 0;
rt.range_tiles = modDef->repairCapability->repairRange_m / tileSize;
rt.ratePerTick = static_cast<float>(
modDef->repairCapability->repairRateFormula.evaluate(mx))
/ static_cast<float>(kTickRateHz);
rt.range_tiles = static_cast<float>(
modDef->repairCapability->repairRangeFormula.evaluate(mx)) / tileSize;
rt.currentTarget = std::nullopt;
entt::entity child = m_admin.createModuleEntity();
@@ -179,17 +173,19 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
std::map<std::string, std::pair<double, double>> weaponMods;
std::map<std::string, std::pair<double, double>> salvageMods;
std::map<std::string, std::pair<double, double>> repairMods;
// Ship-level cargo capacity modifiers ([module.cargo]); applied to the pool.
std::map<std::string, std::pair<double, double>> cargoMods;
for (const PlacedModule& pm : modules)
{
const ModuleDef* modDef = findModuleDef(pm.moduleId);
if (!modDef) { throw std::runtime_error("unknown module id '" + pm.moduleId + "'"); }
const auto overIt2 = moduleLevelOverrides.find(pm.moduleId);
const double mx = static_cast<double>(
overIt2 != moduleLevelOverrides.end() ? overIt2->second : modDef->playerProductionLevel);
for (const ModuleStatModifier& sm : modDef->statModifiers)
{
const double val = sm.value;
const double val = sm.formula.evaluate(mx);
// Route modifier to the correct accumulator by stat category.
// weapon/salvage/repair stats go to the corresponding child map;
@@ -197,16 +193,15 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
const bool isWeaponStat = (sm.stat == "damage"
|| sm.stat == "attack_range"
|| sm.stat == "attack_rate");
const bool isSalvageStat = (sm.stat == "collection_range");
const bool isSalvageStat = (sm.stat == "collection_range"
|| sm.stat == "cargo_capacity");
const bool isRepairStat = (sm.stat == "repair_rate"
|| sm.stat == "repair_range");
const bool isCargoStat = (sm.stat == "cargo_capacity");
std::map<std::string, std::pair<double, double>>* target = &hullMods;
if (isWeaponStat) { target = &weaponMods; }
if (isSalvageStat) { target = &salvageMods; }
if (isRepairStat) { target = &repairMods; }
if (isCargoStat) { target = &cargoMods; }
std::pair<double, double>& acc = (*target)[sm.stat];
if (sm.modifierType == "multiplicative")
@@ -299,86 +294,42 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
// Apply salvage modifiers to each salvage child.
for (entt::entity child : salvageChildren)
{
SalvagerComponent& c = m_admin.get<SalvagerComponent>(child);
float fRange = c.collectionRange_tiles;
SalvageCargoComponent& c = m_admin.get<SalvageCargoComponent>(child);
float fRange = c.collectionRange_tiles;
float fCapacity = static_cast<float>(c.capacity);
// Apply rate modifier: compute rate from interval, apply multiplier, convert back.
float fRate = (c.collectionIntervalTicks > 0)
? static_cast<float>(kTickRateHz) / static_cast<float>(c.collectionIntervalTicks)
: 0.0f;
applyMod(fRange, "collection_range", salvageMods);
applyMod(fRate, "collection_rate", salvageMods);
applyMod(fRange, "collection_range", salvageMods);
applyMod(fCapacity, "cargo_capacity", salvageMods);
applyMod(fRate, "collection_rate", salvageMods);
c.collectionRange_tiles = fRange;
c.capacity = static_cast<int>(fCapacity + 0.5f);
c.collectionIntervalTicks = (fRate > 0.0f)
? static_cast<int>(static_cast<float>(kTickRateHz) / fRate + 0.5f)
: 0;
}
// Cargo capacity is a ship-level stat: apply [module.cargo] modifiers to the
// summed base, then attach the shared cargo pool when the ship can hold anything
// (REQ-MOD-CARGO-CAPACITY).
{
float fCapacity = static_cast<float>(cargoCapacityBase);
applyMod(fCapacity, "cargo_capacity", cargoMods);
const int maxCapacity = static_cast<int>(fCapacity + 0.5f);
if (maxCapacity > 0)
{
m_admin.addComponent<CargoComponent>(entity, CargoComponent{maxCapacity, 0});
}
}
// Apply repair modifiers to each repair child.
for (entt::entity child : repairChildren)
{
RepairToolComponent& rt = m_admin.get<RepairToolComponent>(child);
// Apply rate modifier: compute cycles/s from interval, apply, convert back.
float fRate = (rt.repairIntervalTicks > 0)
? static_cast<float>(kTickRateHz) / static_cast<float>(rt.repairIntervalTicks)
: 0.0f;
applyMod(fRate, "repair_rate", repairMods);
applyMod(rt.range_tiles, "repair_range", repairMods);
rt.repairIntervalTicks = (fRate > 0.0f)
? static_cast<int>(static_cast<float>(kTickRateHz) / fRate + 0.5f)
: 0;
applyMod(rt.ratePerTick, "repair_rate", repairMods);
applyMod(rt.range_tiles, "repair_range", repairMods);
}
// --- Pass 3: attach behavior components based on capability presence -----
// Baseline: every ship can always fall back to advancing, and needs a slot
// for the per-tick behavior selection result.
m_admin.addComponent<AdvanceBehavior>(entity, AdvanceBehavior{});
m_admin.addComponent<SelectedBehaviorComponent>(entity, SelectedBehaviorComponent{});
// Player ships retreat to the rally point when threatened or badly damaged
// (disabled by the balancing tool to keep arena fights symmetric).
if (!isEnemy && m_retreatEnabled)
{
RetreatBehavior retreat;
retreat.retreatHpFraction = BehaviorScores::kLowHpFraction;
retreat.retreatPoint = m_rallyPoint;
m_admin.addComponent<RetreatBehavior>(entity, retreat);
}
if (!weaponChildren.empty())
{
float maxWeaponRange = 0.0f;
for (entt::entity child : weaponChildren)
{
const float r = m_admin.get<WeaponComponent>(child).range_tiles;
if (r > maxWeaponRange) { maxWeaponRange = r; }
}
AttackBehavior attack;
attack.orbitRadius_tiles =
maxWeaponRange * static_cast<float>(m_config.world.orbitFactor);
m_admin.addComponent<AttackBehavior>(entity, attack);
m_admin.addComponent<ThreatResponseBehaviorComponent>(
entity, ThreatResponseBehaviorComponent{});
if (!isEnemy)
{
RallyBehavior rally;
rally.rallyPoint = m_rallyPoint;
rally.orbitRadius_tiles =
static_cast<float>(m_config.world.rallyOrbitRadius_tiles);
m_admin.addComponent<RallyBehavior>(entity, rally);
m_admin.addComponent<RallyBehaviorComponent>(
entity, RallyBehaviorComponent{m_rallyPoint});
}
}
@@ -387,20 +338,15 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
float maxCollRange = 0.0f;
for (entt::entity child : salvageChildren)
{
const float r = m_admin.get<SalvagerComponent>(child).collectionRange_tiles;
const float r = m_admin.get<SalvageCargoComponent>(child).collectionRange_tiles;
if (r > maxCollRange) { maxCollRange = r; }
}
SalvageScrapBehavior salvage;
salvage.scrapTarget = std::nullopt;
salvage.maxCollectionRange_tiles = maxCollRange;
salvage.orbitRadius_tiles =
maxCollRange * static_cast<float>(m_config.world.orbitFactor);
m_admin.addComponent<SalvageScrapBehavior>(entity, salvage);
DeliverScrapBehavior deliver;
deliver.deliveryBay = kInvalidBuildingId;
m_admin.addComponent<DeliverScrapBehavior>(entity, deliver);
SalvageBehaviorComponent sb;
sb.scrapTarget = std::nullopt;
sb.deliveryBay = kInvalidBuildingId;
sb.maxCollectionRange_tiles = maxCollRange;
m_admin.addComponent<SalvageBehaviorComponent>(entity, sb);
}
if (!repairChildren.empty())
@@ -412,17 +358,10 @@ entt::entity ShipSystem::spawn(const std::string& schematicId,
if (r > maxRepairRange) { maxRepairRange = r; }
}
RepairBehavior repair;
repair.currentTarget = std::nullopt;
repair.maxRepairRange_tiles = maxRepairRange;
repair.orbitRadius_tiles =
maxRepairRange * static_cast<float>(m_config.world.orbitFactor);
m_admin.addComponent<RepairBehavior>(entity, repair);
// Repair-capable ships hold with the fleet (REQ-SHP-STANDBY) instead of
// charging the enemy when no more urgent behavior applies; this applies
// whether or not the ship also carries weapons.
m_admin.addComponent<StandbyBehavior>(entity, StandbyBehavior{});
RepairBehaviorComponent rb;
rb.currentTarget = std::nullopt;
rb.maxRepairRange_tiles = maxRepairRange;
m_admin.addComponent<RepairBehaviorComponent>(entity, rb);
}
return entity;
@@ -446,7 +385,7 @@ void ShipSystem::clearMovementIntents()
m_admin.forEach<MovementIntentComponent>(
[](entt::entity /*e*/, MovementIntentComponent& i)
{
i = MovementIntentComponent{false, QVector2D(0.0f, 0.0f)};
i = MovementIntentComponent{0, QVector2D(0.0f, 0.0f)};
});
}
@@ -455,17 +394,12 @@ void ShipSystem::setRallyPoint(QVector2D point)
m_rallyPoint = point;
}
void ShipSystem::setRetreatEnabled(bool enabled)
{
m_retreatEnabled = enabled;
}
void ShipSystem::triggerRallyDeparture()
{
TRACE();
std::vector<entt::entity> toRemove;
m_admin.forEach<RallyBehavior, FactionComponent>(
[&toRemove](entt::entity e, const RallyBehavior& /*rb*/,
m_admin.forEach<RallyBehaviorComponent, FactionComponent>(
[&toRemove](entt::entity e, const RallyBehaviorComponent& /*rb*/,
const FactionComponent& f)
{
if (!f.isEnemy)
@@ -475,6 +409,6 @@ void ShipSystem::triggerRallyDeparture()
});
for (entt::entity e : toRemove)
{
m_admin.removeComponent<RallyBehavior>(e);
m_admin.removeComponent<RallyBehaviorComponent>(e);
}
}

13
src/lib/ecs/system/ShipSystem.h
View File

@@ -18,12 +18,13 @@ class ShipSystem
public:
ShipSystem(const GameConfig& config, EntityAdmin& admin);
entt::entity spawn(const std::string& schematicId, QVector2D position,
entt::entity spawn(const std::string& schematicId, int level, QVector2D position,
bool isEnemy = false,
const std::optional<ShipLayoutConfig>& layout = std::nullopt);
const std::optional<ShipLayoutConfig>& layout = std::nullopt,
const std::map<std::string, int>& moduleLevelOverrides = {});
void despawn(entt::entity entity);
// Reset all movement intents to inactive before behavior systems run.
// Reset all movement intents to priority 0 before behavior systems run.
void clearMovementIntents();
// Set the rally point that newly spawned player combat ships will loiter at.
@@ -32,11 +33,6 @@ public:
// Release all gathered player combat ships to advance toward the enemy.
void triggerRallyDeparture();
// Controls whether newly spawned player ships receive a RetreatBehavior. The
// balancing tool disables this so arena fights stay symmetric and aggressive
// (REQ-BAL-SIM-AI); the main game keeps it enabled (REQ-SHP-RETREAT).
void setRetreatEnabled(bool enabled);
private:
const ShipDef* findShipDef(const std::string& schematicId) const;
const ModuleDef* findModuleDef(const std::string& id) const;
@@ -44,5 +40,4 @@ private:
const GameConfig& m_config;
EntityAdmin& m_admin;
QVector2D m_rallyPoint;
bool m_retreatEnabled = true;
};

16
src/lib/ecs/system/ai/AdvanceEvaluator.cpp
View File

@@ -1,16 +0,0 @@
#include "AdvanceEvaluator.h"
#include "AdvanceBehavior.h"
#include "BehaviorScores.h"
#include "EntityAdmin.h"
#include "tracing.h"
void AdvanceEvaluator::evaluate(EntityAdmin& admin)
{
TRACE();
admin.forEach<AdvanceBehavior>(
[](entt::entity /*e*/, AdvanceBehavior& advance)
{
advance.score = BehaviorScores::kAdvance;
});
}

11
src/lib/ecs/system/ai/AdvanceEvaluator.h
View File

@@ -1,11 +0,0 @@
#pragma once
class EntityAdmin;
// Baseline fallback: gives every ship a constant low score so there is always a
// winning behavior. The actual movement direction is decided by AdvanceExecutor.
class AdvanceEvaluator
{
public:
void evaluate(EntityAdmin& admin);
};

112
src/lib/ecs/system/ai/AdvanceExecutor.cpp
View File

@@ -1,112 +0,0 @@
#include "AdvanceExecutor.h"
#include <optional>
#include <QVector2D>
#include "AdvanceBehavior.h"
#include "BehaviorKind.h"
#include "EntityAdmin.h"
#include "FactionComponent.h"
#include "HealthComponent.h"
#include "HqProxyComponent.h"
#include "MovementIntentComponent.h"
#include "PositionComponent.h"
#include "SelectedBehaviorComponent.h"
#include "StationBodyComponent.h"
#include "tracing.h"
namespace
{
// Accumulates positions to produce their centroid (the center between them).
struct Centroid
{
QVector2D sum;
int count = 0;
void add(const QVector2D& point)
{
sum += point;
count += 1;
}
std::optional<QVector2D> value() const
{
if (count == 0) { return std::nullopt; }
return sum / static_cast<float>(count);
}
};
}
void AdvanceExecutor::execute(EntityAdmin& admin)
{
TRACE();
// Centroid of each faction's alive defence stations. In the arena the HQ is
// spawned as a station, so it is part of this centroid; in the main game the
// enemy side has only its defence stations.
Centroid enemyStations;
Centroid playerStations;
admin.forEach<StationBodyComponent, PositionComponent, FactionComponent, HealthComponent>(
[&enemyStations, &playerStations](entt::entity /*e*/,
const StationBodyComponent& /*sb*/, const PositionComponent& pos,
const FactionComponent& faction, const HealthComponent& health)
{
if (health.hp <= 0.0f) { return; }
Centroid& centroid = faction.isEnemy ? enemyStations : playerStations;
centroid.add(pos.value);
});
// Fallback target per faction: the HQ proxy (main game only), used when a side
// has lost all of its defence stations.
Centroid enemyHq;
Centroid playerHq;
admin.forEach<HqProxyComponent, PositionComponent, FactionComponent, HealthComponent>(
[&enemyHq, &playerHq](entt::entity /*e*/, const HqProxyComponent& /*hq*/,
const PositionComponent& pos, const FactionComponent& faction,
const HealthComponent& health)
{
if (health.hp <= 0.0f) { return; }
Centroid& centroid = faction.isEnemy ? enemyHq : playerHq;
centroid.add(pos.value);
});
const std::optional<QVector2D> enemyStationCenter = enemyStations.value();
const std::optional<QVector2D> playerStationCenter = playerStations.value();
const std::optional<QVector2D> enemyHqCenter = enemyHq.value();
const std::optional<QVector2D> playerHqCenter = playerHq.value();
admin.forEach<AdvanceBehavior, SelectedBehaviorComponent, PositionComponent,
FactionComponent, MovementIntentComponent>(
[&](entt::entity /*e*/, const AdvanceBehavior& /*advance*/,
const SelectedBehaviorComponent& selected, const PositionComponent& pos,
const FactionComponent& faction, MovementIntentComponent& intent)
{
if (selected.winner != BehaviorKind::Advance) { return; }
// Aim at the center between the opposing side's defence stations; fall
// back to the opposing HQ, then to an off-world point in the advance
// direction so the ship keeps moving when no target structure exists.
const std::optional<QVector2D>& stationCenter =
faction.isEnemy ? playerStationCenter : enemyStationCenter;
const std::optional<QVector2D>& hqCenter =
faction.isEnemy ? playerHqCenter : enemyHqCenter;
QVector2D target;
if (stationCenter)
{
target = *stationCenter;
}
else if (hqCenter)
{
target = *hqCenter;
}
else
{
target = faction.isEnemy
? QVector2D(-10000.0f, pos.value.y())
: QVector2D(pos.value.x() + 1000.0f, pos.value.y());
}
intent = MovementIntentComponent{true, target};
});
}

11
src/lib/ecs/system/ai/AdvanceExecutor.h
View File

@@ -1,11 +0,0 @@
#pragma once
class EntityAdmin;
// Moves a ship toward the opposing side when Advance is the winning behavior:
// player ships advance toward +x (the enemy), enemy ships toward -x (the base).
class AdvanceExecutor
{
public:
void execute(EntityAdmin& admin);
};

146
src/lib/ecs/system/ai/AttackEvaluator.cpp
View File

@@ -1,146 +0,0 @@
#include "AttackEvaluator.h"
#include <algorithm>
#include <unordered_map>
#include <vector>
#include <QVector2D>
#include "AttackBehavior.h"
#include "BehaviorScores.h"
#include "BehaviorTargeting.h"
#include "EntityAdmin.h"
#include "FactionComponent.h"
#include "ModuleOwnerComponent.h"
#include "PositionComponent.h"
#include "SensorRangeComponent.h"
#include "tracing.h"
#include "WeaponComponent.h"
#include "WorldConfig.h"
AttackEvaluator::AttackEvaluator(const WorldTargeting& targeting)
: m_targeting(&targeting)
{
}
void AttackEvaluator::evaluate(EntityAdmin& admin)
{
TRACE();
const std::vector<CombatantInfo> combatants = buildCombatants(admin);
// Pass A: the maximum weapon range per ship, used to normalise target
// distance. Ships without a weapon fall back to their sensor range below.
std::unordered_map<entt::entity, float> maxWeaponRange_tiles;
admin.forEach<WeaponComponent, ModuleOwnerComponent>(
[&maxWeaponRange_tiles](entt::entity /*we*/, const WeaponComponent& weapon,
const ModuleOwnerComponent& owner)
{
float& best = maxWeaponRange_tiles[owner.owner];
best = std::max(best, weapon.range_tiles);
});
// Pass B: claim counts, taken from every ship's current target before any
// target is reassigned this tick. Each ship reads the previous tick's claim
// state and excludes its own contribution when scoring its current target.
std::unordered_map<entt::entity, int> claimsByTarget;
admin.forEach<AttackBehavior>(
[&claimsByTarget, &admin](entt::entity /*e*/, const AttackBehavior& attack)
{
if (attack.currentTarget && admin.isValid(*attack.currentTarget))
{
++claimsByTarget[*attack.currentTarget];
}
});
// Pass C: per-ship target selection.
admin.forEach<AttackBehavior, PositionComponent, FactionComponent,
SensorRangeComponent>(
[&](entt::entity e, AttackBehavior& attack, const PositionComponent& pos,
const FactionComponent& faction, const SensorRangeComponent& sensor)
{
const float sensorRange_tiles = sensor.value_tiles;
// Distance normaliser: max weapon range, or sensor range if unarmed.
float weaponRange_tiles = sensorRange_tiles;
const auto weaponRangeIt = maxWeaponRange_tiles.find(e);
if (weaponRangeIt != maxWeaponRange_tiles.end() && weaponRangeIt->second > 0.0f)
{
weaponRange_tiles = weaponRangeIt->second;
}
// Scores a single candidate: base desirability from distance, reduced
// by the overclaim penalty. selfClaimed subtracts this ship's own claim
// so it does not penalise the target it already holds.
const auto scoreOf =
[&](const QVector2D& candidatePos, entt::entity candidate) -> float
{
const float dist = (candidatePos - pos.value).length();
const float x = dist / weaponRange_tiles;
float base = static_cast<float>(m_targeting->targetScoreFormula.evaluate(x));
base = std::max(base, 0.0f);
int claims = 0;
const auto claimIt = claimsByTarget.find(candidate);
if (claimIt != claimsByTarget.end()) { claims = claimIt->second; }
if (attack.currentTarget && candidate == *attack.currentTarget) { --claims; }
float penalty = static_cast<float>(
m_targeting->overclaimPenaltyFormula.evaluate(claims));
penalty = std::clamp(penalty, 0.0f, 1.0f);
return base * penalty;
};
// Find the best candidate among in-range enemies.
std::optional<entt::entity> bestTarget;
float bestScore = 0.0f;
for (const CombatantInfo& c : combatants)
{
if (c.entity == e) { continue; }
const bool isValidTarget = faction.isEnemy ? !c.isEnemy : c.isEnemy;
if (!isValidTarget) { continue; }
const float dist = (c.position - pos.value).length();
if (dist > sensorRange_tiles) { continue; }
const float score = scoreOf(c.position, c.entity);
if (!bestTarget || score > bestScore)
{
bestScore = score;
bestTarget = c.entity;
}
}
// Hysteresis: keep the current target if it is still valid and in
// range, unless a challenger beats its score by more than the margin.
bool keptCurrent = false;
if (attack.currentTarget)
{
const entt::entity t = *attack.currentTarget;
if (admin.isValid(t) && admin.hasAll<PositionComponent>(t))
{
const QVector2D targetPos = admin.get<PositionComponent>(t).value;
const float dist = (targetPos - pos.value).length();
if (dist <= sensorRange_tiles)
{
const float currentScore = scoreOf(targetPos, t);
const float margin = 1.0f + static_cast<float>(m_targeting->hysteresis);
if (!bestTarget || bestScore <= currentScore * margin)
{
keptCurrent = true;
}
}
}
}
if (!keptCurrent)
{
attack.currentTarget = bestTarget;
}
attack.score = attack.currentTarget
? BehaviorScores::kAttack
: BehaviorScores::kInactive;
});
}

22
src/lib/ecs/system/ai/AttackEvaluator.h
View File

@@ -1,22 +0,0 @@
#pragma once
class EntityAdmin;
struct WorldTargeting;
// Acquires/validates a combat target for ships with weapons. Scores high only
// when the ship's health is not low and a valid target is within sensor range.
//
// Target choice is claim-aware: each tick the desirability of every candidate is
// scored from a configurable distance formula and reduced by a soft overclaim
// penalty that scales with how many other ships already target it, spreading
// ships across enemies instead of dogpiling the nearest one.
class AttackEvaluator
{
public:
explicit AttackEvaluator(const WorldTargeting& targeting);
void evaluate(EntityAdmin& admin);
private:
const WorldTargeting* m_targeting;
};

69
src/lib/ecs/system/ai/AttackExecutor.cpp
View File

@@ -1,69 +0,0 @@
#include "AttackExecutor.h"
#include "AttackBehavior.h"
#include "BehaviorKind.h"
#include "DynamicBodyComponent.h"
#include "EntityAdmin.h"
#include "ModuleOwnerComponent.h"
#include "MovementIntentComponent.h"
#include "PositionComponent.h"
#include "SelectedBehaviorComponent.h"
#include "tracing.h"
#include "WeaponComponent.h"
void AttackExecutor::execute(EntityAdmin& admin)
{
TRACE();
// Ships: move toward the behavior target.
admin.forEach<AttackBehavior, SelectedBehaviorComponent, PositionComponent,
MovementIntentComponent>(
[&](entt::entity /*e*/, const AttackBehavior& attack,
const SelectedBehaviorComponent& selected, const PositionComponent& pos,
MovementIntentComponent& intent)
{
if (selected.winner != BehaviorKind::Attack) { return; }
if (!attack.currentTarget) { return; }
const entt::entity t = *attack.currentTarget;
QVector2D center = pos.value;
float radius = 0.0f;
QVector2D centerVelocity;
if (admin.isValid(t) && admin.hasAll<PositionComponent>(t))
{
center = admin.get<PositionComponent>(t).value;
radius = attack.orbitRadius_tiles;
if (admin.hasAll<DynamicBodyComponent>(t))
{
centerVelocity = admin.get<DynamicBodyComponent>(t).velocity_tpt;
}
}
intent = MovementIntentComponent{true, center, radius, centerVelocity};
});
// Weapons: assign the behavior target only if it is within this weapon's range.
admin.forEach<WeaponComponent, ModuleOwnerComponent>(
[&](entt::entity /*we*/, WeaponComponent& weapon, const ModuleOwnerComponent& owner)
{
if (!admin.hasAll<AttackBehavior, SelectedBehaviorComponent>(owner.owner))
{
return;
}
const SelectedBehaviorComponent& selected =
admin.get<SelectedBehaviorComponent>(owner.owner);
if (selected.winner != BehaviorKind::Attack) { return; }
const AttackBehavior& attack = admin.get<AttackBehavior>(owner.owner);
if (!attack.currentTarget) { return; }
const entt::entity t = *attack.currentTarget;
if (!admin.isValid(t) || !admin.hasAll<PositionComponent>(t)) { return; }
const QVector2D ownerPos = admin.get<PositionComponent>(owner.owner).value;
const float dist = (admin.get<PositionComponent>(t).value - ownerPos).length();
if (dist <= weapon.range_tiles)
{
weapon.currentTarget = t;
}
});
}

12
src/lib/ecs/system/ai/AttackExecutor.h
View File

@@ -1,12 +0,0 @@
#pragma once
class EntityAdmin;
// When Attack wins, moves the ship toward its target and assigns that target to
// each weapon that has it in range. Weapons whose range excludes the target are
// left untouched so CombatSystem can keep/acquire a closer target (no thrash).
class AttackExecutor
{
public:
void execute(EntityAdmin& admin);
};

85
src/lib/ecs/system/ai/BehaviorTargeting.cpp
View File

@@ -1,85 +0,0 @@
#include "BehaviorTargeting.h"
#include "CargoComponent.h"
#include "EntityAdmin.h"
#include "FactionComponent.h"
#include "HealthComponent.h"
#include "HqProxyComponent.h"
#include "PositionComponent.h"
#include "ShipIdentityComponent.h"
#include "StationBodyComponent.h"
std::vector<RepairableInfo> buildRepairables(EntityAdmin& admin)
{
std::vector<RepairableInfo> repairables;
admin.forEach<ShipIdentityComponent, PositionComponent, FactionComponent, HealthComponent>(
[&repairables](entt::entity e, const ShipIdentityComponent& /*si*/,
const PositionComponent& pos, const FactionComponent& f,
const HealthComponent& h)
{
repairables.push_back({e, pos.value, f.isEnemy, true, h.hp, h.maxHp});
});
admin.forEach<StationBodyComponent, PositionComponent, FactionComponent, HealthComponent>(
[&repairables, &admin](entt::entity e, const StationBodyComponent& /*sb*/,
const PositionComponent& pos, const FactionComponent& f,
const HealthComponent& h)
{
// The HQ is not a repair target — only ships and defence stations are
// (REQ-SHP-REPAIR). In the balancing arena the HQ is spawned as a station,
// so it is identified by its HqProxyComponent tag.
if (admin.hasAll<HqProxyComponent>(e)) { return; }
repairables.push_back({e, pos.value, f.isEnemy, false, h.hp, h.maxHp});
});
return repairables;
}
std::vector<CombatantInfo> buildCombatants(EntityAdmin& admin)
{
std::vector<CombatantInfo> combatants;
admin.forEach<PositionComponent, FactionComponent, ShipIdentityComponent>(
[&combatants](entt::entity e, const PositionComponent& pos,
const FactionComponent& f, const ShipIdentityComponent& /*si*/)
{
combatants.push_back({e, pos.value, f.isEnemy, false});
});
admin.forEach<PositionComponent, FactionComponent, StationBodyComponent>(
[&combatants](entt::entity e, const PositionComponent& pos,
const FactionComponent& f, const StationBodyComponent& /*sb*/)
{
combatants.push_back({e, pos.value, f.isEnemy, true});
});
admin.forEach<PositionComponent, FactionComponent, HqProxyComponent>(
[&combatants, &admin](entt::entity e, const PositionComponent& pos,
const FactionComponent& f, const HqProxyComponent& /*hq*/)
{
// An arena HQ carries both StationBodyComponent and HqProxyComponent; it
// is already listed by the station pass above, so skip it here to avoid
// counting it twice.
if (admin.hasAll<StationBodyComponent>(e)) { return; }
combatants.push_back({e, pos.value, f.isEnemy, true});
});
return combatants;
}
std::unordered_map<entt::entity, CargoState> buildCargoByShip(EntityAdmin& admin)
{
std::unordered_map<entt::entity, CargoState> cargoByShip;
admin.forEach<CargoComponent>(
[&cargoByShip](entt::entity ship, const CargoComponent& c)
{
cargoByShip[ship] = CargoState{c.current, c.maxCapacity};
});
return cargoByShip;
}
bool isCargoFull(const CargoState& cargo)
{
return cargo.capacity > 0 && cargo.current >= cargo.capacity;
}

Some files were not shown because too many files have changed in this diff Show More