Candy Logo Copyright © 2025-2026 Candy Arts
Dialogue History
The Dialogue History is a log of everything that was said: each Spoken Line, in order, with its speaker. Players read back the lines they missed in it, and your game reads what was said from it, for a journal or a quest log. To display the history to players, use a History Display: see History Display. Two Histories Every line is logged twice:
HistoryContents
Engine history: the Engine's dialogue_historyThe lines run by that Engine only.
General history: candy_de.general_dialogue_historyThe lines run by every Engine, in the order they were spoken.
For example, with one Engine for main dialogues and another for NPC barks, the main Engine's history contains the story without the barks, while the general history contains both. What Is Logged Spoken Lines Each Spoken Line is logged once it's over (after the player advances), in every Dialogue Mode, Voice mode included. Lines skipped because of a Disposition or a missing Variation aren't logged, since nobody said them. The logged text is the line as it was displayed: the chosen Variation, with variables and Word Substitution resolved, and the LLM's text when the line went through the LLM. The formatting added by the UI Element is left out: BBCode wraps, Lexicon formatting, speaker name and end-of-line string. Lexicon keywords are logged as their Disabled text, or as written when they have none (see Lexicon). Transitions A marker is also logged where the dialogue jumped, bridged, returned or ended, so that a History Display can show where one scene ends and the next begins. A dialogue that ends by reaching the end of its last Block is logged with an End marker too. Choosing What Is Logged The write_dialogue_history setting decides whether Spoken Lines are logged. Like the other speech settings, it is set on the Engine, on each UI Element, on each Actor (WriteDialogueHistory) and on each line (Write_Dialogue_History), and the most specific value wins (see Dialogue Modes). For example:
  • Turn it off on a bark Engine, so that barks never reach the history.
  • Turn it off on a narrator Actor, to log dialogue only.
  • Turn it off on a single line, such as a system message.
Transition markers follow the Engine's own write_dialogue_history only. Leave the history on even when your game has no History Display: it costs little, and a History Display can be added later. Entry Format Each history is an Array of entries, oldest first. Each entry is a Dictionary with a single key, which names what the entry is:
{"Speech": { "speaker_ref": "Alice", "display_name": "Alice", "speech": "Good morning!", "portrait": "Happy", "disposition": "" }}
KeyValue
"Speech"A Spoken Line: speaker_ref: the Actor Reference of the speaker. display_name: the name displayed for the speaker, in the language it was displayed in (see Translating Names). speech: the text (see What Is Logged above). portrait: the portrait the line named, as written. disposition: the line's Disposition condition, as written (see Dispositions).
"Jump", "Bridge"A Jump or Bridge. Its value contains changed_conv: whether the transition led to another Conversation.
"Return", "End"A Return, or the end of the dialogue. Its value is an empty String.
Reading the history in your own code:
for entry in candy_de.general_dialogue_history: if entry.has("Speech"): print(entry["Speech"]["display_name"], ": ", entry["Speech"]["speech"])
Lifetime The histories are stored in memory, and grow for as long as the game runs: Candy Dialogue Engine never clears them, and doesn't save them.
  • To preserve the history across save games, save the Arrays with the rest of your save data, and assign them back when loading.
  • To clear a history (when a new game starts, for example), empty its Array: candy_de.general_dialogue_history.clear(), or engine.dialogue_history.clear().
  • To limit its size in a long game, remove the oldest entries from the front of the Array.