Skip to content

Unreal

The native C++ runtime, wrapped in a Blueprint- and C++-friendly plugin. It loads a .storyletsc bundle and deals from it directly, held to the same shared test suite as every other engine.

Built and verified against Unreal Engine 5.7 and 5.8, for editor and game targets. The plugin ships source-only, so your project needs a C++ toolchain even if you drive it from Blueprint.

Download the Unreal zip from the download page. It holds two folders side by side. StoryletEngine/ is the plugin, and StoryletEngineDemo/ is a ready-to-open sample project that finds the plugin in the sibling folder.

To try it first, open StoryletEngineDemo/StoryletEngineDemo.uproject where it sits and confirm the build prompt. There’s nothing to copy. To use it in your game, copy StoryletEngine/ into your project’s Plugins/ folder, restart the editor, and enable it. The engine core is header-only standard C++, so it compiles inside your project with no extra dependencies.

Drag a .storyletsc into the Content Browser. The plugin’s factory builds a UStoryletBundle asset holding the raw JSON, compiled when it loads. A broken bundle still imports, with the error readable on the asset as LoadError. A bundle of a schema this runtime doesn’t read lands the same way, with LoadError naming the schema. Right-click ▸ Reimport refreshes it from the source file.

For DLC or downloaded content, UStoryletBundle::LoadFromJsonString (Blueprint-callable) compiles a bundle from a string at runtime.

FStoryletEngineOptions Options;
Options.Seed = 7;
Options.bLog = true;
UStoryletEngine* Engine = UStoryletEngine::CreateWithOptions(Bundle, Options, {});
UStoryletFlow* Flow = Engine->OpenFlow(TEXT("main"));
Engine->RegisterForDebug(TEXT("main")); // optional: lets the state panel watch it

Create returns null, and logs why, when the bundle is uncompiled or is one the engine can’t read faithfully, such as a bundle that breaks the project map’s rules. That error starts bundle refused: and lists every problem, so check the result before opening a flow. Create(Bundle, {}) is the same engine with the default seed and no log. The last argument binds your game’s own state (below); {} binds none.

The engine owns the bundle, the shared state, and your game’s host scopes (@world, and any others the project declares). A flow is one playthrough across it, and all the dealing and playing happens on a flow, so a single-player game opens one, calls it what it likes, and never thinks about it again. The same seed always deals the same cards. bLog keeps the event logs so the state panel, or a Blueprint polling Log(), can read them. There are two. Flow->Log() is that flow’s own, and Engine->GetRunLog() is the run’s: every flow’s events in one order, each entry naming its Flow. The run log is the only place a story action in another flow moving shared state is visible. To hear each event as it happens instead, with the log on or off, bind the engine’s OnTrace: it fires with an FStoryletLogEntry for every deal, peek, eviction, play, write, turn, discard and diagnostic in every flow, naming its Flow, as Patterplay’s OnTrace does. The engine only traces while something is bound.

Open as many flows as you have parallel plays. OpenFlow / GetFlow / Flows / CloseFlow are all Blueprint-callable, and re-opening a name replaces that flow with a fresh one. What each flow gets its own copy of, and what they all share, is Your game’s state. This is the same shape as Patterplay’s UPatterEngine / UPatterFlow, so a project running both reads the same way.

const TArray<FStoryletHandContents> Dealt = Flow->DealAllHands(); // every hand
const TArray<FStoryletDealtCard> Inn = Flow->Deal(TEXT("the-inn")); // one hand
for (const FStoryletHandContents& Hand : Flow->Board()) // what's out right now
for (const FStoryletDealtCard& Card : Hand.Cards)
for (const FStoryletOutcomeView& Outcome : Flow->Outcomes(Card.GameId, Hand.Hand))
if (Outcome.bAvailable) { /* offer it */ }
TMap<FString, FString> Criteria; // look, don't deal
Criteria.Add(TEXT("area"), TEXT("forest"));
const TArray<FStoryletDealtCard> Looks = Flow->Peek(TEXT("village"), Criteria, 3);
FString Error;
if (!Flow->Play(CardGameId, OutcomeGameId, HandGameId, Error)) { /* Error says why */ }

Everything above is Blueprint-callable, with every view converted to a Blueprint struct (FStoryletDealtCard, FStoryletOutcomeView, FStoryletBoxView, FStoryletHandContents), so a designer can deal and play from a widget without C++. An FStoryletOutcomeView carries the outcome’s own Fields as FStoryletDealtCard carries the card’s, when the box declares outcome fields. BoardForBox(BoxRef) sits beside Board() and PlayAdvancing beside Play because Blueprint pins take no optional arguments. Play returns false and fills Error if the outcome is gated shut or the card isn’t in that hand. Nothing changes in that case. A card with no outcomes is played with an empty OutcomeGameId. A box on the project map can also name the map’s zone group in Peek criteria, beside its own tag groups.

