requirements iteration

docs/requirements.md

@@ -1,92 +1,120 @@
 # Requirements
 
+## Config Files
+
+The following config files drive game parameters:
+
+- **world.config** — world dimensions, region widths, expansion amounts, building refund percentage, wave timing.
+- **buildings.config** — building block cost per building type.
+- **recipes.config** — crafting recipes: inputs, outputs, quantities, durations, and reprocessing plant probabilities.
+- **ships.config** — ship stats (HP, speed, damage, attack range, attack rate), required materials per blueprint, and whether each blueprint is available from the start or unlocked via loot.
+- **stations.config** — HP, damage, range, and fire rate for player and enemy defence stations.
+
 ## Game World
 
-- REQ-GW-1: The game world has a fixed height and scrolls horizontally.
+- REQ-GW-1: Tiles are 20×20 pixels. Items on belts are 10×10 pixels (half a tile), so each belt tile holds at most 2 items.
-- REQ-GW-2: The scrollable area extends from the asteroid's left edge to the current set of enemy defence stations.
+- REQ-GW-2: The world height (in tiles) is read from world.config.
-- REQ-GW-3: The world is divided into a tile grid. Buildings and belts occupy tiles.
+- REQ-GW-3: The world is divided into horizontal regions whose widths (in tiles) are all read from world.config:
-- REQ-GW-4: The asteroid occupies a configurable number of tile columns on the left side of the world. Additional columns can be unlocked during play (see REQ-EXP).
+  - **Asteroid** — the player's build area.
+  - **Player buffer zone** — space between the asteroid and the player's defence stations.
+  - **Contest zone** — space between the player's and enemy's defence stations. This is where combat happens.
+  - **Enemy buffer zone** — space between the enemy's defence stations and the enemy spawn boundary.
+- REQ-GW-4: The player can scroll the view horizontally from the asteroid's left edge to the current set of enemy defence stations (the enemy buffer zone is not visible).
+- REQ-GW-5: When the player destroys a set of enemy defence stations, the scrollable area is extended by a configurable number of tiles (world.config). A new enemy buffer zone of the same configurable width is added beyond the new enemy defence stations.
+- REQ-GW-6: When the player unlocks an asteroid expansion, a configurable number of tile columns (world.config) is added to the left of the asteroid.
 
 ## HQ & Game Over
 
 - REQ-HQ-1: The HQ is pre-placed at the asteroid's right edge at game start.
 - REQ-HQ-2: The HQ has a belt input port. Building blocks delivered to it are added to the global building blocks stock.
-- REQ-HQ-3: If the HQ is destroyed, the game ends and the final survival time is shown.
+- REQ-HQ-3: HQ stats (HP) are read from stations.config.
-- REQ-HQ-4: Factory buildings are never targeted or destroyed by enemies.
+- REQ-HQ-4: If the HQ is destroyed, the game ends and the final survival time is shown.
+- REQ-HQ-5: Factory buildings (other than the HQ) are never targeted or destroyed by enemies.
 
-## Building Placement
+## Building Placement & Management
 
-- REQ-BLD-1: The player places buildings from a build menu. Placement costs building blocks from the global stock.
+- REQ-BLD-1: 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.config.
-- REQ-BLD-2: Placed buildings enter a construction queue and are built one at a time. Each building takes a defined amount of time to construct.
+- REQ-BLD-2: Placed buildings enter a construction queue and are built one at a time. Each building takes a duration defined in recipes.config to construct.
 - REQ-BLD-3: Buildings can only be placed on asteroid tiles.
 - REQ-BLD-4: Shipyards must be placed at the asteroid's right edge.
+- REQ-BLD-5: Buildings can be rotated before and after placement using Q (counter-clockwise) and E (clockwise). Rotation affects the direction of the output port.
+- REQ-BLD-6: The player can demolish a placed building. Demolition returns a configurable percentage of the original building block cost (default 75%) to the global stock. The refund percentage is read from world.config.
 
-## Buildings
+## Building Types
 
