Siming is a cross-platform dialogue editor for games and interactive narratives. It organizes dialogue, choices, conditions, variables, and business events as visual story graphs, then compiles projects into engine-independent runtime data for Unity, Unreal Engine, or a custom host.
This repository contains the desktop editor, Rust core and CLI, runtime data contracts, and C# / Unity 6 SDK.
- Visual dialogue editing: Build dialogue, choice, condition, event, and end nodes as connected graphs.
- Branching and conditions: Drive narrative branches with variables and player choices. Condition nodes support both TRUE/FALSE expressions and switch/case branches with a default exit.
- Localization: Configure multiple locales and export separate localized resources.
- Host and business events: Send presentation notifications or invoke asynchronous events implemented by the game host.
- Runtime export: Export JSON, XML, or binary data in bundled or directory-chunked layouts.
- Validation and migration: Validate schemas and references, promote warnings to errors, and migrate project data before export.
- C# / Unity SDK: Play dialogues, handle variables and events, switch locales, capture and restore playback state, and integrate with Unity 6.
- Node.js 22.13 or later
- Rust stable with
rustfmtandclippy - The platform dependencies required by Tauri 2
- .NET 8 or later for the C# SDK; Unity 6 for the Unity integration
cd apps/desktop
npm install
# Start the Vite frontend
npm run dev
# Start the Tauri desktop application
npm run tauri -- devprototype/ contains product interaction prototypes and private previews. It is not part of the production desktop build.
The repository includes a minimal fixture project at fixtures/minimal-project. Use it to validate the project format, run the CLI, and generate runtime data.
# Show the CLI version
cargo run -p siming-cli -- --version
# Validate a project
cargo run -p siming-cli -- validate fixtures/minimal-project
# Show a project summary
cargo run -p siming-cli -- info fixtures/minimal-project
# Export runtime data
cargo run -p siming-cli -- export fixtures/minimal-project \
--output /tmp/siming-runtime \
--format json \
--layout directory-chunks \
--prettyThe generated files in /tmp/siming-runtime are the runtime data consumed by a host or SDK. If --format and --layout are omitted, the project settings in .siming/project.json are used.
The CLI entry point is siming. In the source repository, use cargo run -p siming-cli -- in its place.
| Command | Purpose | Example |
|---|---|---|
validate |
Validate project structure, references, text, and runtime constraints | siming validate . --warnings-as-errors |
export |
Compile and export runtime data | siming export . --output exports/runtime --format json |
migrate |
Check or apply a schema migration | siming migrate . --check / siming migrate . --write |
info |
Show schema, locales, content counts, and validation summary | siming info . --format json |
Common commands:
# Machine-readable validation output
siming validate . --format json
# Export JSON, XML, or binary runtime data
siming export . --output exports/runtime --format json --pretty
siming export . --output exports/runtime --format xml --pretty
siming export . --output exports/runtime --format binary
# Select the file layout
siming export . --output exports/runtime --layout bundled
siming export . --output exports/runtime --layout directory-chunks
# Check or apply migrations; --write creates a backup first
siming migrate . --check
siming migrate . --writeExit codes are 0 for success, 1 for validation or compilation failure, 2 for argument/path/version errors, and 3 for an unexpected internal error.
apps/desktop/ React + Tauri desktop application
crates/siming-core/ Shared contracts, validation, and runtime compiler
crates/siming-storage/ Project loading, migration, and safe export boundary
crates/siming-cli/ Standalone command-line tool
schemas/ Versioned JSON Schemas
fixtures/ Shared GUI, CLI, and migration fixtures
examples/ Engine-independent runtime reader examples
sdks/csharp/ C# runtime, Unity 6 package, examples, and tests
prototype/ Product interaction prototypes and private previews
A project normally contains:
my-project/
├── .siming/project.json # Project manifest, locales, and export settings
├── dialogues/ # Dialogue graph files
├── definitions/ # Character, variable, event, and tag definitions
└── exports/runtime/ # Runtime data generated by the CLI
Use this layout when the whole project should be loaded at once:
exports/runtime/
├── manifest.json
├── dialogues.runtime.json
└── locales/
├── zh-CN.json
└── en-US.json
Use this layout to load chapters, scenes, or dialogues on demand. The project index, dialogue structures, and locale resources are split into files so a host can load only the chunks required by an entry point.
The JSON runtime contracts are defined by:
schemas/runtime.schema.jsonschemas/runtime-index.schema.jsonschemas/runtime-dialogue-chunk.schema.jsonschemas/runtime-locale-chunk.schema.json
See the runtime format guide for node progression, text keys, and the binary protocol. The repository also includes an engine-independent reader example:
node examples/runtime-reader/index.mjs exports/runtime intro zh-CN发布流程和 Unity Git URL 见发布文档。
The C# SDK consumes runtime data generated by siming export. It does not depend on a Rust native library and does not provide UI, audio/video playback, task systems, or save-file persistence. It includes:
- A general .NET runtime:
Siming.RuntimeandSiming.Serialization.Json - A Unity 6 UPM package:
sdks/csharp/Packages/dev.siming.sdk - Loaders for bundled and directory-chunked JSON exports
- Dialogue playback, choices, automatic dialogue, variables, conditions, and asynchronous business events
- Host event notifications, locale switching, and host-owned playback state capture/restoration
After referencing the SDK, open an export directory with the JSON loader and create a session:
using Siming;
using Siming.Serialization.Json;
using var project = await SimingProject.OpenAsync(
new JsonProjectLoader(new DirectoryDataSource("exports/runtime")),
cancellationToken);
using var session = project.CreateSession(
businessEvents: new GameEvents(),
locale: "en-US");
session.StateChanged += view =>
{
Console.WriteLine($"{view.SpeakerName}: {view.Text}");
};
session.HostEventReceived += message =>
{
// Play audio, change cameras, trigger animations, etc.
HandleHostEvent(message);
};
await session.StartByKeyAsync("intro", cancellationToken);
if (session.Current.Status == SessionStatus.WaitingDialogue)
{
await session.ContinueAsync(cancellationToken);
}
else if (session.Current.Status == SessionStatus.WaitingChoice)
{
await session.ChooseAsync(choiceId, cancellationToken);
}Implement IBusinessEventHandler for game-owned business events:
sealed class GameEvents : IBusinessEventHandler
{
public async Task ExecuteAsync(
string name,
DataValue parameters,
BusinessEventContext context,
CancellationToken cancellationToken)
{
switch (name)
{
case "quest.begin":
await BeginQuestAsync(parameters, cancellationToken);
context.Set("accepted", new VariableValue(true));
break;
default:
throw new InvalidOperationException($"Unknown event: {name}");
}
}
}| API | Purpose |
|---|---|
SimingProject.OpenAsync(...) |
Open and validate the runtime manifest, indexes, and default locale resources |
CreateSession(...) |
Create an isolated session with optional variable storage and business event handling |
StartAsync(...) / StartByKeyAsync(...) |
Start by dialogue ID or entry key |
ContinueAsync(...) |
Advance a dialogue that is waiting for input |
ChooseAsync(choiceId, ...) |
Select a choice |
TickAsync(deltaSeconds, ...) |
Drive automatic dialogue timing from the host |
SetLocaleAsync(locale, ...) |
Switch the current session locale |
CaptureState() / RestoreStateAsync(...) |
Capture or restore minimal state at a safe waiting point |
Stop() / Dispose() |
Stop the session and release resources |
Do not call advance, locale-switch, capture, or restore APIs from callbacks because this can cause reentrancy. Schedule follow-up work in the next host update instead. The SDK does not write save files; the host should persist playback state and variable values as one consistent save.
- In Unity Package Manager, select Install package from disk.
- Select
sdks/csharp/Packages/dev.siming.sdk/package.json. - Put the runtime directory generated by
siming exportunderAssets/StreamingAssets/Siming/, or implementIRuntimeDataSourcefor Addressables, memory, or remote resources. - Import the Basic Dialogue sample and use its
BasicDialoguecomponent as a starting point.
All SDK calls, event handlers, and Unity object access should run on Unity's main thread. Automatic dialogue is driven by the host through TickAsync; the sample component supports scaled or unscaled time.
For installation details, API constraints, save-state handling, error codes, and Unity validation commands, see the C# SDK documentation and SDK guide.
# Rust
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
# Desktop application
cd apps/desktop
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run tauri -- build --no-bundle
# C# SDK (run from the repository root)
dotnet run --project sdks/csharp/tests/Siming.Tests
dotnet run --project sdks/csharp/examples/Console -- \
sdks/csharp/contracts/directory-chunks sdk_demo en-USGenerate SDK test contracts and local packages:
python3 sdks/csharp/scripts/generate-contracts.py
python3 sdks/csharp/scripts/package.py- Product requirements
- Technical design
- Runtime format and host integration
- C# SDK documentation
- C# SDK guide
- CLI and data contract examples
- 中文说明
Siming is released under the Apache License 2.0.
