Files

T

2026-11-08 15:42:54 +01:00

12 KiB

Raw Blame History

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

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.
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`)

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:

Strategic Commander (Empire Level):
- Assesses empire needs: expansion, military defense, economic development, or technology rush.
- Queues city construction and manages empire-wide resource allocation.
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.
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

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.
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.

12 KiB Raw Blame History