A dealt card’s Fields hold only what the card sets. The bundle asset’s GetEffectiveCardFields(Box, Fields) (and GetEffectiveOutcomeFields for an outcome) fills in every field the box declares from its default. GetFieldDecl(Box, Field) gives a field’s declaration (its type, values, stages and default); hand a quality field’s to the Storylet stage functions StageIndex, CompareStages and NextStage to say where a stage stands or what comes after it.

Give the engine your @world values in a UStoryletWorld when you create it, under the scope’s token. The engine reads them through it before every deal, outcomes write back into it, and anything else you bind to the same object sees the same values:

UStoryletWorld* World = NewObject<UStoryletWorld>(this);
World->SetString(TEXT("time_of_day"), TEXT("night"));
World->SetReadOnly(TEXT("time_of_day"), true); // yours alone: a story write is refused
UStoryletEngine* Engine = UStoryletEngine::Create(Bundle, { { TEXT("world"), World } });
bool Known = World->GetBool(TEXT("knows_road")); // what the story has told you
World->OnChanged.AddDynamic(this, &AMyGame::OnWorldChanged); // (Name, Value, bFromStory)

The map takes any scope the project declares, by its token without the @: bind a second container as { TEXT("player"), Player } for @player, and so on. GetHostScope(TEXT("world")) hands back the container bound under a token. Tokens are case-sensitive: a token the bundle doesn’t declare binds nothing the story reads, and is reported through OnError with the kind setup, naming the declared spelling when only the case differs. Since OnError can only be bound once Create has returned, that report is logged as a Warning at once and reaches OnError when you open the first flow. This is Patterplay’s Create, parameter for parameter.

OnRefit fires with each saved value a refitting load put back to its default because it no longer fits its declaration (an enum value, a stage or a flag deleted since the save): its Scope, its Name, and the value the save held. On your own registry (CreateWithRegistry), load it with refit and the engine passes on its share as a flow opens and as a save loads. With nothing bound, each is logged as a Warning. A value the registry already held when you made the engine is claimed before OnRefit can be bound, so that one is only logged.

SetReadOnly is your policy. A story write to that name makes Play return false with @world.x is the game's alone. It is distinct from writable: false on the property’s declaration, which is the story’s own promise, checked when the project compiles and refused by every runtime. Your own Set* calls and a load are never refused by either. Your game keeps a bound world’s values, so the engine never saves them. Leave a scope out and the engine self-backs it from its declared defaults, written through the path accessors below (TEXT("player.hp")), and saves it with everything else.

The other properties cross the Blueprint boundary through typed accessors, path-addressed:

Flow->SetPropertyNumber(TEXT("story.gold"), 5);
double Gold = Flow->GetPropertyNumber(TEXT("story.gold"));
// Also GetPropertyBool / GetPropertyString / GetPropertyFlags and their setters.
// A zone of the project map has one address for every box using it: TEXT("value.docks.danger").
Flow->AdvanceTurns(TEXT("village"), 1);
double Turn = Flow->GetTurn(TEXT("village"));
TArray<FStoryletBoxView> Boxes = Flow->ListBoxes();

ListProperties() returns one row per declared property with its type, value, default, and enum options. The paths, and when to write them, are on Your game’s state.

Every property value lives in a registry, a storylets::ScopeRegistry, one per game. An engine you build with Create makes its own registry and acts as its own game, so a game with one engine never has to think about it. A game running more than one engine, Patter say, makes one registry, registers @world (and any other host scope) in it, and hands it to each engine. From C++:

#include "Storylets/Kernel.h" // storylets::ScopeRegistry: the shared kernel's
// Your @world declarations: a std::vector<storylets::ScopeDeclaration>.
auto Registry = std::make_shared<storylets::ScopeRegistry>();
storylets::OwnedScopeOptions Options;
Options.owner = std::string("Game");
Registry->defineOwned("world", WorldDeclarations, Options); // stored and saved with the rest
FStoryletEngineOptions EngineOptions;
EngineOptions.Seed = 7;
UStoryletEngine* Engine = UStoryletEngine::CreateWithRegistry(Bundle, Registry, {}, EngineOptions);

CreateWithRegistry is C++ only: the registry is a standard C++ object shared by pointer, and no Blueprint pin carries one. On the engine core, the same option is EngineOptions::registry.

storylets::ScopeRegistry is the shared expression kernel’s wildwinter::expr::ScopeRegistry, and Patterplay’s plugin carries the same kernel, byte for byte: in a game with both, storylets::ScopeRegistry and patter::ScopeRegistry are one type, so the same registry goes to UPatterEngine::CreateWithRegistry. Build both plugins from the same kernel: their headers are compiled into your game module, and if one is older, the module that includes both stops at a compile error that says so, so update the older plugin. The module that makes the registry sets bEnableExceptions = true in its Build.cs, since the registry refuses by throwing; one that only calls UStoryletEngine does not. The engine reports its refusals as it always has, as storylets::StoryletError (an expression’s as storylets::EvalError); a call you make on the registry yourself throws the kernel’s wildwinter::expr::RegistryError.

