# AGENTS.md — RTS Civilization Game Engine Architecture & Roadmap

This document serves as the primary technical specification, architecture reference, and development guide for AI agents and developers implementing an **RTS Civilization** game (Real-Time Strategy / 4X hybrid) on top of this hexagonal 3D terrain engine.

---

## 1. Project Vision & Core Concept

**Goal:** Transform this 3D hexagonal terrain engine into a seamless **Real-Time Strategy Civilization** game.

### Gameplay Formula:
- **Civilization Depth (4X):** Hex-based empire building, city founding, tile improvements (farms, mines, lumber mills), territory border expansion, technology tree, and resource economy (Food, Production, Gold, Science, Culture).
- **RTS Dynamics:** Continuous real-time simulation (with pause/speed controls) rather than strict turn-waiting. Units move, scout, build, and fight in real time with tactical unit control, responsive pathfinding, and dynamic skirmishes.
- **Visual Realism:** Modern OpenGL 4.0 rendering with realistic heightmaps, animated procedural water, smooth multi-biome blending (grassland, forest, desert, tundra, red rock canyon, snow-capped mountains), and hex-edge river networks.

---

## 2. Existing Codebase Architecture

The project is built on **C++**, **Qt (Widgets & OpenGL)**, and **OpenGL 4.0 Core Profile**.

### Key Source Files & Responsibilities:
- `terrain.h`:
  - Map dimensions: `MAP_WIDTH = 300`, `MAP_HEIGHT = 125` (total 37,500 hexagons).
  - Hex geometry constants: `LOD_0_SIZE = 1.0f`, `LOD_0_SIZE_Y = 0.4328799f`.
  - Staggered column neighbor resolution: `getHexNeighbor(x, y, edge, &nx, &ny)`.
  - Edge midpoints: `getHexEdgeMidpoint(edge)` for river routing.
  - Data structure `TerrainPoint`: height, biome type, river flags.
- `tile.h` & `tile.cpp`:
  - Hexagon subdivision into triangles (LOD system: 6 base triangles subdivided $\times 4 \times 4 = 96$ triangles per hex).
  - Per-vertex elevation sampling from `heightmap.jpg` (scaled to $3.5\text{ km}$ peak height) with riverbed depression carving.
  - Smooth neighbor-aware normal generation across hex seams.
  - Triplanar texture binding: grass, rock cliff, sand beach, animated water, snow, sahara, tundra, red sand, red rock canyon, and woodland forest.
- `qscenerenderer.h` & `qscenerenderer.cpp`:
  - `QOpenGLWidget` subclass managing camera view, rotation, and mouse interaction.
  - Interactive orthographic hex-tile minimap with camera viewport outline, drag-to-pan, and zoom controls.
- `shaders/simple.vert` & `shaders/simple.frag`:
  - GLSL 400 shaders.
  - Biome typemap sampling and altitude/latitude-based snowline ($2.5\text{ km}$ temperate, down to sea-level at polar caps).
  - Procedural dynamic dual-wave ocean and riverbed water rendering.
- `generate_rivers.py`:
  - Python map preprocessor for strict hex-edge river connectivity and orthographic minimap generation.

### Coordinate Systems:
- **Grid Coordinates:** `(tx, ty)` with $0 \le tx < 300$ and $0 \le ty < 125$.
- **World Coordinates:**
  $$\text{worldX} = tx \times 0.75$$
  $$\text{worldY} = ty \times (2.0 \times \text{LOD\_0\_SIZE\_Y}) + (tx \% 2 == 0 \; ? \; 0.0 : \text{LOD\_0\_SIZE\_Y})$$
- **Elevation (Z):** $0.0$ at sea level; land rises up to $\approx 3.5\text{ km}$.

---

## 3. Game Systems Architecture

To implement the RTS Civilization game, develop modular subsystems decoupled from the raw rendering loop:

```
                      +-------------------+
                      |    GameManager    |
                      +---------+---------+
                                |
     +-----------------+--------+--------+-----------------+
     |                 |                 |                 |
+----+----+      +-----+-----+     +-----+-----+     +-----+-----+
| Faction |      |   Unit    |     |   City    |     | Economy & |
| Manager |      |  Manager  |     |  Manager  |     | Tech Tree |
+----+----+      +-----+-----+     +-----+-----+     +-----+-----+
     |                 |                 |                 |
     |         +-------+-------+         |                 |
     |         |  Pathfinding  |         |                 |
     |         |   (Hex A*)    |         |                 |
     |         +---------------+         |                 |
     +-----------------+-----------------+                 |
                       |                                   |
              +--------+--------+                          |
              | Fog of War /    |                          |
              | Visibility      |<-------------------------+
              +--------+--------+
                       |
              +--------+--------+
              | QSceneRenderer  | (OpenGL Viewport + UI Overlays)
              +-----------------+
```

---

## 4. Agents & Unit Specifications

Units are autonomous or player-directed entities traversing the hex map in real time.

### 4.1 Unit Types

1. **Civilian Units:**
   - **Settler:** Consumed to found a new City Center on valid land tiles (cannot settle on water or mountains).
   - **Worker / Builder:** Constructs tile improvements (Farms, Mines, Lumber Mills, Quarries, Roads) and repairs pillaged tiles. Can be automated via worker AI.
   - **Trader / Caravan:** Establishes land or sea trade routes between cities, providing continuous Gold, Food, and Production.

2. **Military Units (RTS Combat):**
   - **Melee:** Scout $\rightarrow$ Warrior $\rightarrow$ Swordsman $\rightarrow$ Musketman $\rightarrow$ Infantry.
   - **Ranged:** Archer $\rightarrow$ Crossbowman $\rightarrow$ Field Cannon $\rightarrow$ Artillery.
   - **Cavalry:** Horseman $\rightarrow$ Knight $\rightarrow$ Cavalry $\rightarrow$ Tank (high movement speed, flanking bonuses).
   - **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`)
```cpp
enum class UnitType { Settler, Worker, Warrior, Archer, Horseman, Galley };
enum class UnitState { Idle, Moving, Attacking, Harvesting, Building, Fortified };

class Unit {
public:
    int id;
    int factionId;
    UnitType type;
    UnitState state;
    
    // Grid Position & Smooth Real-time World Position
    int tileX, tileY;
    QVector3D worldPosition;
    QVector3D targetPosition;
    float moveProgress; // 0.0 to 1.0 between hexes
    
