Moirai

Moirai is a small, deterministic, single-threaded entity-component-system library for constrained and headless games. It combines checked world construction, validated schedules, prepared queries, typed events, fixed-step execution, diagnostics, and replay support in a no_std + alloc crate.

Status: Moirai 0.1 is pre-1.0. The core API is usable, but minor 0.x releases may make breaking public-API changes. CI checks the feature matrix, Rust 1.75 support, Rustdoc, dependency policy, source coverage, and benchmark compilation.

Single-threaded · no_std + alloc by default · zero runtime dependencies · checked schedules · deterministic replay

When Moirai fits

Use Moirai when you want an ECS that is:

• deterministic across entity allocation, schedule order, queries, events, and replay;
• explicit about component storage, system dependencies, event retention, and fixed-step policy;
• validated before execution for invalid schemas, missing dependencies, and schedule cycles;
• explicit about owner-scoped handles that reject cross-world or cross-schedule use;
• usable without std, threads, reflection, or an engine runtime; and
• designed for constrained devices while still supporting headless verification.

Moirai owns ECS data and execution. Your host owns input, rendering, audio, networking, persistence, and platform integration. The crate does not require a particular game engine or async runtime.

Quickstart

Prerequisites

• Rust 1.75 or later

Add Moirai to your project:

cargo add moirai-for-games --rename moirai

This writes a dependency entry like:

[dependencies]
moirai = { package = "moirai-for-games", version = "0.1" }

Run your first app

Create an application with one resource and one update system:

use moirai::prelude::*;
use moirai::stage;

#[derive(Debug, PartialEq)]
struct Counter(u32);

let mut builder = AppBuilder::new();
builder.insert_resource(Counter(0));
builder
    .add_system(System::new("increment", stage::UPDATE, |world, _dt| {
        world
            .resource_mut::<Counter>()
            .expect("registered resource")
            .expect("seeded resource")
            .0 += 1;
    }))
    .expect("valid system");

let mut app = builder.build().expect("valid app");
app.update(1.0 / 60.0).expect("update");

assert_eq!(app.world().world_tick().raw(), 1);
assert_eq!(app.world().resource::<Counter>().unwrap(), Some(&Counter(1)));

AppBuilder validates the world and schedule together. App::update advances the world tick and runs the built-in update stages in their checked order.

How execution works

The standard builder separates application construction from execution:

AppBuilder
├─ WorldBuilder: components, resources, events, initial data
└─ ScheduleBuilder: stages, systems, sets, conditions, ordering
          │
          └─ build validates ownership and execution contracts
                         │
                         ▼
                        App
        ┌────────────────┴────────────────┐
        ▼                                 ▼
App::update(delta)                 App::render(delta)
Startup once                       Render stages
FixedUpdate 0..n
Update stages
        │                                 │
        └──── checked flush and frame-event cleanup ────┘

The standard schedule contains Startup, FixedUpdate, Update, and Render. Startup runs once; fixed steps run only when configured; update and render are separate host operations. Deferred commands apply at configured flush boundaries, so structural changes never invalidate a running system body.

Core capabilities

Opaque entity, component, event, stage, system, and query handles remain scoped to the world or schedule that created them. Cross-owner use returns an error instead of indexing unrelated state.

Learn through tiered examples

moirai::examples is the canonical learning path. Its 17 lessons are stable-Rust doctests that use the same public API available to applications.

Start with A01: Run your first app and follow each lesson's Next link. The final replay lesson requires the testkit feature and is included in docs.rs builds.

Features

Moirai has no default Cargo features.

Build the default constrained surface:

cargo check --no-default-features

Run the replay lesson and testkit tests:

cargo test --features testkit

Stability and boundaries

The public Rust API follows Cargo's SemVer compatibility rules. Before 1.0, minor releases may revise public contracts; patch releases should preserve them unless the changelog documents a required correction.

Moirai deliberately remains single-threaded and forbids unsafe code. It does not expose allocator, registry, storage-engine, command-queue, or schedule-runner internals. Host snapshots used by testkit are explicit application types—Moirai does not reflect or serialize a type-erased world.

Development

Run the standard public checks:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features --locked
RUSTDOCFLAGS="-D warnings" cargo doc --package moirai-for-games --no-deps --all-features --locked

The complete repository gate also checks the feature matrix, production source coverage, MSRV, benchmark compilation, and the publishable package:

scripts/verify_all.sh

The complete gate requires a current Rust toolchain plus the Rust 1.75 toolchain, cargo-llvm-cov, and UV.

Reference and next steps

• API reference
• Tiered executable examples
• Crates.io package
• Changelog

License

MIT — see LICENSE.