9 Tribes — Turn-Based Strategy Game

A turn-based strategy game with a rules-based engine, AI opponents, and a full-featured web client built on Phaser 3.

Quick Start

npm install
npm run dev

Then open the local dev server URL (printed by Vite) in your browser.

npm run build    # production build
npm test         # run the test suite

What This Is

9 Tribes is a turn-based strategy game played on a tile-based map. Each faction fields units, builds settlements, researches technologies, and battles for control of the map. The game runs in two layers:

• Engine (src/) — pure TypeScript simulation with no DOM or renderer dependencies. Handles turns, combat, movement, economy, AI, terrain, zones, and victory conditions.
• Web Client (web/) — a Phaser 3 game client that renders the engine state, handles input, and drives the game loop with animations and sound.

Architecture

Engine (src/)

The engine is organized into 10 top-level modules:

Module	Purpose
core/	Game state, events, and core data structures
systems/	Game systems (combat, simulation, AI, unit activation)
features/	Feature modules (factions, units, cities, economy, research, zones, etc.)
content/	Game content definitions (base stats, tech domains, synergies)
world/	Map generation and world data
game/	Game scenarios and setup
replay/	Replay recording and playback
data/	Data utilities and migrations
balance/	Balance tuning and constants
design/	Design documentation and type contracts

Systems (src/systems/)

Four core systems drive the game:

• Combat-Action System (12 modules) — Resolves combat actions between units with damage, capture, status effects, labels, and aftermath processing. Uses a modular phase-based approach for clear separation of concerns.
• Simulation System (17 modules) — Handles per-faction and per-round simulation: city production, codification, siege phases, faction turn effects, ecology research, emergent turn effects, environmental effects, faction auras, victory conditions, wild faction turns, and trace recording.
• Strategic AI (10 modules) — AI decision-making with awareness of technologies, synergies, zone effects, status effects, emergent rules, AoE clustering, terrain mutations, and time-sensitive decisions. Includes objective tracking, front-line analysis, posture assessment, rendezvous planning, difficulty coordination, and a learn-loop coordinator.
• Unit-Activation System (11 modules) — Manages unit activation order, movement, actions, and turn lifecycle.

Web Client (web/)

The web client is a Phaser 3 application that renders the engine state:

• Game Scene — Main game rendering and input handling
• Transition Animation System (10 modules) — Diffs state snapshots between frames and spawns smooth Phaser animations for unit movements, spawns, deaths, ownership changes, settlement builds, status effects, combat feedback, and terrain mutations
• Renderer — Tile-based map rendering with fog of war, zone effects, and status indicators
• Sound System — Audio playback for combat, movement, and UI events

Gameplay

Core Mechanics

• Turn-based combat — Units attack, defend, and maneuver on a tile-based map with terrain modifiers
• Unit types — Infantry, cavalry, archers, siege engines, and specialized units with unique stats and abilities
• Settlements — Cities and villages provide production, income, and strategic value
• Technologies — Research unlocks new unit types, abilities, and strategic advantages across multiple domains
• Synergies — Combinations of technologies, units, and zones create emergent gameplay effects
• Zone effects — Bloodtrail, Life Bloom, Citadel, Spike Line, and Decoy zones each provide unique gameplay effects
• Status effects — Poison, stealth, rout, stun, bleed, and frozen — each with persistent visual indicators
• Terrain mutations — Dynamic terrain changes that affect movement, combat, and strategy
• Formations — Units can swap formations for tactical advantages
• Transport — Units can be transported across the map with carry capacity limits
• Bombardment — Ranged attacks against settlements and fortified positions
• Submerge — Certain units can submerge and reappear
• Kill chains — Cascading combat effects when units are eliminated
• Last stand — Units can make a final stand when defeated
• T3 activation — Advanced technology units activate special abilities

Faction System

Each faction has unique units, technologies, and strategic advantages. Factions compete for map control through combat, diplomacy, and economic dominance.

AI Opponents

The AI uses a multi-layered decision system with awareness of:

• Technologies and their effects on unit capabilities
• Synergies between technologies, units, and zones
• Zone effects and their strategic implications
• Status effects and their impact on combat
• Emergent game rules and interactions
• AoE clustering for area-of-effect attacks
• Terrain mutations and their tactical value
• Time-sensitive decisions and turn urgency

The AI tracks objectives, analyzes front lines, assesses posture, plans rendezvous points, and adapts difficulty based on game state.

Victory Conditions

Victory is determined by map control, faction elimination, or special objectives defined by the game scenario.

Game Content

Unit Types

Units are defined with base stats (health, attack, defense, movement, range) and can be modified by technologies, synergies, and zone effects.

Technologies

Technologies are organized into domains and unlock new unit types, abilities, and strategic advantages. Tech effects include:

• Movement and vision bonuses
• Combat-action modifiers
• Per-turn effects
• Fog of war modifications
• Zone-of-control changes
• Formation swap abilities
• Transport carry capacity increases
• Bombardment capabilities

Zone Effects

Zone effects provide persistent area modifiers:

• Bloodtrail — Area-of-effect damage and debuffs
• Life Bloom — Healing and regeneration effects
• Citadel — Defensive bonuses and per-turn healing aura
• Spike Line — Defensive barrier with damage effects
• Decoy — Spawns real unit entities for Mirage synergy

Synergies

Synergies create emergent gameplay by combining technologies, units, and zones. Examples include:

• Tech + unit type combos that unlock special abilities
• Zone + unit type interactions that modify behavior
• Multi-tech combinations that create new effects

Technical Highlights

• 437K+ lines of TypeScript across 869 files
• 50+ engine modules across 4 core systems
• 94 unit sprites with playtest-quality art
• 57 sound effects for combat, movement, and UI
• 91 tests covering core engine logic
• Phase-based combat resolution with modular aftermath processing
• Transition animation system with snapshot diffing and Phaser tweens
• AI awareness system with 8-phase decision pipeline
• Zone effect renderer with stealth filtering and per-round ticking
• Terrain mutation animator with visual feedback
• Faction aura system with per-turn healing effects
• Replay system for recording and playback

Project Stats

Metric	Count
TypeScript files	869
Lines of code	~437K
Engine modules	50+
Unit sprites	94
Sound effects	57
Tests	91

Development

Adding New Content

• Units — Define in src/features/units/ with base stats and abilities
• Technologies — Add to src/content/domains/ with effects and prerequisites
• Zone effects — Create in src/features/zoneEffects/ with tick logic and renderer hooks
• Synergies — Define in src/content/synergies/ with trigger conditions and effects

Running Tests

npm test

Building for Production

npm run build

License

MIT