Kalcode/spaceprojectsim

Source: https://github.com/Kalcode/spaceprojectsim

What is this?

The Space Project is an agent-driven economic simulation wrapped in a native 3D client. There’s no scripted storyline and no player objective — you’re an observer (and god-mode admin) watching an economy run itself.

Every ship is an autonomous agent with its own credits, crew, fuel, cargo hold, and a GOAP planner that decides what to do next: chase the highest-margin trade route, accept a delivery contract, seek out a shipyard to retrofit, or dock and let its crew rest before morale collapses. Facilities run production recipes, degrade and self-repair, level up, and get abandoned when they go broke. Factions collect taxes and post subsidies. Populations consume food, produce labor, and pack up and leave when sentiment craters. Markets price everything off a coverage model with shortage urgency multipliers — no fixed prices anywhere.

It started as an Elixir/Phoenix prototype and was rewritten in Rust because the BEAM scheduler struggled on Windows gaming PCs. The engine (sim_core) is pure, synchronous, IO-free Rust; the Bevy client embeds it directly as a library, so the simulation and the renderer share the same ECS world with zero marshalling between them.

Scale today: ~485 live agents (282 ships · 93 facilities · 27 populations · 8 factions · 60 celestial bodies), ticking at p50 ≈ 10–20 ms inside a 125 ms budget. The architecture is built to push toward 100k+.

🌌 A note on where this is going

Nowhere, on its own — and that’s kind of the point.

This started as a fun idea: a from-scratch space economy that actually simulates itself instead of faking it. It grew way past what I expected, mostly in late-night sessions pairing with Claude. But I’m not pretending it’s a game with a roadmap, and I’m not actively pushing it toward “shippable.”

I’m putting it out under MIT because the bones are genuinely good and I’d rather someone do something with it than let it sit in a private repo. So: fork it, gut it, rename it, bolt a game on top of it, rip the economy engine out and use it somewhere else entirely. Build the thing I didn’t.

PRs and issues are welcome and I’ll look at them, but I can’t promise a cadence. If you want to take it somewhere real, see CONTRIBUTING.md — there’s a “directions you could take this” section written exactly for you.

Screenshots

Title screen — start a fresh universe or load a save.	System overview — orbital rings across Sol and neighboring systems.
Mining cluster — tumbling asteroids, foundries, and ship trails.	Outer reaches — distant belts and stations against nebula backdrops.
Live inspector — faction ledger, relations matrix, full contract board.	Events stream — market crises, dockings, deliveries, tick by tick.

What it simulates

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.

Quick start

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.

Controls

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.

Architecture

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.

Building & packaging

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.

Tech stack

• 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

Contributing

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

License

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