The payload, field by field

runtime.json is the file a game plays from. EnginePayload in C# and FTaleShardPayload in C++ are that file as the engine reads it — the same members under each language’s naming — and this page is every type in it.

Every node in it has already been resolved by the exporter, so nothing on this side re-derives what a node type means. That is the whole point of the format — see node meaning is resolved once.

Reading one

EnginePayloadReader is the one parse of that file: both the code generator and the dialogue engine come through it.

Every member tolerates absence — a missing array reads as empty — but the payload as a whole does not tolerate a wrong version. Parse once and share the result.

The top level

Media is keyed by both the media item’s id and its storage id, because a stored reference may hold either. MediaFocal is keyed the same two ways and covers only the pictures with a face marked; it is what a reference minted from a bare id — an entity’s portrait, an entity’s asset field — answers its focal point from, the way such a reference answers its url from Media. MediaKind is keyed the same two ways; the engine reads it to decide which media fields are sound effects — a field is an sfx clip on its step only when its file’s kind is audio.

Tags omits a tag that has no label — the id is never a fallback for one.

Surface Diagnostics rather than discarding them. A field the exporter could not read is not a type error on this side, so nothing else will ever report it. EngineSession replays them into its own diagnostics channel for exactly that reason.

The graph

EngineBoard

Id · Name · StartNodeId · Nodes · Edges.

When StartNodeId is absent or names a node that no longer exists, the entry is derived: a root with an outgoing edge — not merely a root, since a board is usually full of isolated strays and every one of them is a root.

EngineNode

Scripts run on entering the node, in document order, before any step is emitted.

ChoiceTextKeys are already selected by the exporter, in document order. Use them rather than re-deriving them — though when they are used is the engine’s decision: a contentless exit borrows them only when it is one of several silent, ungated, underived ways out.

Presents being false silences every one of the node’s fields, which no single field can say for itself. It does not silence a choice’s label.

EntryPoint is what the author’s node type declares. A board whose author never used a declaring type still has ways in — they are found structurally.

EngineField

A shape a consumer could not draw arrives as Value: null rather than as a nested object — so a reader never has to defend against one. An itemCounts field carries its entries in one shape, the same one everywhere the value sits: Items here, Items on an exit that hands them over, and FieldItems on an entity — each entry an unresolved entity reference, a count, and its cell when it has one. The payload view looks each entry up and hands the resolved field its references, its counts as the value, and its cells, so ResolvedField.Items() reads the author’s pairs; an entry naming an entity the payload does not carry is dropped whole, its count and its cell with it, and reported as item-missing — the same rule for an exit’s hand-over and an entity’s field. The cells are already laid out by the editor: with a capacity on the field (maxItems, the grid), every entry the editor shows in a cell carries that cell, so a chest reaches the game as the author sees it; without one only the entries she placed herself carry one. The field’s declaration — on the entity definition or the node type’s field template — carries maxItems and, when the grid has a fixed width, columns, and the payload view hands both to the resolved field as ResolvedField.Capacity and ResolvedField.Columns, so a game that draws the grid reads its size off the step’s field and places a cell at row slot / Columns, column slot % Columns, never walking back to the type.

EngineRichText is Html and Text — the same content rendered twice, at export time.

EngineRef

A reference the exporter has already looked up, so a consumer performs no lookup of its own.

EngineRepeaterRef is RepeaterId · RepeaterCode · InstanceId · Index · Ported · Gate · GateExpressionId · Plays · Weight · Once · Parent. Parent is present only on a row of a list declared INSIDE another list’s block: it is the outer row’s own ref, and its InstanceId is what you pass to read just that row’s inner rows. The code names the generated list member. Ported is present, and true, when the repeater’s block carries a source handle: its rows are the node’s exits, each row one of the step’s choices — a generic presenter reads such a row as a choice, never as content, and its fields also ship with Presentable false. Gate is a read row’s own condition, the source — present when the block declares one and the repeater is not ported — and GateExpressionId is the id of its parsed expression, null when the gate is null or blank. The engine has already applied it by the time a step exists: a row whose gate evaluated false is dropped whole, none of its fields reaching the step, and a row whose gate is blank is kept, since the author has written no test yet. A ported row carries neither; its condition is its exit’s.

