Skip to content
Canwu Documentation

Guides

How to embed Canwu in your application, from the first dependency to your own plugins.
Run the first exampleIntegrate Canwu中文指南
Using a coding agent? Start here

Canwu ships two skills for coding agents. Ask your agent to load them before it writes code:canwu-engine-docs and canwu-engine-usage. Then start with the Get started and the relevant runnable example, and use the guides as needed.

Starter prompt

Load the canwu-engine-docs and canwu-engine-usage skills. Read the Canwu tutorial, guide page, and example that match this task. Use only canwu-api, state the rule you must preserve before you edit, and run the example or a focused check when you are done.

These guides are for developers building a game, research tool, or agent system on Canwu. Each page covers one task and shows the canwu-api calls it needs.

If this is your first time

Section titled “If this is your first time”
  1. Run the move-army tutorial to check that your Rust toolchain builds and runs Canwu.
  2. Read Integrate and drive the simulation to put the same flow into your own application.
  3. Pick the guide below that matches your next task.

Guides by task

Section titled “Guides by task”
Integrate and drive the simulationAdd the dependency, create a run, submit commands, and turn real time into simulation time.
Read and present state safelyShow players and agents only what their actor knows, and keep full snapshots for trusted code.
Save, replay, and forkChoose between snapshots and checkpoint journals, reload with the same plugins, and replay or branch a run.
Extend with pluginsAdd your own rules as domain commands and boundary systems.

Guides that belong to one domain system, such as production, resources, and transport: who owns what, are listed with that system under Domain systems.

Rules every integration follows

Section titled “Rules every integration follows”
  1. Build on canwu-api and published extensions. Get concrete rules from domain extensions such as canwu-military, from reference integrations, or from your own plugins. Do not depend on internal crates such as canwu-sim; they carry no compatibility promise.
  2. Change the world through commands. Use engine commands, domain commands, or plugin ingress.
  3. Give players and agents actor-relative views. Keep full snapshots in trusted host code and debugging tools.
  4. Own the clock in your application. Rendering, input, and wall-clock time stay in the host; convert elapsed real time into a simulation duration before you call the engine.
  5. Pin versions for saved runs. Pin the engine version, and load or replay with the same plugins. The engine compares them with the plugin descriptors stored in the save.

Where else to look

Section titled “Where else to look”