For the deep dive — tick phase ordering, the AI stack, the economic feedback loop, runtime ownership — see docs/ARCHITECTURE.md, which has mermaid diagrams for all of it.

You need a Rust toolchain (stable). Then:

make run
# equivalent to: cargo run -p client_bevy

That boots the Bevy app into the main menu. Start opens a fresh universe (name it, or take the default); Load Game lists every save in the binary's directory. Saves live next to the binary as <universe-name>.db — default sim.db.

Other entry points:

One binary, one process. client_bevy is the whole thing — the simulation runs in-process. Headless mode spins up the HTTP/WebSocket server (from the sim_server library crate) for scripted and CI use; there is no separate server binary to run.

Every panel reads the ECS world live — the inspector is effectively a real-time debugger with full component access. Click a ship to see its credits, crew, fuel, current goal, fitting, route memory, and its last few AI commands.

Five crates in one Cargo workspace:

sim_core     Pure simulation logic — hecs ECS, GOAP planner, economy,
             contracts. No async, no IO, no framework. Trivially testable.
sim_db       SQLite persistence (sqlx) — pool, seeder, ECS loader,
             persistence worker, migrations.
sim_server   Library crate — HTTP/WebSocket handlers + engine apply
             helpers. Drives headless mode; embedded by the client.
sim_protocol WebSocket wire types (headless / CI only).
client_bevy  The binary. Bevy 0.18 + egui. Embeds sim_core as a Bevy
             Resource; the renderer queries the hecs world directly.

Three rules keep it honest:

1. sim_core never imports tokio, sqlx, or axum. Pure logic only, so the whole simulation is reasoned about and unit-tested without async.
2. hecs is the source of truth during a tick. The tick loop holds exclusive mutable access — no per-agent locks.
3. Cross-entity effects go through a command buffer (SimCommand). A phase reads world state and writes commands; the next phase applies them. Deterministic, no mid-phase write conflicts.

The full tick phase order, ownership model, and feedback loops are diagrammed in docs/ARCHITECTURE.md.

The original Godot client lives on in history as a parity reference, but it's no longer the front end — the pivot to an embedded Bevy client removed the socket boundary entirely, and every feature now lands in client_bevy.

The Makefile wraps cargo + rustup + codesign + packaging:

make build              # release binary (host target)
make build-mac          # arm64 macOS  (also: build-mac-intel, build-mac-universal)
make build-win          # Windows MSVC (run on a Windows host)
make build-linux        # Linux        (best on a Linux host)

make package-mac        # .app bundle + ad-hoc codesign + Info.plist
make dmg                # macOS .dmg
make package-win        # Windows .zip
make package-linux      # Linux .tar.gz

The workspace version in the root Cargo.toml is the single source of truth — the binary reads it via env!("CARGO_PKG_VERSION") and the Makefile greps the same field for Info.plist and archive names, so packaged builds never drift.

• Rust (edition 2021) — the whole thing
• Bevy 0.18 — renderer, ECS-driven main loop, custom WGSL shaders (procedural planets, sun corona, nebulae, starfield)
• hecs — the simulation's own ECS (separate from Bevy's, deliberately)
• egui (via bevy_egui) — every inspector panel
• bevy_hanabi — GPU particle trails and explosions
• sqlx + SQLite — persistence, bundled so there's no runtime dependency
• axum + tokio — the headless HTTP/WebSocket harness

Contributions are welcome — see CONTRIBUTING.md for dev setup, the conventions that keep the codebase clean, and a list of concrete directions if you want to take this somewhere real.

The fastest sanity check before any PR:

make verify   # build + ~250 tests + clippy, strict

MIT © 2026 Kalcode (David Clausen). Do whatever you like with it.

_{Built for fun in Rust & Bevy · By Kalcode & Claude · Made with ❤️ in Illinois}