review-main

Requirements: Python 3.12+, Nim 2.2.6+ (via nimby), OpenGL

```bash

# 1. Install Nim with nimby

curl -L https://github.com/treeform/nimby/releases/download/0.1.11/nimby-$(uname -s)-$(uname -m) -o ./nimby

chmod +x ./nimby && ./nimby use 2.2.6 && ./nimby sync -g nimby.lock

# 2. Install Python package

pip install -e .

```

```bash

# Play interactively (builds Nim library if needed)

tribal-village play

# Run with random actions (text mode)

tribal-village play --render ansi --random-actions --steps 100

# Train with CoGames/PufferLib

pip install -e .[cogames]

tribal-village train --steps 1000000 --parallel-envs 8 --num-workers 4

```

Controls: Arrow keys/WASD (move), U (use/craft), Space (pause/step), scroll (zoom), Ctrl+1-9 (control groups)

• Victory conditions: Conquest, Wonder, Relic, King of the Hill, Regicide
• Tech trees: Blacksmith upgrades, University research, Castle unique techs per civilization
• Production system: Batch training, production queues, per-unit training times, rally points
• Military commands: Attack-move, patrol, unit stances, control groups
• Economy: AoE2-style market trading, Trade Cog dock-to-dock gold generation, biome resource bonuses
• Unit mechanics: Garrisoning, Trebuchet pack/unpack, Monk conversion, Scout exploration, unit upgrades
• AI system: Role-based agents (Gatherer/Builder/Fighter) with inter-role coordination, shared threat maps, adaptive difficulty
• Terrain: Biome zones, elevation with cliffs/ramps, mud and shallow water, terrain movement speed modifiers

```python

from tribal_village_env import TribalVillageEnv

env = TribalVillageEnv(config={

'max_steps': 10000,

'render_mode': 'rgb_array', # or 'ansi'

})

obs, info = env.reset()

obs, reward, terminated, truncated, info = env.step(actions)

```

| Topic | Description |

|-------|-------------|

| [Quickstart](docs/quickstart.md) | Prerequisites, building, running, testing |

| [Game Logic](docs/game_logic.md) | Step loop, actions, entities, episode rules |

| [Action Space](docs/action_space.md) | Discrete 250 actions (verb * 25 + direction/argument) |

| [Observation Space](docs/observation_space.md) | 84 layers, 11x11 grid per agent |

| [Combat](docs/combat.md) | Combat rules, counters, siege, unit commands |

| [Economy & Respawn](docs/economy_respawn.md) | Inventory, stockpiles, markets, trade, hearts |

| [AI System](docs/ai_system.md) | AI roles, coordination, threat maps, behaviors |

| [Terrain & Biomes](docs/terrain_biomes.md) | Biomes, elevation, cliffs, mud, water depth |

| [World Generation](docs/world_generation.md) | Trading hub, rivers, biomes, spawning |

| [Configuration](docs/configuration.md) | Runtime params, compile-time constants, env vars |

| [Architecture](docs/architecture.md) | System components, module layout, build process |

| [Python API](docs/python_api.md) | Python wrapper, PufferLib integration, examples |

| [CLI & Debugging](docs/cli_and_debugging.md) | CLI usage, debugging flags |

| [Training & Replays](docs/training_and_replays.md) | Training entrypoints, replay setup |

| [Asset Pipeline](docs/asset_pipeline.md) | Asset generation workflow |

See [docs/README.md](docs/README.md) for the complete documentation index.

```

tribal_village.nim # Entry point

src/

environment.nim # Simulation core

ai_core.nim # Built-in AI

renderer.nim # Rendering

ffi.nim # C interface for Python

tribal_village_env/ # Python wrapper + CLI

data/ # Sprites, fonts, UI

```

MIT