Plays says which of a read list’s rows are presented, after the gate: "first" keeps the holding row with the lowest Index, "random" keeps one holding row drawn by Weight (zero never fires; one when the block has no weight number), "leastRecent" keeps the holding row said longest ago — a row never said beats every row that was, and the lowest Index wins among equals; while any holding row carries a condition (a non-blank Gate), only those rows compete, so an “any time” filler waits for a moment none of them fits — and absent keeps every holding row. The engine has already applied it too, so the step carries only the rows that play. The random row is drawn from the playthrough’s seeded generator — the same one a random branch and a script’s random() draw from — and the number is consumed the moment the step is presented, and again whenever a rollback or a restore presents that step again, so a save, a rollback and a redraw all show the same row and nothing drawn while the row is on screen — a NextLine, a script’s roll() — receives its number. A ported row carries neither key.

Once is present, and true, on a read row whose block’s once flag the author ticked. Such a row plays once per playthrough: once it has been said, the engine skips it exactly as it skips a row whose gate failed, under every Plays. A row is said when a step presents it or NextLine returns it; the engine keeps that memory — for a "leastRecent" list’s rows and for a Once row, and for nothing else — in the save as SaidRows, so a load does not forget it, and each moment of the rollback window carries the memory as it stood when that moment was drawn. A ported row never carries Once.

EngineScript is Key · Code · Source · ExpressionId.

Exits, edges and gates

EngineExit

One exit the node’s type declares.

An absent gate passes. A present but blank gate fails on an exit taken automatically, since a blank gate there is an unfilled one, and is no condition on an exit the player is offered (ExitRules.BlankGateFails). The same holds for each of ExtraGates.

The ExitKind derivation, when the author left it unset: content makes it an offer, otherwise a gate makes it a branch, otherwise it continues.

Empty ContentKeys means there is nothing to show, so the exit is a branch rather than a choice. The runtime adds a second source — the edge’s own label. An exit that is offered all the same (a declared offer) and has neither reads its Label as a third source.

An exit’s scripts and items belong to the moment it fires. The engine runs Scripts after the node’s own scripts and before the target node is processed, and takes Items at the same moment; both ride to the next presented step — the runs on its Trace.ScriptsRun, the items on its Trace.Received — so a Loot roll’s drawn outcome reaches the player through that one outcome and no other. The items are taken as ids and resolved when that step is composed, after the exit’s scripts and the target’s own have run, so a script on the exit that writes the item’s field is seen on the entry. The engine keeps no inventory and merges nothing.

A weight changes how a silent node leaves. With no weight anywhere, the first passing flow exit is taken. When any passing flow exit carries one, the engine draws one number from the playthrough’s seeded generator and picks among them by weight — an exit with no weight counts as one, and a weight of zero never fires. When every weight is zero nothing is drawn and the path ends there, exactly as it ends at a node with no exits: a waiting call frame resumes its caller. The draw is replay-safe for the same reason a script’s roll is — the moment’s recorded generator state puts the generator back, so backing up and advancing again draws the same exit.

EngineExitAnswer, the Quiz on an exit, is Correct and FeedbackKeys — the row’s boolean, and the keys of its feedback fields into the node’s Fields, empty when the block declares no feedback field. The keys are structural, like PictureKey: a blank row still carries its key, and the engine skips the feedback step on the resolved text instead. The engine offers such an exit as a choice whatever its own port carries; what happens after the pick is the node’s Quiz, below.

EngineItemCount is one entry of entities-with-counts, wherever the value sits — an exit’s Items, a node field’s Items, an entity’s FieldItems: Ref (an entity reference, not looked up — the engine resolves it when it reads the entry), Count (a whole number of one or more), and Slot (the cell of the inventory grid the entry sits in; absent in the JSON, null here, when it has none). One shape for the three, so a reader parses it once. An entry naming an entity the payload does not carry is dropped, its count and its cell with it, and reported as item-missing — against the exit, the node field or the entity field it sat on.

EngineEdge

Both the edge’s condition and the exit’s own gate must pass.

EngineRequirement

A property of the node itself, not a field its type declares. Any node may carry any number, and they compose by AND.

A deleted tag still ships its id here. Resolve the label to null rather than discarding the row, which is real and editable.

EngineRequirementCheck

The same shape for a requirement, a gate and an edge condition — so a blocked option can name what the player needs rather than show source.

Names are computed at export time, since there is no parser on this side. Which checks failed is a runtime question — evaluate each leaf and draw only the failures.

