Documentation

Start here

• What TaleShard isA project is boards, a world, and rules — and it leaves as data a game engine reads. The one-screen model, before any of the detail.
• Your first boardMake a board, put two nodes on it, join them, and play it. Fifteen minutes, and every idea in the rest of the manual appears once.
• The workspaceEvery part of the editor window named once — the rail and its lists, the tabs and the pages, the panels, and every keyboard shortcut that is real.
• Where to go nextThe six tracks of this manual, what each is for, and which one to read depending on what you are trying to get done today.

Boards and the canvas

• Boards and the canvas

The node builder

• The node builder
• Build a node typeAuthor a node type end to end — fields, a repeater that makes real exits, an appearance, and a node of it on a board. About twenty minutes.
• Managing node typesThe Node Types section, creating and sharing a type, its code, the palette editors, deleting a type and what its nodes do, the destroys-nothing rule, and undo.
• The node-type packsEvery pack in the Add node types library — what it is for, the node types it holds, and the definitions, enums, variables and records it brings with them.
• Field typesEvery field type — what each stores, every option the builder offers, how it is edited on the canvas, what a game engine receives, and what breaks.
• What a node body holdsThe eleven item kinds a node is built from — fields, headings, traits, repeaters, rows, elements, actions, references, radars, totals, lookups — and their data.
• How a field is shownEvery per-field setting beyond its type — label, reading, styles, grid placement, box, thumbnails, tint, visibility, the node dialog and placeholders.
• Appearance and sizeEvery type-level setting — identity, header band, style, body layout, overflow, shape, marks, colour and size — and which one wins when two claim one axis.
• Handles, ports and flowEvery handle option, typed ports, the connection policy and its promotion rule, what makes an exit or a branch row, and the play-mode read-out.

Modelling the world

• Definitions and traitsThe shape of a thing — every field on a definition, the seventeen field types, how inheritance and traits compose, and what a schema change costs.
• EntitiesThe instances — every field on an entity item, how codes are uniquified, the four view kinds and the composer, and what reaches a game engine.
• Views and the composerHow to give a definition more than one way of being read — choosing a starting template, composing the block tree, and what a view can and cannot change.
• Documents and spreadsheetsLore documents and spreadsheets are one object with two kinds. The record, the editor, how mentions work, and what a plan gate actually blocks.
• SpreadsheetsTyped tables and free-form sheets — what actually differs, the ten column types, AI columns and cells, and the entity grid's smaller set of powers.
• Formula referenceAll 97 spreadsheet functions, the A1 reference rules, operator precedence, the seven error values, and how a recalculation actually happens.

Variables, logic and commands

• Variables, contexts, enums and bitmasksFour object types in one panel — every field, how a dotted name resolves, how enum and bitmask values are assigned, and the complete expression language.
• TagsThe tag record, what can be tagged, condition-only tags and the requirement rows they gate, and how a tag reaches a game engine.
• Conditions and gatesHow to make an exit conditional — the two kinds of gate, the blank-gate trap, what a condition may not do, and why the Visual and Code views cannot disagree.
• Scripts on a nodeMaking something happen when the story arrives — where a script lives, a script on an item, what it may do and touch, and what a failure costs.
• CommandsHow the story tells a game to do something — the declaration, the nine parameter types, the waiting switch, and exactly what crosses the boundary.

Playing and styling

• Play modeWalking the story and dressing it — the toolbar, every key, what a save carries, the three container kinds, the five looks and the twenty-one elements.
• MediaThe media record, which file types upload and the three size guards that decide, how thumbnails are made, and what a media code actually resolves to.

Voice and audio

• Voices
• Designing a voiceMake a character's voice from a description or start from a ready-made one, audition it, keep one, then remix it, direct it and cast it per language.
• Casting charactersGive each character a voice, find who is not cast yet, re-cast a character and re-record their lines safely, and teach the voices to say your invented names.
• Producing the linesVoice a board a scene at a time — direct it, generate the missing lines, compare takes, approve the keepers, and attach real recordings by hand.
• Working with a recording studioExport the recording script a studio books from, report which lines ship AI audio, and bring the delivered recordings back onto their lines in one pass.
• Music and sound effectsDescribe a piece of music or a sound, generate several takes side by side, improve the description for the engine, and keep the takes you want in Media.

AI

• AI Generation
• Generating a definition, an item, an imageThree of the generator tabs in Thalia's dock control by control — what each sends, what the result card does, and what Apply actually writes into your project.
• A document into a boardTurn a scene you already wrote into a playable branching board — with your lines kept, your characters matched, and every node reviewed before it lands.
• Thalia, the assistant dockThalia, the project-aware assistant in the right-edge dock — opening it, her fifteen tools, which twelve write, why she auto-commits, and how to undo a session.

Working together

