Skip to content

Unity

The native C# runtime. No web view, no JavaScript, no IPC. It loads a .storyletsc bundle and deals from it directly, held to the same shared test suite as every other engine.

Needs Unity 6 (6000.x), and com.unity.nuget.newtonsoft-json (MIT), which the package declares as a dependency. Some C# is expected, because this is the game-developer side.

Download the Unity zip from the download page. It holds StoryletEngine/, the package (com.storylet-studio.storyletengine), and StoryletEngineDemo/, a ready-to-open demo project that finds the package in the folder beside it (see The demo project).

Install the package as a package, any of:

  • From disk, with Package Manager ▸ Install package from disk… and StoryletEngine/package.json.
  • Embedded, by copying StoryletEngine/ into your project’s Packages/ folder with your file browser.
  • By path, pointing your Packages/manifest.json at the folder ("com.storylet-studio.storyletengine": "file:../path/to/StoryletEngine").

Don’t drag the folder into the Unity Project window. Unity imports it into Assets/ as loose scripts, the package manifest is ignored, and the Newtonsoft dependency never installs.

Drop a .storyletsc into your project. A ScriptedImporter turns it into a StoryletBundleAsset, which holds the raw JSON and rebuilds the compiled bundle on load. A file that isn’t valid JSON still imports, with the error readable on the asset as LoadError, so a bad file is something you can look at, not something that breaks your project. A bundle this runtime can’t read (a schema it doesn’t know, or one that breaks the project map’s rules) is refused when you build the engine on it: new Engine throws a StoryletError naming every problem, before anything is registered.

using System.Collections.Generic;
using UnityEngine;
using StoryletStudio.StoryletEngine;
using Wildwinter.Expr;
public sealed class StoryRunner : MonoBehaviour
{
public StoryletBundleAsset Bundle; // assign the imported asset
private Engine _engine;
private Flow _flow;
void Start()
{
_engine = new Engine(Bundle.Bundle, new EngineOptions { Seed = 7, Log = true });
_flow = _engine.OpenFlow("main");
StoryletDebug.Register(_engine, "main"); // optional: lets the state window watch it
}
}

The engine is the world. Every play call lives on a flow (one playthrough), opened by name. A single-player game opens "main" and never thinks about it again. Several flows run parallel playthroughs over the same shared state (the sharing rules). Bundle.CreateEngine(seed) is the one-line form. The same seed always deals the same cards. Log = true keeps the event logs so the state window can show them. flow.Log() is that flow’s own, and engine.Log() is the run’s: every flow’s events in one order, each entry naming its Flow. Each log keeps the last 1000 entries, and LogCap sets your own.

foreach (var pair in _flow.DealMany()) // every hand; what was dealt, keyed by hand
{
string hand = pair.Key;
List<DealtCard> cards = pair.Value;
}
List<DealtCard> inn = _flow.Deal("the-inn"); // one hand
OrderedMap<string, List<DealtCard>> board = _flow.Board(); // what's out right now
OrderedMap<string, List<DealtCard>> barks = _flow.Board("barks");
var criteria = new OrderedMap<string, string>();
criteria.Set("area", "forest");
RankedList looks = _flow.Peek("village", criteria, 3); // look, don't deal
DealtCard card = inn[0]; // one the player picked
foreach (var o in _flow.Outcomes(card.Id, "the-inn")) // ask when you show them
if (o.Available) _flow.Play(card.Id, o.GameId, "the-inn");

A DealtCard carries Id, GameId, Title, Purpose, and the card’s fields; render it in your own UI. Fields holds only what the card sets. FieldHelpers.EffectiveFields( FieldHelpers.FieldDecls(bundle, "village"), card.Fields) fills in every declared default, and Wildwinter.Expr.Stages.Compare(decl, a, b) orders a quality field’s stages. An OutcomeView carries the same identity, Available, and the outcome’s own Fields when the box declares outcome fields. Play throws before changing anything if the outcome is gated shut or the card isn’t in that hand. A card with no outcomes is played with "" as the outcome.