GateChecks is empty when the gate is absent, blank, unparsed, or a bare literal.

EngineJump

FieldKey — which of the node’s fields carries the target — and ReturnAfter, which pushes a call frame so the path returns here when the jump ends.

EngineTakenBy

Which one of a node’s track rows plays, chosen by a number variable the game advances — an hour, a turn, a day, an alert level. A routine that follows the clock, a week that follows the day.

EngineTakenRow is RepeaterId · InstanceId — the same address every field and exit of the row carries in its Repeater — · Ported · Start · Duration · Condition · ConditionExpressionId. Start is the row’s place on the ruler, null when unset; Duration its length, null for a mark. Condition is a read row’s gate or a ported row’s exit gate, null when it has none; a blank one is none here.

The rule, in Rows order:

1. the first row with no start whose condition holds — a row with no start and no condition is never taken, because it says nothing about when;
2. else, when the variable’s value is a finite number, the first row with a start whose span holds the value and whose condition, if it has one, holds. A value that is not a number takes no span.

A span runs from its start, included, to start plus duration, excluded, so 6 for 6 and 12 for 6 never both hold 12; a row with no duration holds exactly its start. With Wrap set, the value and the start are both read round the ruler (((x % wrap) + wrap) % wrap), so 22 for 4 on a 24-hour clock holds 23, 0 and 1, and a duration of the whole ruler or more holds every value.

The engine has already applied it by the time a step exists. A taken read row is the one track row the step presents; the others are dropped, after the row gate and before Plays. A taken ported row has its exits tried first, as flow exits whose own gate the rule already answered — followed, never offered as a choice — every other row’s exits are removed, and the node’s own exits follow. No row taken means no track row plays and the node’s own exits apply.

EngineQuiz

A question, resolved: RepeaterId · CorrectPortId · WrongPortId · Score. Its answer rows are the node’s exits carrying Quiz, and the two ports are the type’s first two node-level source handles.

The engine offers the answers as the step’s choices; after a pick it presents the picked row’s feedback as a step of its own, skipped when the feedback is empty; then it takes the correct port’s edge when the row is correct and the wrong port’s otherwise. WrongPortId is null when the type declares one source handle only — a wrong pick then ends the path. Score is a script, the increment of the score variable by the question’s worth, run on the correct path exactly as a script slot is, so the next step’s script list names it as quiz:score. It is null when the type names no score variable or the instance leaves it unset; such a question counts nothing, and the payload’s own Diagnostics say so.

The feedback step is recognised by how its moment was entered — from the question itself, through the answer’s port — and every way a step is re-drawn rather than walked to reads the same fact: a save taken on the feedback restores as the feedback, and a language switch keeps it the feedback.

The project tables

EngineNodeType

Type · Code · ClassName · Label · Fields · Repeaters · Presents · EntryPoint · TrackLengthField. The last is the code of the node-level number field that is the length of the type’s track — what a handler waits for before leaving — present only when the type names one; a type whose lanes have no declared length runs until its last row ends.

EngineFieldTemplate

Codes are unique per namespace rather than per type, so a type can carry the same code both at its top level and inside a repeater. Qualify by RepeaterCode when addressing one.

EnumRef is present only for an enum-backed field. A select with inline options carries no enum and no integer values, so it can only produce a plain string — and this being absent is how you know.

EngineRepeaterTemplate is Id · Code · ClassName · Label · Min · Max · StartField · DurationField · PauseField · EveryField · RepeatField · Ported · GateField · Plays · ParentRepeaterId. Plays is the list’s "first", "random" or "leastRecent" (see EngineRepeaterRef.Plays), absent when every holding row plays. ParentRepeaterId is present only on a list declared inside another list’s block, and names the outer one. StartField is the code of the block’s number field that places a row in time — present only when the block marks one; a repeater with no start is an ordinary list, not a lane. DurationField is the code of a row’s duration in the same unit, never present without a start. PauseField is the code of the number field a conversation waits after each row — present only for a repeater drawn as a conversation (bubbles or screenplay). Ported is the block’s own copy of the flag above: its rows are the node’s exits. GateField is the code of the block’s condition field a read row is gated by — present only on a repeater that is not ported and whose block declares one, so the generated constant names exactly the field the engine skips rows by.

EngineEntity