-- REQ-BLD-5: **Miner** (2×2): The player selects which ore type it extracts. Produces ore indefinitely (no depletion).
+- REQ-BLD-7: **Miner** (2×2): The player selects which ore type it extracts. Produces ore at a rate defined in recipes.config. Ore never depletes.
-- REQ-BLD-6: **Smelter** (2×2): Converts ore or scrap into basic materials. No recipe selection required.
+- REQ-BLD-8: **Smelter** (2×2): Converts ore or scrap into basic materials. No recipe selection required. Inputs, outputs, and rates are defined in recipes.config.
-- REQ-BLD-7: **Assembler** (3×3): The player selects a recipe from the config-defined crafting tree. Produces the selected output item.
+- REQ-BLD-9: **Assembler** (3×3): The player selects a recipe from the config-defined crafting tree. Produces the selected output item at the rate defined in recipes.config.
-- REQ-BLD-8: **Reprocessing Plant** (3×3): Consumes scrap and produces higher-level intermediate products. Each product type has a fixed drop probability per processing cycle.
+- REQ-BLD-10: **Reprocessing Plant** (3×3): Consumes scrap per cycle (quantity from recipes.config) and produces higher-level intermediate products. Each product type has a fixed drop probability per cycle, defined in recipes.config.
-- REQ-BLD-9: **Shipyard** (4×2): The player selects a blueprint. Automatically produces one ship of that type whenever all required materials are available in its input buffer.
+- REQ-BLD-11: **Shipyard** (4×2): The player selects a blueprint. Automatically produces one ship of that type whenever all required materials are present in its input buffer. Ship material requirements are defined in ships.config.
-- REQ-BLD-10: **Belt** (1×1): Transports materials one tile at a time. Available in straight and curved variants.
+- REQ-BLD-12: **Salvage Bay** (TBD size): A dedicated drop-off point for salvage ships. Scrap delivered here is placed onto connected output belts.
-- REQ-BLD-11: **Splitter** (1×1): Splits an incoming belt into two outgoing belts.
+- REQ-BLD-13: **Belt** (1×1): Transports items. Available in straight and curved variants.
+- REQ-BLD-14: **Splitter** (1×1): Distributes incoming items alternately between two output directions. If one output is blocked, items are sent to the other output until it unblocks.
 
 ## Material Transport & Buffers
 
 - REQ-MAT-1: Materials are transported exclusively via belts and splitters.
-- REQ-MAT-2: A building accepts any material arriving from a belt feeding into it, provided that material is required by the currently selected recipe.
+- REQ-MAT-2: A building accepts items from all adjacent belt tiles whose direction points toward the building, provided the item is an input required by the currently selected recipe.
-- REQ-MAT-3: Each building has one fixed output port from which produced items are placed onto a connected outgoing belt.
+- REQ-MAT-3: Each building has one fixed output port (direction determined by rotation). Produced items are placed onto the belt at the output port.
-- REQ-MAT-4: Each building's input buffer holds up to twice the quantity of each input material needed for one production cycle.
+- REQ-MAT-4: Each building's input buffer holds up to twice the quantity of each required input material for one production cycle.
-- REQ-MAT-5: The building blocks stock is the only global inventory. All other materials exist only in building buffers or on belts.
+- REQ-MAT-5: 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.
+- REQ-MAT-6: The building blocks stock is the only global inventory. All other materials exist only in building buffers or on belt tiles.
 
 ## Resources
 
-- REQ-RES-1: Ore is extracted by miners and smelted into basic materials.
+- REQ-RES-1: Ore is extracted by miners and smelted into basic materials by smelters.
-- REQ-RES-2: Scrap is collected by salvage ships from destroyed enemy ships and delivered to the asteroid. It can be smelted (same output as ore smelting) or processed in a Reprocessing Plant.
+- REQ-RES-2: Scrap is collected by salvage ships from destroyed enemy 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.
-- REQ-RES-3: Building blocks are produced by an assembler recipe and are the only globally pooled resource.
+- REQ-RES-3: Building blocks are produced by an assembler recipe and are the only globally pooled resource. They are added to the global stock when delivered to the HQ via belt.
-- REQ-RES-4: The crafting tree (recipes, inputs, outputs, durations) is defined in a config file.
+- REQ-RES-4: All recipes, production rates, and reprocessing probabilities are defined in recipes.config.
 
 ## Ships
 
