ticks

AGENTS.md

@@ -104,6 +104,30 @@ To implement the RTS Civilization game, develop modular subsystems decoupled fro
               +-----------------+
 ```
 
+### 3.1 Simulation Time & Tick System
+
+The game combines continuous real-time rendering and interpolation (`deltaTime`) with a configurable **Simulation Tick** (`movement_tick_duration` in `config/game.yaml`, defaulting to `30.0` seconds at $1\times$ simulation speed):
+
+1. **Tick Timer & Speed Multiplier:**
+   - `GameManager::update` advances an internal tick timer by `deltaTime * simSpeedMultiplier`.
+   - When the timer reaches `movement_tick_duration`, a simulation tick fires (`processTickYields`).
+2. **Discrete Per-Tick Economy & Progression (`processTickYields`):**
+   - **Food & Population:** City food yield is converted into inhabitants (`food * foodToInhabitantsRatio`).
+   - **Labor (Production):** City labor yield is added to the active construction project (`currentLabor`), completing units or buildings when `laborCost` is reached, or accumulating locally if idle.
+   - **National Stockpiles:** Culture, Faith, and Gold yields from all owned cities are added to the player's national treasury.
+   - **Science & Research:** Total science generated per tick across a player's cities is applied directly to the active technology in the player's `researchQueue`.
+3. **Continuous Real-Time Unit Movement (`movement_speed`, Scaled by Tick Duration):**
+   - Units move smoothly every frame, and their movement rate is defined in **movement points (base hexes) per tick** (`movement_speed` in `config/units/*.yaml`, stored in `UnitConfig::movementSpeed` — higher values mean faster movement, e.g., `2.0` for infantry/civilian, `3.0` for galley, `4.0` for cavalry).
+   - Effective speed in hexes per second is calculated dynamically per hex segment as:
+     $$\text{hexesPerSec} = \frac{\text{movementSpeed}}{\text{tickDuration} \times \text{stepCost}} \times \text{simSpeedMultiplier}$$
+   - On flat terrain (`stepCost = 1.0`), a unit with `movementSpeed = 2.0` traverses $2.0$ hexes during one full simulation tick ($0.5$ ticks per hex).
+4. **Unit Construction & Action Durations (`action_durations`):**
+   - Unlike `movement_speed` (which is a rate per tick), unit build actions (such as `boerderij_bouwen` and `build_road` under `action_durations` in `config/units/builder.yaml`) are configured as **durations in simulation ticks** (ticks per action, accessed via `UnitConfig::getActionDuration`).
+   - Total real-time build duration in seconds is calculated as:
+     $$\text{duration} = \text{ticks} \times \text{movement\_tick\_duration}$$
+   - While building, `buildProgress` interpolates continuously from $0.0$ to $1.0$ over `duration` seconds (scaled by `simSpeedMultiplier`).
+   - Similarly, city production (`labor_cost` in `config/units/*.yaml` and `config/buildings.yaml`) and technology research (`science_cost` in `config/technologies.yaml`) progress discretely each tick based on the city/empire's per-tick yield.
+
 ---
 
 ## 4. Agents & Unit Specifications
@@ -124,7 +148,7 @@ Units are autonomous or player-directed entities traversing the hex map in real
    - **Siege:** Catapult $\rightarrow$ Trebuchet $\rightarrow$ Bombard (high bonus damage against city walls).
    - **Naval:** Galley $\rightarrow$ Caravel $\rightarrow$ Frigate $\rightarrow$ Battleship (operates only on water hexes).
 
-### 4.2 Unit Data Model (`Unit.h`)
+### 4.2 Unit Data Model (`unit.h` / `unitconfig.h`)
 ```cpp
 enum class UnitType { Settler, Worker, Warrior, Archer, Horseman, Galley };
 enum class UnitState { Idle, Moving, Attacking, Harvesting, Building, Fortified };
@@ -146,14 +170,14 @@ public:
     float health, maxHealth;
     float attackDamage;
     float defense;
-    float movementSpeed; // hexes per second
+    float movementSpeed; // movement points (base hexes) per simulation tick
     float visionRange;   // in hex radius
     
     // Path & Target
     std::vector<std::pair<int, int>> currentPath;
     int targetEntityId; // target unit or city
     
-    void update(float deltaTime);
+    void update(float deltaTime, float tickDuration, float simSpeedMultiplier);
     void commandMoveTo(int destX, int destY);
     void commandAttack(int targetId);
     void commandBuildImprovement(int improvementType);