The engine registers @story under story, and every other bag that declares something under a key starting storylets/, which no expression can name. Given your registry, it registers nothing for @world or any other host scope: those are yours. defineOwned has the registry store and save one, and defineForeign("world", Resolver, &Declarations, Options) keeps it in your game, where nothing saves it. A UStoryletWorld you pass to CreateWithRegistry under a token is registered in your registry for you.

Every expression reads every scope in the registry, and GetPropertyNumber(TEXT("patter.gold")) and its setters reach another engine’s values from your code. A card can name Patter’s game-wide scope directly, with no setting in either project: gate on @patter.visits, or change @patter.gold in an outcome, which writes it through your registry under Patter’s rules. Only Patter’s shared values are visible this way. If a project names @patter and no Patter engine is on the Storylet Engine’s registry, it refuses the content before anything changes: OpenFlow returns null and UStoryletSave::DeserializeState returns false, each logging this content names @patter, which no engine on this registry registered: give every engine the game's one registry as an error. So build every engine on the game’s one registry before opening a flow or loading a save. If Patter’s engine goes away mid-game, an outcome writing @patter fails naming the scope.

A token is taken once: an engine that wants a token another already holds is refused as it is built, CreateWithRegistry returns null and logs who holds it, and the registry is left as it was. When a UStoryletEngine goes away, its values leave the registry with it. ApplyLiveBundle works on your registry as on the engine’s own: the new engine core carries the run across, a property the edit dropped leaves the registry, and nothing another engine keeps there is touched. If you drive the engine core directly rather than through UStoryletEngine, its hotSwap(Bundle) does the same and hands back the replacement engine and its load report. Don’t call it on GetCoreEngine(): the wrapper keeps the old core, which the swap leaves spent, so use ApplyLiveBundle there. The replacement keeps the options the engine was built with. To change one, pass a callback that edits a copy of them, hotSwap(Bundle, [](storylets::EngineOptions& O) { O.log = true; }), and everything it doesn’t touch stays as it was.

UStoryletSave::SerializeState(Engine) and DeserializeState(Engine, Json) are the .storyletsave string boundary, in the runtime module and Blueprint-callable (Patterplay’s UPatterSave, name for name). The file carries the engine’s envelope, storylets/save@3, with every live flow inside it, plus a bound UStoryletWorld’s values, and a load applies all of it, the world first, because the load checks every card it puts back in a hand against the world as it will be. A refused load leaves the world as it was. The envelope holds what isn’t a property: boards, clocks, cooldowns, random streams, play logs, and spent cards. An engine made with Create also carries its registry’s values in the envelope, a self-backed @world included, so a round trip preserves the whole run. The registry section is written in a fixed order, engine-wide values first and then each flow’s in flow order, so the same run always saves the same text. With a UStoryletWorld bound, the load restores its values as you would, so your read-only names are restored too (why a world you keep rides beside the envelope). A foreign or malformed blob returns false and leaves the engine untouched. Flow objects your game is already holding survive the load: they re-bind by name, so a Blueprint variable pointing at a flow keeps working. Files saved as storylets/save@1, before the registry held the values, still load: their values move into the registry as they do.

An engine on your registry leaves the property values out of its envelope. Your game saves the registry once, beside each engine’s file, and loads it before or after the engines, in either order:

#include "Storylets/Save.h"
const std::string RegistryText = storylets::saveRegistry(*Registry); // every property, once
const FString StoryletsText = UStoryletSave::SerializeState(Engine); // everything else
// Loading, into a freshly made registry and engine:
storylets::loadRegistry(*Registry, RegistryText);
UStoryletSave::DeserializeState(Engine, StoryletsText);
UStoryletFlow* Flow = Engine->GetFlow(TEXT("main"));

A value for a flow that hasn’t been restored yet waits in the registry until the flow claims it. A flow you open fresh with OpenFlow never picks up a value a load left for its name, and Reset() drops only the Storylet Engine’s waiting values, never another engine’s.

A load is forgiving. A card your edit deleted drops off the board, a property you added takes its default, and a save from an older build goes in without a word. UStoryletSave::PreviewLoad(Engine, Json, Report) says what that would cost before you spend it, and changes nothing. It fills an FStoryletLoadReport (bExact, Project, the Version / Hash pairs, Flows, Evicted, DroppedCooldowns, DroppedSpent, DroppedProperties, DefaultedProperties and RetypedProperties), and DeserializeStateWithReport(Engine, Json, Report) loads and hands back the same report for what the load did.

