Build role-playing simulations with Concordia
Learn Concordia by building a tabletop role-playing game: entities, components, prefabs and engines; the project editor and the concordia-session command line; free debugging with No Language Model; then a live game on a real model. 12 min 31 s in 12 chapters.
Chapters
Commands shown
Learn the editor for free
python -m pip install -e .
python -m examples.project_editor.run --port 8080 --model-backend noneDebug a prompt
log context --source current Charlie --step 3Connect a real model
python -m pip install -e ".[together]"
export TOGETHER_API_KEY="your-together-api-key"
python -m examples.project_editor.run --port 8080 \
--model-backend together_ai --model-name deepseek-ai/DeepSeek-V4.1-FlashAttach a terminal
concordia-session --url http://127.0.0.1:8080 interactive --draft royal-cake-draft.jsonBuild the game
catalog prefabs
add instance game_master.situated_in_time_and_place.GameMaster --id narrator
add instance basic --id pip
add instance minimal --id gerald
set simulation premise '"…"'
validate · save · export royal-cake.jsonRun it again
python -m examples.project_editor.run --project royal-cake.json \
--model-backend together_ai --model-name deepseek-ai/DeepSeek-V4.1-Flash
# add --headless to run without the editorGet the project file
The exact design built in chapter 7. Save it as royal-cake.json and pass it with --project.
{
"schema_version": 4,
"template": "entity-workbench-v1",
"instances": [
{
"id": "narrator",
"prototype": "installed:game_master.situated_in_time_and_place.GameMaster",
"prefab": "game_master.situated_in_time_and_place.GameMaster",
"role": "game_master",
"params": {
"name": "Narrator",
"extra_event_resolution_steps": "",
"clock_description": "Each step is one character’s turn and moves time forward by about thirty minutes. Turns rotate so that every character gets to act. The party begins at noon in the Throne Room.",
"start_time": "8:00 AM on Queen Marigold’s hundredth birthday",
"locations": "Wizard’s Tower: Pip’s cluttered workshop of bubbling potions and spellbooks. Royal Kitchen: ovens, flour and Mabel’s spotless counters. Throne Room: being decorated for the party; the Queen arrives at noon. Castle Garden: a lily pond, rose bushes and a sundial."
}
},
{
"id": "pip",
"prefab": "basic",
"role": "entity",
"params": {
"name": "Pip",
"goal": "Pip is an over-enthusiastic apprentice wizard who has never met a spell worth not trying. Pip wants to turn Gerald back into the royal birthday cake before noon, ideally without anyone finding out. Pip’s turns are short: one or two sentences.",
"randomize_choices": false
},
"prototype": "bob"
},
{
"id": "reginald",
"prefab": "basic",
"role": "entity",
"params": {
"name": "Sir Reginald",
"goal": "Sir Reginald is an elderly and extremely formal knight who believes any problem can be solved with a proper quest and a strongly worded letter. He is determined that the Queen’s birthday goes perfectly, and he suspects foul play. His turns are short: one or two sentences.",
"randomize_choices": false
},
"prototype": "bob"
},
{
"id": "mabel",
"prefab": "basic",
"role": "entity",
"params": {
"name": "Mabel",
"goal": "Mabel is the royal baker: practical, unflappable and fond of saying ’well, that won’t do.’ She wants a cake on the Queen’s table by noon, even if she has to bake a new one from scratch. Her turns are short: one or two sentences.",
"randomize_choices": false
},
"prototype": "bob"
},
{
"id": "gerald",
"prefab": "minimal",
"role": "entity",
"params": {
"name": "Gerald",
"custom_instructions": "Gerald is a toad who, until this morning, was the Queen’s birthday cake. He is unfailingly polite, speaks in complete sentences, would very much prefer not to be eaten, and is not shy about joining in. His turns are short: one or two sentences.",
"goal": "Gerald wants to decide whether he would rather stay a toad or become a cake again.",
"randomize_choices": false
},
"prototype": "alice"
}
],
"premise": "It is eight o’clock on the morning of Queen Marigold’s hundredth birthday in the hilltop kingdom of Crumbleton. The party starts at noon in the Throne Room. At dawn, Pip the apprentice wizard tried to make the royal cake extra magnificent and accidentally turned it into a very polite toad named Gerald. Pip and Gerald are in the Wizard’s Tower. Mabel the baker has just noticed that the cake is missing from the Royal Kitchen. Sir Reginald is in the Throne Room, inspecting the decorations with a magnifying glass.",
"max_steps": 12,
"components": [],
"dynamic_states": {}
}Recorded on upstream commit 80d9dab, with the project editor example and Together AI adapter from the concordia-claw feat/android-project-editor-demo-001 branch. Chapters 3–5 use No Language Model. The live game uses DeepSeek V4.1 Flash on Together AI: one 10-step run, about $0.13. Waiting during live runs is sped up, as marked on screen. Terminal scenes replay real captured concordia-session output; long output is trimmed and marked. Narration is synthesized with the open Kokoro voice model.