• Working at the same timeWhat syncs live and what does not, whose cursor you see where, what the connection pill means, and exactly what happens when the connection drops.
• Undo in a shared projectWhy Ctrl+Z can never revert a colleague's work, which stack it drives and how that is decided, what counts as one step, and what is not undoable at all.
• HistoryReading the list of steps and jumping back to any of them — and the second, durable history a document keeps, which is a different feature entirely.
• Organizations, roles and invitesThe two role systems and the complete permission table, how an invite actually works, what consumes a seat, and every refusal you can hit.

Getting it out

• LocalizationThe translation round trip — Excel and XLIFF, exactly what is translatable, the placeholder rules, and every message a bad import produces.
• Screenplay importFinal Draft and Fountain into boards — which formats parse, what a scene actually becomes, the grouping and routing controls, and what is not read.
• Project archivesTaking a whole project out as a ZIP and bringing it back — what is in the archive, what import actually does, and why the version must match exactly.
• Connecting a game engineHow a finished project reaches a game — the API key, what the sync sends, what your game never has to learn, and where the plugin's own manual begins.

Project settings

• Project settings

Start here

• What the plugin doesThe one-screen mental model — your project becomes three files, and C# reads them. No parsing, no node-type table.
• RequirementsThe Unity version, the one required package, what is optional, and which platforms the sync tool has actually been run on.
• What to get right firstThe ordering rules and one-shot constraints that cost an afternoon each — the media bootstrap, the frozen policy, restart versus start, and settling a command.
• Play your first storyThe smallest program that starts a session and prints a line — no Unity, no MonoBehaviour, about thirty lines.
• Where to go nextSeven tracks and what each one is for, so you can stop reading in order and start reading what you need.

Concepts

• The three filesruntime.json, codegen.json and the generated code — who writes each, who reads each, and what changes when.
• Node meaning is resolved onceWhy the engine never re-derives what a node means, and why a type-to-field-keys table is not something anyone can write.
• Expressions ship as treesEvery gate and script is parsed once at sync time. The engine evaluates a tree and ships no parser at all.
• The two seamsThe engine is portable and has no Unity or Unreal in it. The integration layer is where the game engine is allowed. What belongs on each side.
• The payload, field by fieldEvery type in runtime.json as the engine reads it — the traversal half, the project tables, and the asymmetries the format encodes on purpose.

Authoring for a game

• What a build needs from a projectThe authoring decisions that reach a compiler: codes that become C# names, what an unimplemented command does, option sets, and the start nothing will guess.

Playing a story

• Starting a sessionTaleShardPlayer, what it needs, its two construction seams, and why it is not a MonoBehaviour.
• Reading a stepPlayStep, ResolvedField and the accessors — the whole read surface, in one page.
• Choices, and why one is lockedAdvancing, selecting, and drawing an option the player can see but cannot take — including the progress reading behind it.
• One handler per node typeA node type's logic lives in its own file — a handler asset the player routes to, after the step event everything else listens to.
• Entity display: name, colour, portraitEntityDisplay resolves a speaker once — and colour is user data, so a game asks whether there is one rather than assuming.
• Implementing commandsThe generated hook a story calls, the starter file a sync writes, what happens if you never override it, argument coercion, and why not to hand-register.

The generated code

• What a sync generates to start fromGameBootstrapper, GameSession, GameData and the two behaviours — the seven things Setup does in order, and which entry point to use.
• The generated constants and storesNodeTypes, GameBoards, EntityCodes, GameTags, MediaRegistry and the four stores — the typed names that replace every string literal in your game code.

Media

• Where synced media landsThe media path and its Resources segment, the addresses assigned, the import that must happen, and the combination that ships every file twice.

The plugin and sync

• What a sync writesEvery file a sync produces, which of them land in your Unity project, which ship in a build, and what belongs in version control.

Extending

• Post-sync hooksRun your own code after a sync finishes — validation, custom imports, extra generation.
• The generator pipelineICodeGenerator, the twelve domain generators and the order they run in, and the four ways to change what a sync writes without forking the plugin.

Reference

• The play loopEngineSession, DialogueEngine, PlayStep and the enums around them — every member you call, and the handful that exist for the engine rather than for you.
• What a step containsResolvedField and its typed accessors, choices and why they are blocked, entities, actors, and the five reference value types.
• Saving a playthroughWhat a save carries and what it deliberately does not, the two load rules that are not configurable, and why you must not use your own serializer.
• Loading mediaMediaAddress, MediaLibrary and the source interface — how a reference becomes an asset, who owns what, and the release rule that has no automatic fallback.
• The Unity playerTaleShardPlayer and the component that owns one — the four layers, every verb, the policy that freezes at construction, and how a playthrough ends.
• Scripting and commandsIScriptRuntime, RuntimeValue, and the token an awaited command settles — the seam between the story and your game code.
• DiagnosticsThe two channels the engine reports on, the sinks you can plug into them, the thread-safety contract, and every code the runtime emits.
• Drawing a line of textStoryText, the TextMeshPro formatter and the field converter — turning a field into a drawn line without losing a stage direction to a stray angle bracket.
• Colour and how an entity looksContrastPolicy and the APCA measurement behind it, EntityDisplay and EntityPalette, and the one hex parser everything shares.
• The project's UI stringsUIStrings — the one thing this layer localizes, why everything else is already done, and the gate that breaks if you copy a translated value into a variable.
• Generated entity dataEntitySet and the contracts generated code is written against — the typed way into a project's entities, and the seal a lookup depends on.