The definition names its fields by name, so resolve a name to an id before looking one up.

An itemCounts field on an entity travels in the one shape it has everywhere: FieldItems[fieldId] is the entry list, each entry exactly what a node field’s Items and an exit’s Items carry. The payload view resolves them into the resolved entity’s field, so ResolvedField.Items() reads a recipe’s ingredients, or a chest’s contents, exactly as it reads a loot row’s; an entry naming an entity the payload does not carry is dropped with its count and its cell and reported as item-missing.

Two synthetic keys, which are not field ids: __name__ in Localizations, and __description__ in RichText — the description every item has and no definition declares.

An entity carries only the translations an author can edit: its name’s when its definition allows translated names, its description’s when it allows translated descriptions, and a field’s when the field is marked localizable. Anything else falls back to the master value.

EngineEntityDefinition is Id, InheritanceChain, CustomFields and MentionLook. InheritanceChain (inheritanceChain on the wire) is the ids of the definitions it inherits from, nearest first; the key is omitted when it inherits from nothing, and reads as an empty list. It is what makes an entity of this definition the right kind for a script role typed by any of them. CustomFields is every field the definition has, in this order: each ancestor’s (its traits’ fields, then its own), then the definition’s traits’ fields, then its own. A trait field’s Id is the key its value sits under in FieldData (<instance>__<field>, through a nested trait <outer>__<inner>__<field>) and its Name carries the trait’s prefix (stats.armor). MentionLook may name any of them. EngineEntityField is Id · Name · Type · Multiple · MaxItems · Columns · Computed · Roles — Multiple nullable, so a payload that predates the key reads as false; MaxItems and Columns the same grid declaration EngineFieldTemplate carries, present only on an itemCounts field that declares them, and reaching the resolved entity field as ResolvedField.Capacity and ResolvedField.Columns. Computed is true on a formula field and absent otherwise: its value in FieldData or CodeFields was worked out from the item’s other fields when the payload was built. It is fixed for the playthrough — a script that writes it is refused, and a saved value on it is dropped on load. Roles (roles on the wire) is present only on a code or condition field whose script receives more than self: each an EngineScriptRole, Name (target) and DefinitionId (the entity definition its value belongs to). A run must pass a value for every role and for nothing else, each an entity of that definition or of one whose InheritanceChain names it; the key is omitted when there are none, and reads as an empty list.

MentionLook (mentionLook on the wire) says how an @-mention of one of the definition’s records draws in rich text. Absent means its name, and the key is omitted rather than written empty, so a project that declares no such definition keeps the payload it had. The one look today is a keycap:

"mentionLook": { "as": "keycap", "keyField": "keyName", "padField": "padControl", "touchField": "touchGesture" }

The three field slots name custom fields by name, each optional, and each a preview only — what the editor draws on the canvas and in play mode. A game draws the player’s current binding, which it resolves itself, and reads these only as a last-resort fallback. An as this reader does not know reads as absent rather than failing the load, so a payload from a newer editor draws such a mention as the record’s name; a blank slot reads as null. The payload view hands the look to every entity of the definition as ResolvedEntity.MentionAs, and the entity display marks a mention of one as an action — see an input action’s glyph.

EngineVariable, EngineContext

Id · Code · Type · DefaultValue, plus an expression id for a condition-typed variable — a named expression rather than a value, whose authored source is its default value.

The runtime resolves a variable by code, never by id.

EngineContext is a Code.

EngineEnum

Id · Code · Kind (enum or bitmask) · Options.

An enum is named by its code — what an author types before the dot — and a member by an option’s value, which is also what a stored select field holds. Both sides of a comparison are therefore the same string, which is what makes state == GameState.Hostile resolvable.

EngineEnumOption is Value · IntValue. The integer is what lets a generator emit an integer-backed enum, and it is absent for a select with inline options. An option carries no label here; the generated enum takes its labels from codegen.json.

Expressions

Expressions maps an id to one authored expression, parsed once at export time. An engine ships an evaluator and no parser, so this tree is the only form an expression can be evaluated from — see expressions ship as trees.

An expression that did not parse is refused at evaluation time — a gate reads false and is reported, never true.

EngineDiagnostic

Severity · Code · Message · BoardId · NodeId · FieldKey · NodeType.

The same shape as the runtime’s own diagnostics, which is what lets ReportPayload replay them into one channel without translation.