All work
Simulation engine · 2026

Maestro Engine

A data-driven grand-strategy simulation engine (Godot 4): deterministic event-driven core, Utility-AI decisions as data, acceptance-test gates on every roadmap task.

Type
Simulation engine
Year
2026
Stack
GDScript · Godot 4 · JSON content contracts
GDScriptGodot 4JSON content contractsDeterministic simulationUtility AI
Maestro Engine
The problem

Grand-strategy games need deep, deterministic simulation — but general-purpose engines don't provide it, and building one from scratch means solving scheduling, decision-making, and content architecture without losing determinism or performance.

Constraints
  • 01

    Full determinism: same seed, same inputs, bitwise-identical results — required for testing and replay.

  • 02

    Performance under load: thousands of scheduled jobs and per-country evaluations per tick.

  • 03

    Content must be addable without touching engine code.

What was built
  1. 01

    An event-driven kernel (SimClock, EventQueue, ScheduledQueue, ActivationSet, WorldState) with selectively-activating entities — idle entities cost nothing.

  2. 02

    Every decision rule runs through one weighted-equation mechanism (Utility AI); all numeric parameters live in JSON data files, never in code.

  3. 03

    A content contract: scenarios load from validated JSON through ContentSchema/ContentLoader — adding content requires zero engine changes.

  4. 04

    Entity importance is derived from world state and dependency networks alone — proven identity-blind by name-swap tests.

Engineering decisions

Acceptance gates instead of vibes

Development runs on a 39-task roadmap where each task ships with acceptance tests and, where relevant, benchmarks — e.g. a scheduler comparison ran 40,000 scheduled jobs over real economy/production load and adopted the bucket scheduler on measurements, not preference.

Zero per-tick polling

Political/compliance evaluations answer on-demand queries instead of polling every entity every tick — the benchmark for the political core measured 100 countries / 1,100 actions at ~330µs per action with zero per-tick evaluations.

Domain purity

No domain names in the engine core — all game-specific logic lives in data and content handlers. The engine audit report verifies this boundary.

Result
  • ✓

    First Working Engine milestone passed with all 5 acceptance criteria sealed in an acceptance report (external-data game, two rules through one mechanism, save/load, zero domain names, full determinism).

  • ✓

    Regression suite green across all suites; 15k+ lines of GDScript across 76 engine files.

  • ✓

    Scheduler and political-core benchmarks documented in the repo (25-Experimental-Scheduler-Benchmark.md and TASK-039 batch report).