What the plugin does

The plugin syncs a project into assets, gives Blueprints and C++ a typed way to read them, and plays the story — and it keeps those jobs apart.

It syncs your project into assets

TaleShard > Sync in the main menu, or the TaleShard button on the level editor’s toolbar, drives the sync tool, which talks to the TaleShard server and writes two payload files. The plugin turns them into assets under Content/TaleShard/Generated/: the playable payload, one entity store per definition and the project-wide entity index, the enum, command, variable, board, node-type and media indexes, one string table per language, a manifest, and a gameplay-tag list in Config/Tags/TaleShardGenerated.ini that gives every code in the project a tag your Blueprints pick from a tree. Media files are imported as real textures and sounds.

A content change never needs a compile. A line edited, an entity added, a translation changed — every sync of that kind rewrites assets and stops. That is the loop a writer runs twenty times a day, and it stays free.

Blueprints read it through nodes that follow every sync

The plugin’s Blueprint nodes read the synced data directly: Get Entity Field and Get Node Field (pick a definition or a node type, then a field, and the output pin takes the field’s type), Get Story Variable and Set Story Variable, and the TaleShard Command event (one red event per command, its arguments on typed pins). Their menus list your project’s own names, and follow every sync without a compile. A name a sync removes becomes a compile error on the node that used it, and the sync window lists the Blueprints affected.

C++ gets typed code on a schema change

In a project with C++ of its own, a sync that finds the schema changed — a field, an enum option, a command parameter, a node type added or renamed — also emits C++ into your game module: one struct per entity definition, one enum per author enum, a command handler class with one typed event per command, and one accessor library per node type. That costs a build, on your normal terms — the same cost as adding a property by hand. The change report says what changed, and says when a restart is needed. The first such sync adds the plugin’s modules to your module’s Build.cs itself.

Generate C++ Types is Automatic by default: on when the project has a C++ module, off when it does not. Blueprints never need it. With it off, everything is still reachable by tag and by key; the generated layer is the typed view over the same data, never a second copy of it — see the typed C++ layer.

It plays a story

Place a TaleShard Story actor in a level and press Play: the story plays on the plugin’s dialogue screen, which types each line out, numbers the choices, greys a locked one with its reason, shows the speaker’s portrait and speaks a recorded line. Create New on the actor makes a screen of your own laid out like it.

Underneath is the TaleShard Player component, which a game that draws the story itself uses directly: bind its On Step Presented event and every step arrives already resolved — its fields, its choices, its cast — while the component forwards the session’s verbs (Advance, Choose, Back, Save, Restore and the rest). A node type gets its own handler class, one per type, instead of a switch; a command written by an author lands on an event you implement in Blueprint or C++, and can suspend the story until your game answers.

While the game plays in the editor, TaleShard > Story Debugger shows where the story is and what it holds, and jumps to any node — see the Story Debugger.

The modules

The split is what keeps a broken generation from taking the editor down with it:

• TaleShardCore — the dialogue engine, the expression evaluator, the text model and the save codec, as plain C++ with no reflected types. It is the port of the Unity runtime, graded by the same conformance fixtures.
• TaleShardRuntime — the session, the component, the value type, the asset types and the Blueprint function libraries.
• TaleShardUMG — the rich-text markup emitter, the presenter widget base, the dialogue screen and the TaleShard Story actor.
• TaleShardBlueprintNodes — the Blueprint nodes that read the synced data. Editor-only: each node compiles into ordinary calls on the runtime, so nothing of this module is in a packaged game.
• TaleShardEditor — the sync window, the Story Debugger, the process driver and the generators. Absent from a packaged game.
• TaleShardTests — the automation tests. Never shipped.

No module in the plugin ever references generated code. Generated C++ lives in your project, so a generation that fails to build breaks your game module and never the menu item that regenerates it; the documented recovery is to delete the generated folder and rebuild.