    // Attributes
    float health, maxHealth;
    float attackDamage;
    float defense;
    float movementSpeed; // hexes per second
    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 commandMoveTo(int destX, int destY);
    void commandAttack(int targetId);
    void commandBuildImprovement(int improvementType);
};
```

### 4.3 Real-time Hex Pathfinding (`Pathfinder.h`)
- Implement **A\*** over the hexagonal grid with cost functions:
  - **Flatland (Grassland/Plains):** Base cost $1.0$.
  - **Forest / Jungle:** Cost $2.0$.
  - **Hills:** Cost $2.0$.
  - **River Crossing:** Penalty $+1.5$ (unless road/bridge is present).
  - **Mountain / Deep Water:** Impassable for land units.
  - **Friendly vs Enemy Hexes:** ZOC (Zone of Control) penalties near hostile military units.

---

## 5. Cities, Territory & Improvements

### 5.1 City Architecture
- **City Founding:** Consumes a Settler. Claims the center hex and immediate ring of 6 adjacent hexes.
- **Borders:** Expanding territory based on accumulated Culture.
- **Hex Yields:**
  - **Food:** Drives city population growth ($Pop = 1, 2, 3 \dots$).
  - **Production (Hammers):** Contributes to the active construction queue (units, buildings, wonders).
  - **Gold:** Empire treasury for unit upkeep, tile purchasing, and rush production.
  - **Science:** Advances active technology research in real time.
  - **Culture:** Expands borders and advances civics/policies.

### 5.2 Tile Improvements
- **Farm:** Built on Grassland/Plains/Floodplains ($+2\text{ Food}$, river adjacency bonus).
- **Mine:** Built on Hills ($+2\text{ Production}$).
- **Lumber Mill:** Built on Forest ($+1\text{ Production}$, preserves forest defense).
- **Road:** Built along hex edges/centers to reduce movement cost to $0.33$.

---

## 6. AI Agent Behavior (Civilization Empire AI)

AI opponents must operate through a hierarchical decision architecture:

1. **Strategic Commander (Empire Level):**
   - Assesses empire needs: expansion, military defense, economic development, or technology rush.
   - Queues city construction and manages empire-wide resource allocation.
2. **Operational Commander (Theater Level):**
   - Coordinates multi-unit formations (e.g. Settler with Warrior escort; army squads containing front-line melee and rear-line archers).
   - Manages tactical skirmishes, city sieges, and territorial defense.
3. **Tactical Agent (Unit Level):**
   - Implements Utility AI or Behavior Trees:
     - Worker AI: evaluates unworked tiles in city radius and constructs optimal improvements.
     - Scout AI: moves toward unrevealed fog of war while avoiding hostile barbarians.
     - Military AI: attacks vulnerable targets, retreats when health drops below $30\%$, uses terrain defense bonuses.

---

## 7. Fog of War & Vision System

1. **Three Visibility States:**
   - **Unexplored (Black):** Never seen. No terrain, no entities.
   - **Explored / Fog of War (Grayscale/Dimmed):** Previously discovered terrain and static cities visible; enemy units hidden.
   - **Visible (Full Color):** Currently within line-of-sight of any friendly unit or city.
2. **GPU Texture Mask:**
   - Maintain a $300 \times 125$ texture updated on the CPU / compute shader representing visibility $(0 = \text{black}, 128 = \text{fog}, 255 = \text{visible})$.
   - Sample this mask in `simple.frag` to dim or mask terrain and hide out-of-vision units.

---

## 8. Implementation Roadmap

### Phase 1: Core Simulation Loop & Pathfinding
- [ ] Create `GameSimulation` class with fixed-tick update (e.g., 20 ticks/sec).
- [ ] Implement hex A* pathfinding (`Pathfinder.h/.cpp`) using `getHexNeighbor`.
- [ ] Add basic `Unit` class with real-time waypoint interpolation across hex centers.
- [ ] Implement mouse raycasting / hex picking from screen click to `(tx, ty)`.

### Phase 2: Unit Rendering & RTS Controls
- [ ] Render 3D unit meshes / billboards on tile surfaces at correct elevation $Z$.
- [ ] Implement standard RTS controls: Left-click select, box-select, right-click move/attack.
- [ ] Add unit health bars, selection rings, and minimap unit dots.

### Phase 3: Cities & Tile Improvements
- [ ] Implement `City` class, city founding with Settler, and territory border rendering.
- [ ] Add Worker unit improvement actions (Farm, Mine, Road).
- [ ] Implement resource yield accumulation (Food, Production, Gold, Science).

### Phase 4: Combat, Technology & Opponent AI
- [ ] Implement real-time combat calculation, ranged attack trajectories, and damage resolution.
- [ ] Add Technology Tree interface and research progression.
- [ ] Implement AI Factions and Barbarian encampments.

---

## 9. Coding Guidelines for Agents & Developers

- **Language Standard:** C++17 with Qt 5/6 framework.
- **Rendering Thread Safety:** Game logic and pathfinding must run synchronously or safely decoupled from `paintGL()`. Never call OpenGL functions outside the OpenGL context thread.
- **Memory Management:** Use RAII and smart pointers (`std::unique_ptr`, `std::shared_ptr`) for entities. Avoid raw manual array allocations in game loop updates.
- **Performance:**
  - With 37,500 hexes, avoid iterating all hexes every frame. Use spatial partitioning or chunking for unit queries.
  - Batch unit rendering using instanced OpenGL draw calls (`glDrawArraysInstanced` or `glDrawElementsInstanced`).
- **Math Consistency:** Always use `terrain.h` helper functions (`getHexNeighbor`, `getHexEdgeMidpoint`, `LOD_0_SIZE_Y`) to maintain consistent geometry and alignment with the terrain mesh.