canwu-engine-usage

参伍引擎 Canwu Engine

English | 简体中文

Website: canwu.org

Canwu is a headless historical simulation engine written in Rust. It simulates a historical world, advances time in a repeatable way, accepts validated commands, and records events and their causes. It can also represent what each person knows instead of giving every actor access to the true world state.

Canwu does not render graphics, play audio, or provide a production user interface. Games, research tools, Python programs, web clients, and AI agents use Canwu through its public APIs.

Canwu is built for simulations that need more than a mutable game-state object. It provides deterministic time, validated authority-aware commands, atomic settlement, actor-relative knowledge, typed extension points, causal evidence, save/load validation, exact replay, and explicit live evidence sealing. The engine remains domain-neutral: applications define their own rules and content through public contracts rather than adding application-specific types to the kernel.

The project is under active development. The public examples are small on purpose: they make the engine's guarantees easy to inspect, test, and reuse in larger games, research environments, and agent-driven simulations.

Use Canwu as a dependency

Rust applications should depend on the supported public API rather than the implementation crates:

[dependencies]
canwu-api = "=0.19.0"

Applications that persist Canwu snapshots should pin a published engine release exactly and upgrade only alongside an explicit save migration. The example above selects the immutable 0.19.0 release rather than the moving main branch.

The crates in canwu-api's dependency graph are published so Cargo can resolve the public API. They are not separate compatibility surfaces for application code. The domain extensions are also published as crates.io packages so applications can depend on an officially released extension version; they remain optional and may evolve independently before 1.0.

Quick start

Install Rust 1.88 or newer, then run the extracted reference-world starter:

cargo run -p canwu-reference-world --example starter

For a phased, API-only plugin example:

cargo run -p canwu-api --example phased_boundary

For a persisted decision-ticket example with dynamic options, utility evaluation, authority-derived command execution, trace output, and exact replay:

cargo run -p canwu-api --example decision_ticket

For the social diffusion simulation module example:

cargo run -p canwu-society --example local_community_diffusion

For the evidence-based technology flow:

cargo run -p canwu-technology --example technology_diffusion

For routed local and Wuxi-to-Beijing correspondence:

cargo run -p canwu-correspondence --example routed_correspondence

For the trusted desktop debug client:

cargo run --locked -p canwu-debug

canwu-debug starts the Hongwu Ming fiscal reference fixture through the public API. Run advances six simulation hours at a time, Step settles the next canonical boundary, and Run fiscal sample executes the complete fiscal cycle. The center view shows the reference-world map and an interactive settlement timeline; click a frame to inspect its fiscal counts. Open trace viewer opens the browser trace viewer against the same live trace dump.

How the repository fits together

• canwu-core: stable IDs, repeatable random numbers, and schema metadata
• canwu-decision: decision tickets, controllers, traces, utility evaluation, guarded utility policies, and policy SDK contracts
• canwu-time: historical time that is independent of rendering speed
• canwu-event: stored events and links between causes and effects
• canwu-knowledge: what each actor knows and when they learned it
• canwu-routing: deterministic, observer-relative route planning
• canwu-transport: itinerary, custody, booking, capacity-pool, and delivery execution records
• canwu-sim: private simulation state, commands, scheduling, plugins, and multi-owner transition audits
• canwu-api: public APIs for programs, agents, explanations (including rule-evaluation traces), and debugging
• canwu-reference-world: replaceable example entities, detached projection, movement plugin, routing adapter, and runnable persistence/replay starter
• canwu-debug: a small reference client built on the public API and reference integration
• canwu-information: published information-lifecycle extension, including authenticity findings
• canwu-correspondence: published correspondence domain extension and simulation plugin built on routing, transport, and information, with delegated carriers
• canwu-society: published social diffusion simulation module; architecturally, a domain extension built on canwu-api
• canwu-culture: published culture authoring, compilation, and lifecycle extension built on canwu-society, with host-driven and in-engine settlement plugins
• canwu-law: experimental deterministic legal authoring, institutional procedure (including weighted, unit-block, and consultation stages), versioned law, applicability, succession, and retirement extension
• canwu-technology: published generic technology extension for evidence, local capability, implementation, use-specific adoption, and diffusion
• canwu-history-research: published optional historical assessment plugins kept downstream from base technology truth
• canwu-fiscal: published generic fiscal-procedure extension for regional law adoption, assessment, remission, authorization, receipts, and reports
• canwu-resource: optional conserved resource accounts, demand, allocation, transfer escrow, atomic exchange, delegated access grants, consumption, loss, fulfillment, and holder-relative reports
• canwu-production: optional process, site, facility, work-order, WIP, maintenance, repair, and output-settlement extension
• canwu-economy-reference-content: source/model-card-bound economy profiles with fail-closed place, period, resource, process, and coverage keys
• canwu-military: optional military domain extension for forces, operations, combat, occupation, military knowledge, and military administration
• canwu-movement: optional movement lifecycle extension for movement orders, leg settlement, capacity-pool allocation, and holder-relative movement reports over canwu-transport records
• canwu-force-supply-reference: replaceable military-supply consumer proving that resource fulfillment and force consequences remain separate domains
• canwu-economy-reference: runnable G1b grain loop and detached G5 local scarcity/price-pressure reference composition
• canwu-ming-fiscal: source-cited Ming reference content from 1368-1662, plus an optional Zheng continuation through 1683
• canwu-ming-fiscal-reference: runnable Hongwu, Wanli, and Hongguang scenario composition using the fiscal and reference-world plugins

The crate map shows the repository layers, exact dependency DAG, and publication order. The documentation index links the architectural contracts, community guidance, and legal notices. agent-interface contains packaged skills for engine users. Repo-local contributor skills live under .agents/skills, with Claude-compatible loaders under .claude/skills; these are tooling, not runtime simulation plugins. The website and assets directories contain the community site and project media.

Read the architecture and end-state design before changing boundaries.

Development

Contributions, bug reports, examples, documentation improvements, and careful architecture discussions are welcome. See [CONTRIB