To park one playthrough rather than the whole run, SaveFlowToJson(Id) on the engine takes that flow’s state, its property values included, and OpenFlowRestoring(Id, Json, Report) puts it back. CloseFlow in between is what releases the cards it was holding and takes its values out of the registry, and PreviewFlowRestore(Id, Json, Report) says what coming back would cost.

What outlives a run has a pair of its own. SaveDurableToJson() on the engine takes the installation’s memory (the shared durable values and the durable one-shots that have been spent), and on a flow it takes that player’s pocket. In the next run’s fresh engine, LoadDurable(Json, Report) puts the memory back and OpenFlowWithDurable(Id, Json, Report) opens the player’s flow with their pocket in (OpenFlowWithDurableSeeded takes the flow’s own seed as well). Both fill an FStoryletLoadReport, naming whatever no longer fits the build (what carries and what the report lists). From C++, Engine::saveDurable(), Flow::saveDurable(), Engine::loadDurable() and the durable open option take a storylets::DurableSave, and storylets::serializeDurable / deserializeDurable in Storylets/Save.h turn one into text and back.

Tools ▸ Storylet Engine Runtime State opens the examiner. Register an engine with RegisterForDebug("label") (or FStoryletDebug::Register from C++) and the panel shows it live: the shared properties with type-aware editors behind a search filter and per-row reset-to-default and the run log (every flow’s events in one order), then each open flow with its own properties, per-box turns, board, and retained log, each log behind per-kind filters, Autoscroll, Copy, and Clear, and Save State… / Load State… buttons. It refreshes a few times a second, attaches and detaches across PIE on its own, and lives in the plugin’s editor module, so it never ships in a packaged game. The registry it reads compiles to no-ops in Shipping builds.

FStoryletLiveLink::Create(Bundle->GetBuildId(), TEXT("My Game")) then Link->Attach(Engine) joins the running game to Storyletter. The editor’s Board shows the game’s run, and a save in the editor pushes the new bundle into it, applied in place by ApplyLiveBundle, whether the engine made its own registry or shares yours with Patter. It compiles to no-ops in a Shipping build. The wiring, and what carries across, are on Live Link.

Select a UStoryletBundle and its Details panel shows what the bundle offers your code: hands, boxes, tags, declared properties, and the project map when the bundle has one (its zone group and zones, and which boxes use it). Nothing running needed. UStoryletBundle::DescribeBundle() is Blueprint-callable too: the map is bHasMap and Map on the description, and bUsesMap on each box. See the bundle inspector.

Open StoryletEngineDemo.uproject and press Play. The project’s game mode puts the Board demo on screen. It loads the Hamlet bundle from disk, deals every hand, and gives you a board you can play with the mouse, with a transcript of every action. Open the Runtime State panel beside it to watch the run live. The smallest part to read first is CreateBoardSession() plus OnDealAllHandsClicked() in UStoryletBoardDemoWidget, and the rest is UI.

The Hamlet on Unreal is the second demo, the same project with Patter performing each card’s dialogue, two engines in one game. It ships as a project zip on the download page; Source/HamletDemo/Private/HamletGame.cpp is the whole integration, and Running it with Patter explains the handoff.

storylets::StoryletEngineVersion (Blueprint: Get Storylet Engine Version) is this runtime’s version, as in its .uplugin. A game, a tool or an extension that ships apart from the Storylet Engine checks at start-up that the one it finds is one it was built for: storylets::versionInRange(storylets::StoryletEngineVersion, "1.0.0", "2.0.0") (Blueprint: Storylet Engine Version In Range, UStoryletVersion::StoryletEngineVersionInRange) is true from 1.0.0 up to, but not including, 2.0.0. It’s false when any of the three isn’t a version. Both are in Storylets/Version.h.

The plugin is two layers. Source/StoryletEngineRuntime/Public/Storylets/ is the engine core, header-only standard C++17 with no Unreal types in it, keeping the structure of the JavaScript reference runtime. Everything else is the Unreal wrapper: UStoryletBundle, UStoryletEngine, UStoryletFlow, UStoryletWorld, UStoryletSave, FStoryletLiveLink, FStoryletDebug, the Blueprint structs, the factory, the bundle’s Details panel, and the Runtime State panel. Exceptions from the core are caught at that boundary and surfaced as error strings and logs, so Blueprint never sees one.

Some things stay C++ only: SubscribeTrace (Blueprint binds OnTrace instead), a generic value on the flow and engine property calls (Blueprint uses the typed accessors above), the registry (CreateWithRegistry and GetRegistry), and the engine core itself (GetCoreEngine(), GetCoreFlow(), and the core’s listBags()). Numbers cross the boundary as double.

Open source under the MIT licence, made by .