-- REQ-SHP-1: Ships are produced by shipyards and are fully autonomous; they require no player input once produced.
+- REQ-SHP-1: Ships are produced by shipyards and are fully autonomous once produced.
-- REQ-SHP-2: **Combat ships** — move right through space and engage enemy ships automatically.
+- REQ-SHP-2: All ship stats (HP, speed, damage, attack range, attack rate) and required build materials are defined in ships.config. ships.config also specifies whether each blueprint is available from game start or must be unlocked.
-- REQ-SHP-3: **Salvage ships** — move to the battlefield, collect scrap from destroyed enemy ships, and return it to the asteroid. Vulnerable to enemy ships while operating.
+- REQ-SHP-3: Ships move independently with no collision between them.
-- REQ-SHP-4: **Repair ships** — move to damaged player defence stations and player ships and repair them.
+- REQ-SHP-4: **Combat ships** — move right through space and engage enemy ships. The player can configure the following per shipyard (applied to all ships produced by that shipyard):
-- REQ-SHP-5: The player selects which blueprint a shipyard produces by clicking it and choosing from unlocked blueprints.
+  - Stance: aggressive (advance toward enemies) / defensive (hold position near asteroid).
-- REQ-SHP-6: The initial set of blueprints is available from the start. Additional blueprints are unlocked as loot from destroyed enemy defence stations.
+  - Target priority: closest / highest HP / structures first.
+- REQ-SHP-5: **Salvage ships** — move to the location of destroyed enemy ships, collect scrap, and deliver it to a Salvage Bay on the asteroid. Vulnerable to enemy ships while operating.
+- REQ-SHP-6: **Repair ships** — move to damaged player defence stations or player ships and repair them. The player can configure the target priority per shipyard:
+  - Defence stations first / ships first / nearest target.
+- REQ-SHP-7: The player selects a blueprint per shipyard by clicking it. New blueprints are unlocked as loot from destroyed enemy defence stations.
 
 ## Defence Stations
 
-- REQ-DEF-1: A set of player defence stations is pre-placed in space at the asteroid's right edge at game start.
+- REQ-DEF-1: 2 player defence stations are pre-placed in space at the start. Their positions are determined by the world region widths in world.config.
-- REQ-DEF-2: Player defence stations automatically fire at approaching enemy ships.
+- REQ-DEF-2: Player defence stations automatically fire at approaching enemy ships. Stats are read from stations.config.
 - REQ-DEF-3: Player defence stations can be destroyed by enemies and repaired by repair ships.
-- REQ-DEF-4: A set of enemy defence stations is placed at the right boundary of the scrollable area at game start.
+- REQ-DEF-4: 2 enemy defence stations are placed at the right boundary of the scrollable area at game start, and again each time a new set is spawned after a push. Stats scale with the push scaling factor (REQ-DIF-3).
-- REQ-DEF-5: Enemy defence stations automatically fire at player ships.
+- REQ-DEF-5: Enemy defence stations automatically fire at player ships within range.
-- REQ-DEF-6: When all enemy defence stations in a set are destroyed, the push scaling multiplier is applied, the scrollable area is extended, and a new (stronger) set of enemy defence stations is placed at the new boundary. The destroyed stations drop ship blueprint loot.
+- REQ-DEF-6: Enemy and player defence stations are never in each other's firing range.
+- REQ-DEF-7: When both enemy defence stations in a set are destroyed, the push scaling multiplier is applied (REQ-DIF-3), the scrollable area is extended (REQ-GW-5), and a new set of enemy defence stations is placed at the new boundary. The destroyed stations drop ship blueprint loot.
 