_flow.SetProperty("world.time_of_day", ExprValue.Str("night")); // write before you deal
ExprValue gold = _flow.GetProperty("world.gold");
List<PropertyRow> rows = _flow.ListProperties();
_flow.AdvanceTurns("village", 1);
double turn = _flow.Turn("village");
List<BoxView> boxes = _flow.ListBoxes(); // id, gameId, title, turn

The paths, and when to write them, are on Your game’s state. ExprValue (the value type), OrderedMap and PropertyRow are in the Wildwinter.Expr namespace, with the registry and the rest of the shared expression kernel, so add using Wildwinter.Expr; (and using System.Collections.Generic;) beside using StoryletStudio.StoryletEngine;, as the first sample does.

@world is your game’s, and so is any other scope the project declares, such as @player. Bind each one through HostScopes, keyed by its token, to an IHostScope with Get, CanSet and Set, and conditions read your live game state directly:

_engine = new Engine(Bundle.Bundle, new EngineOptions
{
Seed = 7,
HostScopes = new Dictionary<string, IHostScope> { ["world"] = new MyWorld() },
OnError = e => Debug.LogWarning($"{e.Kind} {e.Node}: {e.Message}"),
});

Your game keeps those values, so the engine never saves them. Leave a scope out, and the engine backs it itself from its declared defaults, as a property it saves with the rest. Patter’s IHostScope has the same Get and Set, so one object can serve both engines.

A token is case-sensitive. Bind one the bundle doesn’t declare ("World" for world, say) and OnError hears about it as the constructor ends, as a PlayError with Kind "setup", naming the declared spelling when only the case differs. OnError also hears every condition the engine couldn’t evaluate and counted as false. Without one, each goes to Debug.LogWarning.

OnRefit hears what a refitting load put back. A game that loads its own registry with Load(saved, refit: true) has a saved value that no longer fits its declaration (an enum value, a stage or a flag deleted since the save) go back to its default, and the engine passes on its share as a List<LoadMisfit> (Scope, Name, and the Value the save held) as it claims them: as it’s built, as a flow opens, and after LoadGame. Without one, each goes to Debug.LogWarning.

Every property value lives in a registry, a ScopeRegistry, one per game. An engine you build on its own 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 in it, and hands it to each engine:

var registry = new ScopeRegistry()
.DefineOwned("world", Model.HostScopeDecls(Bundle.Bundle, "world"),
new OwnedScopeOptions { Owner = "Game" }); // stored and saved with the rest
_engine = new Engine(Bundle.Bundle, new EngineOptions { Seed = 7, Registry = registry });

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 scope the project declares: those are yours. DefineOwned has the registry store and save one; DefineForeign("world", resolver, declarations) keeps it in your game, and nothing saves it. Passing both Registry and HostScopes registers your resolvers in your registry for you.

Every expression reads every scope in the registry, so a card’s condition can read @patter.gold, and GetProperty("patter.gold") and SetProperty("patter.gold", value) reach another engine’s values from your code. A card can also change @patter.gold in an outcome, with no setting in your project: the write goes through the registry under Patter’s rules, so a property Patter declares read-only is refused. Give every engine the game’s one registry: if your content names @patter and no engine on the registry registered it, OpenFlow and LoadGame refuse it before anything changes, with the error this content names @patter, which no engine on this registry registered: give every engine the game's one registry. If Patter takes its scope away mid-game, an outcome that writes it throws, naming the scope. A token is taken once: building an engine that wants a token another already holds throws at once, naming the holder, and leaves the registry as it was.

