Dominium/README.md

dominium

Deterministic mean-field simulator with vector agents — civilization, faith, war and money emerge from the arithmetic — in Rust, with a Llimphi UI.

dominium is a bit-for-bit deterministic simulator: thousands of vector agents (lemmings) live on a dense numeric substrate of five physical layers (materia, psique, poder, oro, degradacion), acting through six atomic actions (move, take, drop, transmit, attack, rest). Nobody scripts a society — the engine only adds floats, and civilization, belief, conflict and trade come out of the coupling. Concepts (church, bank, commune, lab) are metaprogrammable field emitters loaded as JSON at runtime: rewrite the domain without recompiling.

_{a live mean-field run — the isometric continent, thousands of lemmings, Concepts emitting their fields, and ψ-cluster recoloring}

Run

# deterministic headless CLI
cargo run --release -p dominium-cli -- run --seed 42 --ticks 1000

# the live Llimphi app — isometric canvas + control panel (play/pause/reseed, sliders)
cargo run --release -p dominium-app-llimphi

Install

cargo build --release
# binaries land in target/release/

• Linux / macOS / Windows — Llimphi UI.
• Wawa / WASM — dominium-core, dominium-physics, dominium-iso, dominium-render-plan compile with zero graphical deps.
• Web — via dominium-notebook-kernel (a pluma notebook kernel).

Crates

Crate	Role
dominium-core	Data + the six atomic actions + Concepts + worldgen. SoA grid of 5 layers, vector lemmings. Only serde + libm.
dominium-physics	The 6-phase tick: field diffusion + entropy + transitions, actions, aging. Bit-exact.
dominium-sim	Frontend-agnostic simulation session: World + clock (tick/epoch/seed) + snapshot ring (rewind) + trails + k-means clusters.
dominium-iso	CPU pseudo-3D isometric projection: fixed iso matrix + composite Z from 5 layers + analytic Lambert shadows.
dominium-render-plan	World → depth-sorted Vec<Quad>, ready for any backend.
dominium-canvas-llimphi	Llimphi/vello backend: a RenderPlan → View<Msg> with paint_with.
dominium-app-llimphi	The app — canvas + stats panel + play/pause/reseed, tick loop on its own thread re-entering via Handle::dispatch.
dominium-cli	Headless runner: cross-platform determinism checks, per-tick stats CSV, Concept packs.
dominium-notebook-kernel	Notebook kernel running cells over a World (5 languages: world/seed/tick/stats/param) on shared state.

The chain core → physics → iso → render-plan is fully graphics-free; only the *-llimphi crates pull the GPU UI stack.

How dependencies work

dominium is a full app. Llimphi (the sovereign GPU engine: Elm loop, theme, widgets) and every foundational dependency are pulled as git dependencies from the tawasuyu monorepo — the suite's source of truth. The simulation crates (dominium-core/physics/sim/iso/render-plan) are pure compute and depend only on serde + libm; the UI crates pull the GPU stack via git-dep.

Considerations

• Inviolable rule: zero graphical deps in core / physics / iso / render-plan. Only serde and libm. Graphics live in canvas-llimphi / app-llimphi.
• Bit-for-bit deterministic given the same seed and the same version.
• Concepts load at runtime (id + pos + radius + mods + hack); the engine stays dumb, external AI is optional. They let you rewrite the domain without recompiling.
• Everything non-fixed is data. SimParams / ZWeights are serializable and live-editable from panel sliders; a whole scenario (params + relief + Concepts) serializes as one.

License

MIT. Builds on Llimphi and the tawasuyu suite.