Entities
Entities are the building blocks of a StoryBonsai project: scenes, nodes, variables, characters, locations, items, skills, codex entries, activities, audio cues, media, choice groups, and tags. You author entities in the editor (each one has an inspector panel), and the pages in this section document the fields you’ll find there.
Conventions shared by every entity
Renaming an ID
Every entity has an ID field: the renameable, expression-namespace
handle. You type this in expressions (Played(tag_companion_loyal)) and
pick from it in the editor’s pickers (the Speaker dropdown on a dialogue
event, the Tag picker on a node, and so on).
Renaming an ID propagates across the project: the editor updates every cross-reference, and rewrites the expression strings that mention the renamed entity by name. So var_gold becomes var_score in every condition and template after a variable rename, skill_logic >= 5 becomes skill_reason >= 5 after a skill rename, and node_intro becomes node_opening everywhere it appears in a visible-when or play-history check. You don’t have to chase the renames down.
Localization notes
Author-facing text fields that get translated (a character’s Name, a codex entry’s Body, a dialogue event’s Text) carry two companion fields in the inspector:
- Translator note: an optional hint you write for translators (register, tone, context). Shows up in the editor’s localization panel next to the source string. Has no runtime effect.
- Max length: an optional advisory cap on the translated string’s length, in characters. Shows up as a translator hint. The runtime does not enforce truncation.
Both are translator hints, not runtime contracts. The per-entity pages list them under the field they relate to.
All entity types
Narrative spine
- Scene: unified state-machine entity with intro / outro / update lifecycle.
- Node: the unit you author choices and events on.
- Character: speaker identity for dialogue.
- Tag: renameable label entity for grouping nodes, scenes, items, locations, codex entries.
Variables & expressions
- Variable: typed mutation target driven by Set variable events.
- Skill: RPG-style skill metadata; backs an auto-generated
skill_<id>variable.
RPG / authoring surfaces
- Codex: long-form content the host UI reveals on unlock.
- Activity: host-rendered mini-form with variable overrides.
- Item: inventory metadata (storage lives on a list-typed variable).
- Choice group: collapses sibling nodes into a single synthesized choice.
World layer
- Location: spatial entity in the world graph.