The registry is one type to every engine because the expression kernel is shared: the Wildwinter.Expr namespace, in its own assembly. Patterplay carries the same kernel, and with both packages installed it compiles once, in Patterplay’s Patterplay.Expr; on its own, this package compiles its copy, StoryletEngine.Expr. So beside Patterplay, the Storylet Engine needs Patterplay 0.28.0 or newer, and stops the compile with an error saying so if it finds an older one. If your scripts have their own assembly definition, reference StoryletEngine.Expr and Patterplay.Expr beside StoryletEngine.Runtime: Unity ignores whichever is not installed. The engine’s own errors are still StoryletError and EvalError; a call you make straight to the registry throws the kernel’s RegistryError.

SaveEnvelope env = _engine.SaveGame();
LoadReport report = _engine.LoadGame(env); // rebuilds every flow...
_flow = _engine.GetFlow("main"); // ...so re-take your handles

The envelope is storylets/save@2. It holds what isn’t a property: boards, clocks, cooldowns, random streams, play logs, and spent cards. An engine built on its own also carries its registry’s values on env.Registry, its self-backed host scopes included, so those two lines are the whole run. A game that passed its own registry saves that once, beside each engine’s envelope, and env.Registry is null:

JObject registryJson = StoryletSave.SaveRegistry(registry); // every property, once
JObject storyletsJson = StoryletSave.ToJson(_engine.SaveGame()); // everything else
// Loading, into a freshly built registry and engine, in either order:
StoryletSave.LoadRegistry(registry, registryJson);
_engine.LoadGame(StoryletSave.FromJson(storyletsJson));
_flow = _engine.GetFlow("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. Envelopes saved as storylets/save@1, before the registry held the values, still load: their values move into the registry as they do.

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. PreviewLoad(env) says what that would cost before you spend it and changes nothing. LoadGame returns the same LoadReport once it has. report.Exact is true when the save goes back exactly as it was; otherwise Evicted, DroppedProperties, DefaultedProperties, RetypedProperties, and the Version / Hash pairs say what moved.

SaveFlow(id) takes one flow’s state, its property values included, for a playthrough stepping away, and OpenFlow(id, new OpenFlowOptions { Restore = saved }) puts it back. Closing the flow in between is what releases the cards it was holding, and takes its values out of the registry. On the way back, a shared card another flow now holds is dropped and reported (PreviewFlowRestore(id, saved) asks in advance).

What outlives a run, a durable value or a durable card’s spend, has a call of its own on each half. Take both as the run ends, and put them into the next run’s fresh engine:

DurableSave memory = _engine.SaveDurable(); // the installation's memory: the shared half
DurableSave pocket = _flow.SaveDurable(); // one player's pocket: their flow's half
var next = new Engine(Bundle.Bundle);
LoadReport memoryReport = next.LoadDurable(memory);
Flow alice = next.OpenFlow("alice", new OpenFlowOptions
{
Durable = pocket,
OnRestoreReport = r => Debug.Log(r.Exact ? "pocket in" : "the build moved on"),
});

Both reports say what no longer fits the build, as a load’s does. Durable can’t be given with Restore. StoryletSave.ToJson(pocket) and StoryletSave.DurableFromJson(json) carry a half as JSON, the same text every runtime writes.

For files, StoryletSave is the string boundary. SerializeState(engine, worldValues) gives you the .storyletsave text, and DeserializeState(engine, text, world: myWorld) reads one back, either envelope version (why the engine never saves a @world you bind). Your world implements IWorldContainer (Snapshot() and Load(values); StoryletSave.WorldOf(bag) wraps a kernel PropertyBag), and the saved values go into it before the engine loads, because the load checks every card it puts back in a hand against the world as it will be. A refused load leaves your world as it was. Without it, the call hands the values back, and you should apply them before loading. A foreign or malformed blob throws, so a bad file can’t corrupt a run.

Window ▸ Storylet Engine ▸ Runtime State (its tab reads Storylet State) lists every engine registered with StoryletDebug, with Save State… / Load State… (the whole run as a .storyletsave file) under its name, then a section per open flow. One registration covers every flow. The window reads them off the engine, so a flow you open later appears on its own.

Each flow’s section starts with Properties, one row per declared property, with type-aware editors (toggle, number, text, enum popup, flags) and a per-row Reset. Values refresh a few times a second, and the field you’re typing in keeps what you’ve typed. The per-box turn clocks and the current board come next. The log is that flow’s retained event log, with per-kind filters, Autoscroll, Copy, and Clear. The run log (every flow’s events in one order) sits under the engine’s name, above the flow sections.

A Filter properties field at the top narrows every flow’s rows by name or path, and a game that registered its StoryletLiveLink with StoryletDebug.RegisterLink gets a Live Link line above it showing the connection and the build.

It’s an editor window, so it never ships in a player build.

Select an imported bundle asset and its Inspector shows what the bundle offers your code: its identity, the hands, the tags by box, the declared properties, the project map when the bundle has one, and counts. Nothing running needed. See the bundle inspector.

StoryletLiveLink connects a running game to Storyletter. The editor’s Board shows your game’s run, and saving in the editor pushes the new bundle into the game without a restart. Wire it behind #if UNITY_EDITOR || DEVELOPMENT_BUILD, and a release build strips it. The wiring, and what the link carries, are on Live Link.

StoryletLiveBundle.Apply(engine, data) swaps the pushed bundle in through the engine’s own HotSwap, which you can call yourself for the load report:

var swap = _engine.HotSwap(newBundle); // the engine remembers the options it was built with
_engine = swap.Engine; // re-take every flow handle from the replacement
foreach (var p in swap.Report.DroppedProperties) Debug.Log($"dropped {p.Path}");

To build the replacement with a different option, pass a callback that changes a copy of the engine’s own options: _engine.HotSwap(newBundle, o => o.Log = true) turns the log on and keeps the seed, the HostScopes bindings, and everything else it leaves alone. Apply takes the same callback.

It works on your game’s registry too. The old engine hands its values to the replacement on that registry, the report says which properties the edit dropped, defaulted, or retyped, values still waiting for a flow keep waiting, and nothing belonging to Patter or your game is touched; the old engine is spent, its flows closed. A bundle for another project is refused before anything moves, and if the rebuild fails for any other reason, a bundle this runtime refuses included, the old engine and the registry are left exactly as they were.

Open StoryletEngineDemo/ from the zip and press Play. There’s nothing to install and no sample to import, because its Packages/manifest.json points at the package folder beside it. It runs the Board demo over the Hamlet bundle: every hand a labelled group, every dealt card a button, every outcome beneath its card, with a transcript of each deal, play, and turn. Open the Runtime State window beside it to watch the run live.

The smallest part to read first is Start(), StartSession() and DealAllHands() in Assets/Demo/BoardDemo.cs: load the bundle, build an engine, open a flow, deal, read Board(). Everything else in that file is UI.

The Hamlet on Unity 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; Assets/Hamlet/HamletGame.cs is the whole integration, and Running it with Patter explains the handoff.

The package is four assemblies over the shared expression kernel, so the boundaries are enforced by the compiler. StoryletEngine.Runtime is pure C#, with no UnityEngine and no JSON library (the engine, the flow, and everything under it). StoryletEngine.Runtime.Json is the Newtonsoft layer (BundleLoader, StoryletSave and StoryletLiveBundle). StoryletEngine.Runtime.Unity holds StoryletBundleAsset and StoryletDebug, and StoryletEngine.Editor holds the importer, the bundle inspector, and the state window. The kernel is StoryletEngine.Expr, or Patterplay’s Patterplay.Expr when that is installed. The C# keeps the structure of the JavaScript reference runtime, so the two stay in step.

StoryletEngineVersion.Current is the runtime’s version, as in its package manifest ("1.0.0"). A game, a tool or an extension that ships apart from the engine checks it at start-up with StoryletEngineVersion.InRange(StoryletEngineVersion.Current, "1.0.0", "2.0.0"): at least the first version and below the second, by semantic-version order. Every runtime has the same pair.

Open source under the MIT licence, made by .