236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
# 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.
|