Connecting a game engine

At some point the story stops being something you write and becomes something a game plays. This page is the seam: what crosses it, what does not, and where this manual hands over to the plugin’s.

The shape of it

You do not export a file and import it somewhere. The engine syncs: the plugin holds a key, asks for your project, and receives it as data.

1. You generate an API key for the project.
2. A programmer pastes it into the plugin’s sync window.
3. The plugin pulls the project and writes files into the game.
4. It syncs again whenever you have changed something worth pulling.

The key identifies the project, and the plugin’s sync tool carries TaleShard’s address with it, so there is nothing else to configure — no URL, no project id, no account details. Only a studio running its own TaleShard server sets an address, in the sync window’s Server fields. <!— Not yet true: the sync tool’s built-in address is still a local one until the release that turns production on (the plugin v1 plan, item O7). This paragraph describes that release. —>

Getting the key

Project settings → Export → the Unity integration section. See project settings.

The key is scoped to one project, and generating or managing it needs the manage project settings permission, which is the Admin role. See organizations and roles.

What crosses the seam

Your project is compiled into a payload with no TaleShard concepts left in it. That is the whole design: a game reads resolved data, not a story it has to interpret.

What goes	In what form
Boards, and the nodes and edges on them	Resolved — every field value already looked up
Node types	As templates: each field’s name, type and storage, and each repeater as a collection
Exits	With their gate, their content, their kind and what to do when blocked
Entities and entity definitions	Resolved, with references already followed
Variables, contexts and enums	With their types and their declared values
Tags	A flat table of id to label
Media	A table of id to location — a path for a build, a signed link for a share
Expressions	As parsed trees, not as strings
Rich text	Pre-rendered, per language
Diagnostics	Everything the build noticed and could not resolve

Two consequences worth holding on to.

Your game never learns your node-type table. It reads fields off a step and follows exits. Add a node type on Tuesday and no new build is needed for the game to understand it — which is the point of authoring your own node types at all.

Expressions travel parsed. The game does not re-implement the expression language; it evaluates a tree that TaleShard already understood, which is what keeps play mode and the game taking the same route through the same project.

What does NOT cross

Stays in TaleShard	Why
Your views and the composer	Presentation for you, not data for a game
Your looks, palettes and custom CSS	Play mode’s own presentation layer
Documents and spreadsheets as editable surfaces	Their values reach the payload where a field references them; the editors do not
The AI panels and their history	Authoring tools
Media codes	A code names a generated constant at build time; at runtime a game resolves a media id. See media.
Command declarations	The plugin reads them from the project document alongside the payload, not from the payload itself

The one thing a writer has to agree with a programmer

Commands. Everything else on this page is automatic; a command is the one place where a decision you make in the editor becomes work somebody has to do in the game.

A command you declare becomes a method in their code, and their build compiles whether they have written it yet or not. A command they have not written is never silent: one the story does not wait for warns once, naming the method, and moves on; one marked the story waits for this command to finish fails its wait with an error naming the method, and the story carries on — so a story never hangs at runtime waiting for something nobody wrote.

That is worth a conversation before you declare twenty of them. See commands.

Where to set the starting point

Project settings → Game Start → Entry node decides where a game build begins. It is optional for playing in the browser and it is what a build reads, so a project that plays correctly here can still open on the wrong scene in a game if it is unset.

Where this manual ends

Everything past the sync is a different product with its own manual:

The Unity plugin — what the plugin does, playing a story in a scene, reading a step, implementing the commands you declared, and extending what the generator writes.

Two pages there are the ones a programmer opens first: what the plugin does and play your first story.