Line Schemas
A line schema is a file that describes one Command to Candy Dialogue Creator: its fields, their defaults, their help, their dropdowns and their checks. Every Command Candy Dialogue Creator offers is described by a schema: to write Lines of a Command of your own, add its schema.
A schema only describes the Command to the editor. What the Command does is a script in your game: see the Candy Dialogue Engine documentation, under Advanced.
Place schemas in a mod's Line_Schemas folder (see Mods), one .txt file per Command.
A First Schema
Suppose your game has a Command of its own, Give_Item, whose script reads an Item and an Amount. Its schema, give_item.txt:
{
"type": "Give_Item",
"title": "Give Item",
"category": "My Game",
"colors": { "Text": Color(1, 1, 1, 1), "BG": Color(0.2, 0.45, 0.25, 1) },
"summary": "{Item} x{Amount|1}",
"fields": [
{
"id": "Item", "label": "Item", "widget": "line_edit", "default": "",
"tooltip": "The item the player receives.",
"values": ["Item name", "{expression}Expression"],
"checks": [ { "check": "required" } ]
},
{
"id": "Amount", "label": "Amount", "widget": "line_edit", "default": "1",
"tooltip": "How many the player receives.",
"values": ["1+: A whole number.", "{expression}Expression"],
"checks": [ { "check": "number", "whole": true, "min": 1 } ]
}
]
}
After a restart:
- Give Item is offered among the buttons of the Dialogue Buttons panel, in a "My Game" category, and can be assigned a shortcut.
- Its Lines are displayed in the Navigator as "Give_Item: Potion x3", in the colors set.
- Its form contains two fields, with help, a required value and a number check.
- Exported Lines are written as
"Give_Item": { "Item": "Potion", "Amount": "3", "Meta": {...} }.
The Schema
| Key | Description |
| type | Required. The Command's name in the Dialogue file: the name of its script in your game. No spaces. |
| fields | Required. The list of its fields, in order. |
| title | Its name in Candy Dialogue Creator. |
| category | The category of its button and of its row in the settings. |
| category_tooltip | The tooltip of its category's heading, in the Dialogue Buttons panel's settings: what the category's Commands are for. Only one Command of the category needs it. |
| colors | The text and background colors of its row in the Navigator, until Settings > UI > Navigator Colors sets others. |
| summary | What its Lines display in the Navigator after the Command's name. {Id} is replaced by the value of that field, and {Id|text} by text when the field is empty. |
| short | What its Lines display in the Navigator's Short mode: a template, or a list of templates, of which the first whose fields all contain a value applies. |
| layout | The form it opens with in the Dialogue Editor. Without one, a single list of all its fields. |
| Key | Description |
| id | Required. The field's key in the Dialogue file. |
| label | Its name in the form. |
| widget | How it's edited: line_edit (one line of text), text_edit (several lines), color, group, list or map. |
| default | Its value in a new Line. Always a text, in quotes: "1", "", "null". |
| tooltip | What the field does, in a sentence or two. Displayed by the ?. |
| values | The kinds of values it accepts, each displayed as a bullet by the ?. |
| dropdown | Its dropdown. See Dropdowns. |
| checks | The messages displayed for its value. See Field Checks. |
| visible_when | A rule that hides the field while another field's value renders it irrelevant. See below. |
| height | For text_edit: its height in pixels, or "fit" to grow with its text. |
"5", on and off are "1" and "0". Never write a number, true or null without quotes as a default.
Overrides
A field that overrides something the game otherwise decides uses "null" as its default: the text null, meaning "not set". Its dropdown then receives a No override (null) item automatically. Your Command's script must treat "null" as a key that was left out.
Symbols in Help
In tooltip, values and check texts, write your project's symbols as {expression}, {role}, {vardict} and so on, never as the symbols themselves: Candy Dialogue Creator replaces them with the symbols of Settings > Project > Symbols.
Groups, Lists and Maps
A field can contain other fields, listed in its own fields key.
| Widget | Description |
group | A titled set of fields, stored as a dictionary under the group's id. |
list | Entries that repeat, stored in order. With "entry": "named", each entry has a name the user enters. |
map | Entries the user names, stored under their names, such as the players of a Media Play. |
"entries": "commands" contains Lines instead of fields, in order, as a Block does: the Commands of a Text Event. Each entry is a Line of its own Command, so the same Command can appear several times. Forms can't display it: set "in_forms": false on it, and edit it with a widget of its own, as the Text Event Editor edits Text Events.
Lists and maps accept two more keys: entry_label, what an entry is called in tooltips ("choice"), and entry_prefix, what new entries are named after ("Choice" produces Choice_1, Choice_2).
{
"id": "Rewards", "label": "Rewards", "widget": "list", "entry": "named",
"entry_label": "reward", "entry_prefix": "Reward",
"tooltip": "What the player receives.",
"fields": [
{ "id": "Item", "label": "Item", "widget": "line_edit", "default": "" },
{ "id": "Amount", "label": "Amount", "widget": "line_edit", "default": "1" }
]
}
Always place a Command's entries in a field of their own, as here, never as the Command's own keys: the Command then retains room for other fields.
Fields That Hide
visible_when displays a field only while another field's value renders it relevant:
"visible_when": { "field": "Mode", "equals": "Timed" }
"visible_when": { "field": "Mode", "in": ["Timed", "Delayed"] }
"visible_when": { "field": "Target", "not_empty": true }
"visible_when": { "field": "Count", "greater_than": 0 }
"visible_when": { "all": [ rule, rule ] }
"visible_when": { "any": [ rule, rule ] }
"visible_when": { "not": rule }
Other tests: not_equals, not_in, less_than, begins_with, ends_with, contains, not_contains, is_number.
- The named field is a sibling of this one. Start its name with
../ to name a field one level up. - Values are compared without regard to case, and numbers as numbers.
- A value that is an expression, or
null, leaves the field displayed: its value is only known when the Line runs.
Hiding a field never removes it from the Line. Only write rules on plain data fields, never on overrides.
Meta Fields
Candy Dialogue Creator adds the Meta fields to every schema automatically: Meta Reference, Meta Notes and Custom Data on the Line, and Custom Data on every entry (see Meta Data). Don't list them.
Replacing a Built-In Schema
A schema whose type is a built-in Command's replaces that Command's schema. Use this with care: the built-in schemas follow Candy Dialogue Engine's Commands, and an update of Candy Dialogue Creator won't update your copy.
A Command's form is rearranged without a schema, through its line layout (see Line Layouts).
Commands Without a Schema
A Dialogue can contain Lines of a Command that Candy Dialogue Creator has no schema for, such as an imported Dialogue that uses your own Commands. Such a Line still opens: Candy Dialogue Creator builds a plain form from the Line's own data. A schema adds the rest: a button to add the Command, defaults, help, dropdowns and checks.