Start here

• What the plugin doesThe modules, the TaleShard menu, what a content sync writes without a compile, how Blueprints and C++ read it, and how a story plays.
• RequirementsThe supported engine version, installing the release zip, when a compiler is needed, where the sync tool goes, and where the API key lives.
• Build your first story in BlueprintsFrom a blank Blueprint project to a playable, saveable, bilingual dialogue — install, sync, one actor, your own screen, commands, character data, packaging.
• Play your first storyThe smallest program that starts a session and prints a line — no actor, no widget, about forty lines of C++, or four Blueprint nodes.
• Your first attemptThe ordering rules and one-shot constraints that cost an afternoon each — the frozen policy, handlers before Play, and the tags the sync owns.
• Where to go nextThe tracks and what each one is for, so you can stop reading in order and start reading what you need.

Concepts

• The three filesruntime.json, codegen.json and the generated code — who writes each, who reads each, and what changes when.
• Node meaning is resolved onceWhy the engine never re-derives what a node means, and why a type-to-field-keys table is not something anyone can write.
• Expressions ship as treesEvery gate and script is parsed once at sync time. The engine evaluates a tree and ships no parser at all.
• The two seamsThe engine is portable and has no Unity or Unreal in it. The integration layer is where the game engine is allowed. What belongs on each side.
• The payload, field by fieldEvery type in runtime.json as the engine reads it — the traversal half, the project tables, and the asymmetries the format encodes on purpose.

Authoring for a build

• What a build needs from a projectThe authoring decisions that reach a compiler: codes that become tags and names, what an unimplemented command does, option sets, and the start nobody guesses.

Playing a story

• Starting a sessionThe TaleShard Player component, what it needs, the two ways to get a session, and the verbs that drive one.
• Reading a stepThe step handle, the resolved field, and the two function libraries that read them — the whole read surface, in one page.
• Choices, and why one is lockedTaking a choice, and drawing an option the player can see but cannot take — with the reason the engine already wrote.
• One handler per node typeA node type's logic lives in its own class — a handler the session routes to, after the step event everything else listens to.
• Entity display: name, colour, portraitThe entity palette resolves a speaker once — and colour is user data, so a game asks whether there is one rather than assuming.
• Implementing commandsThe command handler class, the two ways to register a command, the completion a waiting story hands you, and the one event that catches the rest.
• Entity scripts and instancesRunning the script an entity holds in a code field, what `self` and a field's roles are, spawning entity copies that change on their own, and saving both.

The generated assets and code

• What a sync writes as dataThe assets and gameplay tags every sync writes without a compile — the payload, the indexes, the stores, the string tables, the manifest.
• The typed C++ layerWhat a schema change generates into your game module — native tags, enums, entity structs, row structs, the command class, field accessors, variables.

Media

• Where synced media landsThe media folder, the assets the import makes, the index that maps a reference to them, and the one thing a rename changes.

The plugin and sync

• What a sync writesEvery file a sync produces, which of them land in your Unreal project, which ship in a build, and what belongs in version control.
• The Story DebuggerThe editor tab that shows the story playing in the editor — where it is, its variables, what it played — and jumps to any node or opens it in TaleShard.

Extending

• Running your own code after a syncThe two editor-module delegates that fire when a sync and its generation finish — for validation, custom imports, or extra generation of your own.
• The editor APIThe public types an editor module of yours can reach — the module, the sync service, the asset generator, their results and states, and the two commandlets.

Reference

• Saving a playthroughWhat a save carries and what it deliberately does not, the two load rules that are not configurable, and why the text is the artifact.
• Loading mediaThe media index, the resolved address and the Load Media action — how a reference becomes an asset, and who holds it afterwards.
• The Unreal playerThe session, the component that owns one, the subsystem that builds one without an actor, every verb, the frozen policy, and how a playthrough ends.
• DiagnosticsThe two channels the engine reports on, the event that carries them to Blueprint, every code the runtime emits, and the sync codes you act on.
• Drawing a line of textThe presenter widget, the rich-text markup it draws with, and the style table that decides what a mention or a heading looks like.
• The project's UI stringsUI Strings — the one thing this layer localizes, why everything else is already done, and the gate that breaks if you copy a translated value into a variable.