SOVEREIGN

A Procedural Geopolitical Simulation

Watch nations rise and fall in a living, breathing world of emergent geopolitics.

Features · Getting Started · Controls · Architecture · Roadmap · Contributing

---

Features

Procedural World Generation

• Massive maps — 2 000 × 2 000 tile worlds with per-tile data (elevation, temperature, humidity, biome, river, resource, ownership)
• Web Worker pipeline — entire terrain generation runs off the main thread with zero-copy ArrayBuffer transfers
• 26 biomes — from deep ocean and glaciers to tropical rainforests and volcanic peaks, with organic jittered boundaries
• Rivers — Minecraft-style noise zero-crossing algorithm producing primary and secondary waterways with shore tapering
• 8 resource types — Timber, Stone, Iron, Gold, Fertile Soil, Fish, Fur & Game — derived from biome, ore noise, elevation and river proximity
• Strategic locations — automatic detection of river crossings, mountain passes, straits and peninsulas scored 0–10
• Nation spawning — 12 nations placed on habitable land with procedural names, colours, flags, governments and personality traits

Tile Data System

• Struct-of-arrays — 8 typed-array layers (Float32Array / Uint8Array) instead of 4M JS objects
• WorldMap.at(x, y) — ergonomic accessor returns a TileInfo snapshot with biome, resource, owner, river, shore adjacency
• Per-tile ownership — Uint8Array layer tracking which nation owns each tile (255 = unclaimed)

Rendering & Performance

• Chunked ImageBitmap pipeline — tiles are rasterised once per view mode and cached as bitmaps
• Viewport culling — only visible chunks are drawn each frame
• Precomputed chunk layout — view switching swaps cached bitmaps into a fixed layout without recalculation
• Spatial-hash tooltip grid — O(1) strategic point lookups on hover
• { alpha: false } canvas context — lets the browser skip compositing

Seven Overlay Modes

Key	Mode	Visualises
E	Elevation	Height map (blue → green → brown → white)
T	Temperature	Heat map (blue → red)
H	Humidity	Moisture map (tan → teal)
B	Biome	Full 26-biome colour palette (default)
G	Strategic	Biome base + highlighted strategic points
R	Resource	Biome base + tinted resource deposits
P	Political	Territory colours + nation borders

State Management & Persistence

• Zustand store — single source of truth for phase routing, view mode, world data, nations
• Title screen — seed input + "New World" button with phase-based routing
• Save / Load — binary format in IndexedDB (~68 MB per 2000×2000 world)
• Tile inspector — hover tooltip showing biome · river · resource · strategic · nation (toggle: I)

Desktop & Web

• Runs as a native Electron app (Windows, macOS, Linux)
• Also ships as a static web build deployed to GitHub Pages via CI

---

Getting Started

Prerequisites

• Node.js 18+ and npm
• Git

Install

git clone https://github.com/CodeByBryant/Sovereign.git
cd Sovereign
npm install

Run

# Electron (desktop)
npm run dev

# Web-only (Vite dev server)
npm run dev:web

Build

# Web build → dist/
npm run build:web

# Desktop build + package
npm run build
npm run package

# Platform-specific installers
npm run build:win
npm run build:mac
npm run build:linux

---

Controls

Input	Action
Click + drag	Pan the camera
Scroll wheel	Zoom in / out
E	Elevation overlay
T	Temperature overlay
H	Humidity overlay
B	Biome overlay
G	Strategic overlay
R	Resource overlay
P	Political overlay
I	Toggle tile inspector
S	Toggle toolbar

---

Architecture

