Skip to main content

Define characters

A deck declares its characters in characterBundle, a key in the deck's own castle.json. Add it beside the keys that are already there, and leave the rest of the file as it is.

{
"title": "Windmill Village",
"server": { "main": "server/index.js", "maxPlayers": 1, "tickRate": 0 },
"characterBundle": {
"version": "windmill-1",
"characters": [
{
"id": "tomas",
"version": "1",
"name": "Tomas",
"instructions": "You are Tomas, the village watchman: careful, dry, a little tired. Tell apart what you saw from what you heard. Treat anything you recall as fallible."
},
{
"id": "mara",
"version": "1",
"name": "Mara",
"instructions": "You are Mara, who runs the village shop. Speak warmly and briefly. Never claim something happened in the world unless you know it from the story."
}
],
"eventTypes": [
{
"id": "windmill_fire",
"claims": [
{
"id": "windmill_burned",
"text": "The old windmill burned down.",
"witnessCharacterIds": ["tomas"]
}
]
}
],
"beats": [
{
"id": "mara_asks_about_fire",
"characterId": "mara",
"eventTypeId": "windmill_fire",
"requiredClaimIds": ["windmill_burned"],
"opportunity": "opening",
"priority": 100,
"repeat": "once_per_event",
"intent": "Ask whether the player is safe.",
"openingText": "Tomas said the mill burned. Are you all right?",
"completionOutcomeIds": ["safety_answered"]
}
]
}
}

version, characters, eventTypes and beats are all required. eventTypes and beats can be empty lists. Castle rejects a bundle with a key it doesn't know, so check the spelling when a publish fails.

A deck has one characterBundle, and every character in it is the same kind. The bundle on this page has no conversation block, so its characters are playthrough characters. Adding a conversation block makes every character in the bundle a shared character instead, and Characters.send stops working for all of them. See One kind per deck.

Characters​

Each entry in characters has:

  • id: how your code refers to the character, for example in Characters.open("mara"). Ids are unique within the bundle and stay the same across versions.
  • version: your own label for this version of the character.
  • name: the name players see.
  • instructions: who the character is and how it talks, written to the character. Players can't read it directly, and nothing they type can replace it. The model does read it, though, and a reply can repeat what's in it, so don't put anything there that must stay secret.

Write instructions as you would brief an actor: personality, what the character wants, how it speaks, and what it would never say. Leave out story facts the character shouldn't know yet. Facts reach a character through events (below), so the character learns them only when they happen.

Events and claims​

An event type is something that can happen in your story. Its claims are the facts it establishes. Each claim names its witnesses: the characters who can learn it first-hand, because they were there.

  • id: the event type's id, which the server uses to record it.
  • claims: one to eight claims. Each has an id, a text the characters read as a fact, and witnessCharacterIds, the characters allowed to learn it first-hand (at most 12).

Each event type happens at most once per playthrough.

Declaring an event doesn't make it happen, and recording it doesn't tell anyone. Your server records the event when it happens in your game, then delivers its claims to the witnesses. Characters who aren't witnesses learn about it only when your game passes the news on. See Run the story from the server.

Beats​

A beat is a moment you write in advance: once a character knows certain claims, its next reply to the player opens with your line instead of a generated one.

  • id, characterId, and eventTypeId: the beat, who says it, and which event it follows.
  • requiredClaimIds: the claims of that event the character must know first.
  • opportunity: "opening", the start of the character's next reply. It's the only value for now.
  • repeat: "once_per_event", at most once for each time the event happens. It's the only value for now.
  • priority: a whole number from 0 to 1000. When several beats are ready, the highest goes first.
  • intent: what the character is trying to do in this moment, which guides the rest of its reply.
  • openingText: the exact line the reply opens with.
  • completionOutcomeIds: the outcomes your game may record when it decides how the moment ended, for example "safety_answered".

A beat that fires arrives with the reply. A ready beat isn't guaranteed to fire on the very next reply: Castle can hold it back when it doesn't fit, for example when the conversation is long. The beat isn't finished until your server completes it with one of its outcomes. See Beats.

Limits​

Most
Characters48
Event types32
Claims per event type8
Witnesses per claim12
Beats64
Required claims and outcomes per beat8 each
id, version, name100 characters and 128 bytes
instructions8,000 characters, and 10,000 once written as JSON (quotes and line breaks count twice)
Claim text, beat intent, openingText500 characters each
Whole bundle192 KiB

Publishing​

Publishing the deck publishes its bundle. castle-web save-deck sends the bundle whenever castle.json has a characterBundle key, and Castle checks it before saving anything. An invalid bundle fails the save with CAULDRON_CHARACTER_INVALID_ARGUMENT and a message saying what's wrong.

  • Keep characterBundle in castle.json for as long as the deck has characters. Each save publishes the bundle with that version of the deck. If you delete the key, the save sends no bundle, the published one stays tied to the older version, and characters stop opening.
  • To remove characters from a deck, set "characterBundle": null and publish. Characters stop opening, and messages already on their way may still be answered.
  • Characters only work in a published deck, including when you test it locally with castle-web serve. The local preview talks to the real character service using the deck's id, so publish the bundle before you try a conversation, and publish again after you change it.
  • The bundle isn't sent to players' devices with the deck. The model reads the instructions and the claims a character has learned, so a reply can repeat them.

A player's playthrough keeps the bundle it started with. When you publish a new bundle, players who already started keep the old one until they reset their playthrough. A player who starts after the publish gets the new one. definitionVersion on an opened character tells you which bundle the playthrough is using. If a change matters to players who already started, change the bundle's version and offer a reset in your game. A shared world is different: it switches to the new bundle on its next turn.

The same applies to you while you test. After you edit a character and publish, your own playthrough still answers with the old character. To try the edit, reset your playthrough: call reset on any open character's handle (see Resetting the playthrough), or give your deck a "Start over" button that does. Then open the character again. If you changed the bundle's version, definitionVersion now shows the new one.