convert concept to requirements

docs/requirements.md

@@ -0,0 +1,92 @@
+# Requirements
+
+## Game World
+
+- REQ-GW-1: The game world has a fixed height and scrolls horizontally.
+- REQ-GW-2: The scrollable area extends from the asteroid's left edge to the current set of enemy defence stations.
+- REQ-GW-3: The world is divided into a tile grid. Buildings and belts occupy tiles.
+- 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).
+
+## 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-4: Factory buildings are never targeted or destroyed by enemies.
+
+## Building Placement
+
+- REQ-BLD-1: The player places buildings from a build menu. Placement costs building blocks from the global stock.
+- 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-3: Buildings can only be placed on asteroid tiles.
+- REQ-BLD-4: Shipyards must be placed at the asteroid's right edge.
+
+## Buildings
+
+- REQ-BLD-5: **Miner** (2×2): The player selects which ore type it extracts. Produces ore indefinitely (no depletion).
+- REQ-BLD-6: **Smelter** (2×2): Converts ore or scrap into basic materials. No recipe selection required.
+- REQ-BLD-7: **Assembler** (3×3): The player selects a recipe from the config-defined crafting tree. Produces the selected output item.
+- 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-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-10: **Belt** (1×1): Transports materials one tile at a time. Available in straight and curved variants.
+- REQ-BLD-11: **Splitter** (1×1): Splits an incoming belt into two outgoing belts.
+
+## 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-3: Each building has one fixed output port from which produced items are placed onto a connected outgoing belt.
+- 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-5: The building blocks stock is the only global inventory. All other materials exist only in building buffers or on belts.
+
+## Resources
+
+- REQ-RES-1: Ore is extracted by miners and smelted into basic materials.
+- 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-3: Building blocks are produced by an assembler recipe and are the only globally pooled resource.
+- REQ-RES-4: The crafting tree (recipes, inputs, outputs, durations) is defined in a config file.
+
+## Ships
+
+- REQ-SHP-1: Ships are produced by shipyards and are fully autonomous; they require no player input once produced.
+- REQ-SHP-2: **Combat ships** — move right through space and engage enemy ships automatically.
+- 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-4: **Repair ships** — move to damaged player defence stations and player ships and repair them.
+- REQ-SHP-5: The player selects which blueprint a shipyard produces by clicking it and choosing from unlocked blueprints.
+- REQ-SHP-6: The initial set of blueprints is available from the start. Additional 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-2: Player defence stations automatically fire at approaching enemy ships.
+- 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-5: Enemy defence stations automatically fire at player ships.
+- 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.
+
+## Enemy Waves
+
+- REQ-WAV-1: Enemy ships spawn in waves off-screen to the right and travel left toward the asteroid.
+- 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-3: Waves consist of a single enemy ship type. Enemy ship stats scale with the current difficulty level.
+- REQ-WAV-4: A grace period at game start passes before the first wave spawns.
+
+## Difficulty Scaling
+
+- REQ-DIF-1: The difficulty level is a multiplier applied to enemy ship stats.
+- REQ-DIF-2: **Time scaling** — the difficulty multiplier increases gradually as a function of elapsed game time.
+- 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-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-2: Each unlocked column costs a fixed, configurable amount of building blocks.
+
+## 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-4: The player can scroll the view horizontally across the scrollable area.