Characters
Characters are an experimental part of Cauldron. They are open to Cauldron creators, and the details on these pages may still change.
A character is someone in your deck that players talk to in their own words: a shopkeeper, a rival, a witness who saw something. You write who each character is, and Castle runs the conversation. Each character remembers what the player told it and what it has seen happen in your game. The game decides what actually happens, and characters only know the things your deck tells them.
A deck with characters has three parts:
- A character bundle in the deck's
castle.json. It names each character and gives it instructions, and declares the story events your game can record and what each one tells the characters who witness it. See Define characters. - Client code that opens a character and sends what the player types, using the SDK's
Charactersmodule. See Talk to a character. - Server code, in the deck's multiplayer server, that records what happens in the story and decides who gets to know about it. See Run the story from the server.
There are two kinds of conversation:
- Playthrough characters are separate for each player. Every player gets their own copy of each character, which remembers only that player's conversations and story. A player can reset their whole playthrough and start the story over. Most decks want this kind, and the first three pages cover it.
- Shared characters live in a persistent multiplayer world. Every player in the world talks to the same character, which can remember what happens across all of them. See Shared characters.
A deck's characters are either all playthrough characters or all shared ones: a deck has one character bundle, and the kind is set for the whole bundle (see One kind per deck). If you want both, use two decks.
What Castle does and what your deck does
Castle:
- picks and runs the AI model. A deck can't choose the model, give a character tools of its own, or call a model directly.
- keeps each character's conversation history and memory, and pins the published character bundle each playthrough started with.
- checks every request against the signed-in player. A player can only send their own words, never your instructions or the story state.
- pays for the conversation. See Costs and limits.
Your deck:
- writes each character's personality and instructions.
- decides what happens in the game, records it as story events, and chooses which characters learn about each one.
- shows the conversation, a waiting state while a reply is on its way, and a clear message when talk isn't available.
Who can talk to characters
A player has to be signed in. Players under 13, and players whose age Castle doesn't know, can't talk to characters in creator decks. For them, the character calls fail. Build the deck so that it still makes sense without the conversation, or show a short message in its place.
Costs and limits
Castle pays for character conversations. Each player has a daily allowance, shared with Castle's other AI features, that resets at midnight UTC. Every message a player sends uses some of it. Characters.open returns what's left, so the deck can show it. Each deck also has a daily limit across all of its players. When either one runs out, sends fail until the next UTC day (see Errors).
Other limits:
- A bundle can hold up to 48 characters, 32 event types and 64 beats, and at most 192 KiB in all. See Limits.
- A player message is at most 2,000 characters.
- A playthrough can have only so much waiting to be answered at once: about 32 messages, fewer while Castle is still updating characters' memories.
Try it
The pages that follow build one small deck: a watchman and a shopkeeper in a village where the old windmill burns down. The watchman sees the fire, and the shopkeeper hears about it only when the game passes the news on.
- Declare the two characters and the fire in
castle.json(Define characters). - Publish the deck once, so Castle has the bundle (Publishing).
- Add a chat panel that opens a character and sends what the player types (Talk to a character).
- Record the fire from the server and tell the witnesses (Run the story from the server).