open source · 0.13.0 · pre-1.0

Canwu Engine

参伍引擎

Build replayable historical simulations where each player sees only what their character knows.

Canwu is a headless simulation engine written in Rust. Your code sends it commands; it advances time, records what happened and why, and tracks what each character knows. Rendering, UI, and historical content stay in your game, research tool, or agent system.

Run the example View source ↗Read the architecture ↓

Replay: Same inputs, same result
Knowledge: A separate view per character
Rendering: Use any engine or UI
Agents: Same API as players

The starter examplestarter.rs

use canwu_api::{Canwu, CommandRequest, CommandRequestId, EntityRef, Issuer, SimDuration};
use canwu_reference_world::{
    MovementCommand, ReferenceWorldPlugin, demo_scenario, order_movement,
    snapshot as reference_snapshot,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (scenario, ids) = demo_scenario()?;
    let plugin = ReferenceWorldPlugin;
    let mut canwu = Canwu::new_with_plugins(35, scenario, &[&plugin])?;

    let envelope = order_movement(
        Issuer::Actor(ids.commander),
        &MovementCommand {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?
    .at_time(canwu.time());
    canwu.enqueue_command(
        canwu.time(),
        0,
        CommandRequest::new(CommandRequestId::new(1), canwu.revision(), envelope),
    )?;
    canwu.advance_canonical(SimDuration::hours(19))?;

    let saved = canwu.snapshot_json()?;
    let loaded = Canwu::from_snapshot_json_with_plugins(&saved, &[&plugin])?;
    let fork = loaded.fork();
    let journal = canwu.replay_journal();
    let replayed = Canwu::replay_from_journal(&[&plugin], &journal)?;

    assert_eq!(loaded.checkpoint_hash(), canwu.checkpoint_hash());
    assert_eq!(fork.checkpoint_hash(), canwu.checkpoint_hash());
    assert_eq!(replayed.checkpoint_hash(), canwu.checkpoint_hash());
    println!(
        "army_location={} checkpoint={}",
        reference_snapshot(&replayed)?
            .army(ids.army)
            .expect("demo army exists")
            .location,
        replayed.checkpoint_hash()
    );
    Ok(())
}

Open starter.rs on GitHub ↗

Architecture

How Canwu fits into your application

Your application sits on top and talks only to canwu-api. Domain plugins add rules such as resources, movement, or law. The runtime underneath holds the live world and changes it only while settling commands and scheduled work. Select a layer, or follow one command from submission to replay.

Public API boundary · code above this line uses only canwu-api
Engine internals · reached only through canwu-api

Your application

Owns rendering, input, the real-time clock, accounts, and historical content. It depends on canwu-api, registers the plugins it needs, submits commands, and reads the results.

Reference client in this repository

canwu-debugDesktop debug client (egui) built on the public API and the reference integrations

Domain plugins

Domain extensions add reusable rules as simulation plugins built on canwu-api. Register only the ones you need, or write your own. Reference content packs supply data, and reference integrations combine the pieces into small worlds you can run and copy.

Domain extensions (published on crates.io)

canwu-resourceResource accounts, reservations, transfers, and fulfillment
canwu-productionProduction processes, facilities, work orders, and output
canwu-movementMovement orders, route legs, and capacity pools
canwu-militaryForces, operations, combat, and occupation
canwu-societySocial diffusion between population groups
canwu-cultureCulture authoring, compilation, and lifecycle
canwu-lawLegal procedures, versioned law, and applicability (experimental)
canwu-technologyTechnology from evidence to adoption and diffusion
canwu-fiscalFiscal institutions, procedures, and assessments
canwu-informationDocuments, copies, access, and interpretation
canwu-correspondenceLetters, addresses, carriers, and interception
canwu-history-researchOptional research assessments for technology runs

Reference content packs

canwu-ming-fiscalVersioned, source-cited Ming fiscal data
canwu-economy-reference-contentEconomy model cards and cited data
canwu-military-reference-contentSynthetic (non-historical) military rulesets for the reference integration

Reference integrations (repository only, not published)

canwu-reference-worldSmall world with armies and territories, used by the starter example
canwu-economy-referenceGrain loop with production, transport, and military supply
canwu-force-supply-referenceMilitary supply as a second resource consumer
canwu-military-referenceThe military extension running in the reference world
canwu-ming-fiscal-referenceHongwu, Wanli, and Hongguang fiscal scenarios

Write your own plugin →

`canwu-api`

The engine crate your application depends on; extension crates build on it too. Its Canwu type creates and advances a run, accepts commands, returns detached snapshots and actor-relative views, and saves, forks, and replays runs. It re-exports the types you need from the crates below.

Main calls

Canwu::new_with_pluginsCreate a run from a scenario and a plugin list
enqueue_commandQueue a command for a simulation time
advance_canonicalAdvance time and settle everything that falls due
viewer_for_actorRead the world as one actor knows it
events · explainList what happened and ask why
snapshot_json · fork · replay_from_journalSave, branch, and replay a run

Integrate Canwu →

`canwu-sim`

Holds the authoritative state. It queues incoming commands, runs scheduled work, and settles due work in boundaries: one all-or-nothing pass at one simulation time, run in 14 fixed phases. If anything fails, the whole boundary rolls back. It also records the evidence and hashes used for saves and replay. Applications reach it only through canwu-api.

Crate

canwu-simRuntime, scheduling, settlement, plugins, persistence, hashing, and replay

How a boundary is settled →

Models and mechanisms

Data types that plugins and applications reach through canwu-api: what happened and why, what each actor knows, pending decisions, and route and transport records. The runtime itself uses the event, knowledge, and decision types.

Crates

canwu-eventEvents with their cause, audience, and evidence references
canwu-knowledgeWhat each actor knows, with source, confidence, and age
canwu-decisionDecision tickets, controllers, and policies
canwu-routingRoute planning where travel times change over time
canwu-transportTransport runs, bookings, handoffs, and capacity pools

Events and causality →

Foundation

Typed IDs, deterministic random numbers, schema metadata, and simulation time arithmetic. Every other crate builds on these two.

Crates

canwu-coreStable IDs, deterministic random numbers, and schema primitives
canwu-timeSimulation time and checked duration arithmetic

Replayable randomness →

Step 1 of 7
Build a command
Your client creates a typed command. In the starter example, the reference world wraps a MovementCommand into a command envelope.
```
let envelope = order_movement(Issuer::Actor(commander), &command)?;
```
Step 2 of 7
Queue it
enqueue_command puts the request in the ingress queue for its due time and returns a receipt. Resending the identical request returns the same receipt; reusing its ID with different content fails. The world has not changed yet.
```
canwu.enqueue_command(due_at, priority, CommandRequest::new(id, revision, envelope))?;
```
Step 3 of 7
Advance time
advance_canonical moves simulation time forward. Each batch of work that falls due is settled in one boundary.
```
canwu.advance_canonical(SimDuration::hours(19))?;
```
Step 4 of 7
Settle the boundary
The engine checks the issuer's authority, the revision the command was based on, and its expected time. A rejected command is recorded with its reason. Plugin systems then run in 14 fixed phases and propose changes, which commit together or roll back together.
The 14 phases →
Step 5 of 7
Record what happened
Committed changes produce events that carry their cause and audience. Characters' knowledge and reports are updated, and the replay journal gains one more boundary.
Step 6 of 7
Read it back
A player or agent reads through viewer_for_actor and sees only what that actor knows. Trusted host tools can also list events() and ask explain() why something happened.
```
let viewer = canwu.viewer_for_actor(actor)?;
```
Reading state safely →
Step 7 of 7
Save and replay
snapshot_json saves the run, and replay_journal returns its recorded inputs. replay_from_journal rebuilds the run from those inputs; equal checkpoint hashes show the replay is exact.
```
let replayed = Canwu::replay_from_journal(&[&plugin], &canwu.replay_journal())?;
assert_eq!(replayed.checkpoint_hash(), canwu.checkpoint_hash());
```
Save, replay, and fork →

Each layer uses only its own layer and the layers below it. Select a layer to see its crates, or switch to Follow a command and use the arrows.

Read the architecture guide →

Guarantees

Three things the engine guarantees

The engine owns time, state, and history; your plugins own the rules of your period. The engine enforces these three properties for every client, and for every plugin that reads, writes, and draws randomness only through its declared contract.

replay

Deterministic replay

Time, scheduled work, and random draws run in a fixed order. Replaying a run's journal rebuilds it, and the checkpoint hash confirms the result is identical.

knowledge

Each character knows different things

The true state of the world is kept apart from what each character knows. Each observation records its source, confidence, and age, so a character can act on a report that is late or wrong.

commands

One API for every client

Clients change the world only by submitting commands, and read it through snapshots, events, or a character's view. A game, a research notebook, and an AI agent use the same calls.

Install

Add canwu-api 0.13.0

Requires Rust 1.88 or newer. Add canwu-api to your application's Cargo.toml. The reference world used by the examples lives in the repository; clone it to run the examples. The exact = pin matters because a save loads only in the engine version that wrote it.

Cargo.toml

[dependencies]
canwu-api = "=0.13.0"

crates.io ↗View releases ↗

Five-minute check

Run the starter example

The starter moves an army with a typed command and advances 19 hours. It then saves and reloads, forks, and replays the run, and checks that all three copies match the original's checkpoint hash.

Clone and run

git clone https://github.com/PeiyuanQi/canwu
cd canwu
cargo run -p canwu-reference-world --example starter

Expected output

army_location=3 checkpoint=dd9796a606983d02eafd3495df11b20bb8423cec33f96c0eaddc24e44e4e2de1

Step-by-step tutorial

open source · 0.13.0 · pre-1.0

What works today

Canwu is pre-1.0, so a minor version can still change the API. Everything listed under “Implemented” has tests. Before you depend on an area that is still in progress, check the conformance profile.

Implemented

Change state only through validated commands, built into the engine or defined by your plugins
Advance time, run scheduled work, and record the cause of every event
Give each character its own knowledge, including late reports
Save snapshots and checkpoint journals, fork runs, and replay them exactly
Track whether each person is alive, free, detained, or captive, and reject orders from people who cannot act
Check a change that spans several plugins before it commits
Show rule explanations only to characters allowed to see them
Move goods and people with capacity limits, delegated carriers, and shared access to resources (extension plugins)
Checked-in benchmarks for run time, memory allocation, and snapshot size

In progress

Bindings for other languages and network access
Archive storage and indexed lookup of past history
Larger runnable scenarios that combine several domains
Ready-made client and renderer integrations

CI runs on Windows, macOS, and Linux.

Conformance profile ↗

AI agents

Agents use the same API as players

An agent reads a view limited to its character, submits the same typed commands a player would, and sees rule explanations only for what that character may know. Each domain plugin defines its own commands and views.

viewer_for_actor(actor)viewer.query_knowledge(query)viewer.visible_changes_since(time)viewer.evaluation_traces(subject, after)enqueue_command(...)advance_canonical(...)

Agent loopactor-scoped

// 1. Read what this character knows
let viewer = canwu.viewer_for_actor(actor)?;
let knowledge = viewer.query_knowledge(&query)?;

// 2. Decide, then submit a typed command
canwu.enqueue_command(time, priority, request)?;
canwu.advance_canonical(duration)?;

// 3. See what changed from this character's point of view
let changes = canwu.viewer_for_actor(actor)?.visible_changes_since(since);

Use cases

What you can build

See integration patterns →

Grand strategy games

Run the simulation behind any map or renderer.

Historical research

Run repeatable scenarios, branch alternative histories, and compare the results.

Agent environments

Give several agents different knowledge, authority, and commands.

Education and public history

Build timelines, maps, and classroom tools on replayable state.

Contribute

Help improve Canwu

Start with the architecture guide and the contribution guide, then open an issue or a focused pull request. Improvements to the public API, docs, tests, and reference scenarios are all welcome.

Architecture→API examples↗Contributing↗License→

Canwu Engine

Build replayable historical simulations where each player sees only what their character knows.

Your application

Reference client in this repository

Domain plugins

Domain extensions (published on crates.io)

Reference content packs

Reference integrations (repository only, not published)

canwu-api

Main calls

canwu-sim

Crate

Models and mechanisms

Crates

Foundation

Crates

Build a command

Queue it

Advance time

Settle the boundary

Record what happened

Read it back

Save and replay

Deterministic replay

Each character knows different things

One API for every client

Add canwu-api 0.13.0

Clone and run

Expected output

Grand strategy games

Historical research

Agent environments

Education and public history

Help improve Canwu

`canwu-api`

`canwu-sim`