sovereign/
├── electron/                # Electron main + preload
│   ├── main/
│   └── preload/
├── src/
│   ├── config/
│   │   └── Config.ts        # Every tunable parameter in one place
│   ├── core/
│   │   ├── ai/              # (Phase 4+) AI decision systems
│   │   ├── camera/
│   │   │   └── Camera.ts    # Pan / zoom state
│   │   ├── entities/
│   │   │   ├── Nation.ts          # Nation class (provinces, stats, personality)
│   │   │   ├── NameGenerator.ts   # Procedural nation names
│   │   │   ├── ColorGenerator.ts  # Golden-angle colour spacing
│   │   │   └── FlagGenerator.ts   # Procedural flag patterns
│   │   ├── rendering/
│   │   │   └── Renderer.ts  # Chunked Canvas 2D draw loop
│   │   ├── simulation/
│   │   │   └── Simulation.ts
│   │   ├── state/
│   │   │   ├── GameStore.ts      # Zustand global store
│   │   │   └── persistence.ts    # IndexedDB save / load
│   │   ├── systems/
│   │   │   └── NationSpawner.ts  # Greedy spawn + territory claiming
│   │   ├── terrain/
│   │   │   ├── biomes.ts           # 26-biome classifier
│   │   │   ├── rivers.ts           # Noise zero-crossing rivers
│   │   │   ├── resources.ts        # 8 resource types generator
│   │   │   ├── strategic.ts        # Strategic point detection
│   │   │   ├── terrain.worker.ts   # Web Worker pipeline
│   │   │   └── TerrainGenerator.ts # Orchestrates all layers
│   │   └── world/
│   │       └── WorldMap.ts   # Struct-of-arrays tile storage
│   ├── styles/               # SCSS w/ tokens, mixins, components
│   ├── types/
│   │   ├── resources.ts      # ResourceType enum + metadata
│   │   └── tile.ts           # TileInfo / TileData interfaces
│   └── ui/
│       ├── App.tsx           # Phase router
│       ├── MapView.tsx       # Canvas + toolbar + tooltip + worker
│       ├── TitleScreen.tsx   # Seed input + New World
│       └── main.tsx          # Entry point
├── public/                   # Static assets
├── docs/                     # Documentation
│   ├── architecture.md
│   ├── terrain.md
│   ├── nations.md
│   └── save-load.md
├── electron-builder.yml      # Desktop packaging config
├── electron.vite.config.ts
└── vite.config.ts            # Web-only Vite config

---

Roadmap

Phase 1 — Terrain Generation ✅

• Seeded simplex noise (elevation, temperature, humidity)
• 26-biome classification with organic jitter
• Chunked ImageBitmap rendering with viewport culling
• Camera pan & zoom
• River generation (primary + secondary waterways)
• Strategic point detection (river crossings, mountain passes, straits, peninsulas)
• Web Worker terrain pipeline with zero-copy transfers
• JSDoc documentation across all modules

Phase 2 — Foundation & Nation Spawning ✅

• Struct-of-arrays tile data (WorldMap)
• 8 resource types derived from biome, ore noise, elevation & rivers
• Title screen with seed input
• Zustand state management + phase routing
• Save / Load via IndexedDB (binary format)
• Seven overlay modes (Elevation, Temperature, Humidity, Biome, Strategic, Resource, Political)
• Tile inspector tooltip
• Nation entity system with procedural names, colours, flags & personality
• Greedy spawn placement + 5 × 5 starting territories
• Political map overlay with territory colouring

Phase 3 — Expansion & Borders

• Organic expansion algorithm with terrain costs
• Border detection & rendering
• Natural borders (rivers, mountain ranges)
• Collision / conflict resolution

Phase 4+ — Simulation Loop

• Population, economy & technology growth
• Diplomacy & alliances
• Warfare (province-by-province conquest)
• Religion & culture spread
• AI decision-making (Top-K / Top-P sampling)
• God Mode (intervention tools)
• Historical timeline & statistics

See individual phase docs in docs/ for details.

---

Contributing

Contributions are welcome! The project is in early development.

1. Fork the repository
2. Create a feature branch — git checkout -b feature/your-feature
3. Commit your changes — git commit -m 'Add your feature'
4. Push — git push origin feature/your-feature
5. Open a Pull Request

Guidelines

• TypeScript strict mode
• ESLint + Prettier — npm run lint:fix && npm run format
• Meaningful commit messages
• Update docs when adding features

---

License

MIT — Copyright (c) 2026 Bryant Ejorh

---

Inspired by Ages of Conflict, WorldBox and grand strategy games

Built with Electron · React · TypeScript · simplex-noise