-## Enemy Waves
+## Threat Level & Enemy Waves
 
-- REQ-WAV-1: Enemy ships spawn in waves off-screen to the right and travel left toward the asteroid.
+- REQ-WAV-1: A global **threat level** accumulates continuously over time. The rate of increase per second is determined by a formula read from world.config where the input is elapsed game time in seconds. Example: `1*t - 30` gives 0 threat/s at t=30s and increases linearly after that.
-- REQ-WAV-2: A wave spawns its ships over a period of several seconds. After spawning completes, a configurable gap elapses before the next wave begins spawning.
+- REQ-WAV-2: At game start and immediately after each wave is triggered, a random inter-wave gap is drawn uniformly from a configurable [min, max] range (world.config, in seconds).
-- REQ-WAV-3: Waves consist of a single enemy ship type. Enemy ship stats scale with the current difficulty level.
+- REQ-WAV-3: When the gap expires, a wave is triggered. Ships are spawned using the accumulated threat level. Any threat not spent on ships carries over to the next wave. A longer gap results in a larger wave.
-- REQ-WAV-4: A grace period at game start passes before the first wave spawns.
+- REQ-WAV-4: Ships are spawned until the accumulated threat is exhausted. Each ship type has a threat cost defined as a formula in ships.config (where x is elapsed game time), so threat cost per ship can increase over time.
+- REQ-WAV-5: Ships in a wave are spawned one at a time over the spawn duration. Spawning duration is read from world.config.
+- REQ-WAV-6: Per-ship stats (damage, attack rate, range, speed) are each defined as formulas in ships.config where x is elapsed game time in seconds at the moment of spawning.
+- REQ-WAV-7: The grace period before the first wave is implicit: threat accumulates from t=0 but the first wave does not trigger until the initial gap (drawn at game start) has elapsed.
 
-## Difficulty Scaling
+## Push Scaling
 
-- REQ-DIF-1: The difficulty level is a multiplier applied to enemy ship stats.
+- REQ-PSH-1: Each time the player destroys a set of enemy defence stations, a configurable push scaling factor (world.config) is multiplied permanently into the threat level accumulation rate. This causes all subsequent waves to be larger.
-- REQ-DIF-2: **Time scaling** — the difficulty multiplier increases gradually as a function of elapsed game time.
+- REQ-PSH-2: Enemy defence station stats (HP, damage, range, fire rate) are each defined as formulas in stations.config where x is the station generation — an integer starting at 0 for the initial set and incrementing by 1 each time a new set is placed.
-- REQ-DIF-3: **Push scaling** — each time the player destroys a set of enemy defence stations, the difficulty multiplier is multiplied by a configurable push scaling factor.
+- REQ-PSH-3: Push scaling factors stack multiplicatively with each other and with the time-based threat formula.
-- REQ-DIF-4: Time scaling and push scaling stack multiplicatively.
-- REQ-DIF-5: The push scaling factor is configurable. It is the same factor applied to the strength of replacement enemy defence stations.
 
 ## Asteroid Expansion
 
-- REQ-EXP-1: The player can unlock additional asteroid tile columns by spending building blocks from the global stock.
+- REQ-EXP-1: 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-2: Each unlocked column costs a fixed, configurable amount of building blocks.
+- REQ-EXP-2: Each expansion adds a configurable number of columns (world.config) and costs a configurable amount of building blocks (world.config).
 
 ## UI
 
 - REQ-UI-1: The elapsed survival time is always visible.
 - REQ-UI-2: The current global building blocks stock is always visible.
-- REQ-UI-3: The player can click a building to inspect its contents and change its selected recipe or blueprint.
+- REQ-UI-3: The player can scroll the view horizontally across the scrollable area.
-- REQ-UI-4: The player can scroll the view horizontally across the scrollable area.
+- REQ-UI-4: The player can click a building to inspect its current contents and change its selected recipe or blueprint.
+- REQ-UI-5: When clicking a shipyard, the player can also configure stance and target priority for ships produced by that shipyard.