Godot
The pure GDScript runtime. No native extension to compile, no web view. It loads a
.storyletsc bundle and deals from it directly, held to the same shared test suite as every other engine.
Needs Godot 4.7 or newer. Every release is tested against Godot 4.7, and the runtime uses only plain GDScript, so it also runs headless.
Install
Section titled “Install”Download the Godot zip from the download page, drop the storyletengine/
folder into your project’s addons/ directory, and enable the plugin in Project ▸ Project
Settings ▸ Plugins.
The runtime works with or without the plugin enabled. Enabling it registers the .storyletsc
importer (so bundles become assets you can load()), the bundle inspector, and the export
hook that keeps your bundle in an exported build (see Exporting your game).
Load a bundle
Section titled “Load a bundle”Either read the file yourself:
var text := FileAccess.get_file_as_string("res://story.storyletsc")var loaded := StoryletBundle.load_from_string(text)if not loaded["ok"]: push_error(loaded["error"]) returnvar bundle = loaded["bundle"]load_from_string reads storylets/bundle@2 and the earlier storylets/bundle@1 and
storylets/bundle@0, and refuses any other schema by name.
Or, with the plugin enabled, load("res://story.storyletsc") gives you a
StoryletBundleResource carrying json_text and get_bundle(). A broken bundle still
imports, so check is_valid() (and get_errors() for why) before you use it.
Build an engine, open a flow
Section titled “Build an engine, open a flow”var engine := StoryletEngine.create(bundle, {"seed": 7, "log": true})if engine == null: return # create has already said whyvar flow := engine.open_flow("main")StoryletDebug.register(engine, "main") # optional: lets the state panel find itcreate returns null, with a push_error, for a bundle it can’t read faithfully. An unknown
schema is named as unsupported bundle schema, and a project map whose rules the bundle breaks
gives an error starting bundle refused: that names every problem it found. Check for null
before you open a flow.
Keep the engine. Hold it in a variable or a member for as long as you play, as the
example does. A flow holds its engine weakly, because GDScript’s reference counting can’t free
a cycle and an engine and its flows would otherwise keep each other alive for good. So a flow
on its own doesn’t keep its engine: StoryletEngine.create(bundle).open_flow("main"), with
the engine kept nowhere, gives a flow that is already closed, and every call on it refuses with
push_error, saying its engine was freed. You need the engine anyway, to save the game and to
open other flows.
The same reference counting applies to the callables you hand the engine. A trace handler on
a flow can read that flow freely, since a closed flow lets go of its handlers. But a host scope
resolver or an engine-level handler that reads a member of the object holding the engine
captures that object, and the two then keep each other alive. Have the callable capture the
values it needs instead, as the Hamlet demo’s resolver captures its world Dictionary rather
than the game.
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).
The same seed always deals the same cards. "log": true keeps the event logs. flow.log()
is that flow’s own, and engine.log() is the run’s, every flow’s events in one order with
each entry naming its flow. That last one is the only place a story action in another flow
moving shared state is visible, and the state panel shows both (capped at 1000;
"log": {"cap": n} sets your own).
@world is your game’s, and so is any other scope the project declares, such as @player. Bind
each one through "host_scopes", keyed by its token, to a {"get", "set"} resolver, and
conditions read your live game state directly:
var world := {"time_of_day": "day"}var engine := StoryletEngine.create(bundle, { "host_scopes": {"world": { "get": func(n: String): return world.get(n), "set": func(n: String, v) -> void: world[n] = v, }}, "on_error": func(e: Dictionary) -> void: push_warning("%s %s: %s" % [e["kind"], e["node"], e["message"]]),})Your game keeps those values, so the engine never saves them, and a resolver with no "set" is
one the story can’t write. Leave a scope out, and the engine backs it itself from its declared
defaults, as a property it saves with the rest. Patterplay takes the same "host_scopes", so one
resolver can serve both engines.
A token is case-sensitive. Bind one the bundle doesn’t declare ("World" for world, say) and
"on_error" hears about it as the engine is built, as {"kind": "setup", "node", "message"},
naming the declared spelling when only the case differs. So does a key the options Dictionary
doesn’t take, a typo or the old "world" option, which is ignored rather than refused.
"on_error" also hears every condition the engine couldn’t evaluate and counted as false.
Without one, each goes to push_warning.
"on_refit" hears what a refitting load put back. A game that loads its own registry with
registry.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 an Array of {"scope", "name", "value"}, with what the save held, as it
claims them: as it’s built, as a flow opens, and after load_game. Without one, each goes to
push_warning.
Deal, peek, outcomes, play
Section titled “Deal, peek, outcomes, play”flow.deal_many() # refresh every handvar board := flow.board() # hand gameId -> Array of card viewsfor hand in board: for card in board[hand]: print("%s holds %s" % [hand, card["gameId"]])
var looks := flow.peek("village", {"area": "forest"}, 3) # look, don't deal: looks["cards"]
var hand_id: String = board.keys()[0]var card_id: String = board[hand_id][0]["gameId"]for outcome in flow.outcomes(card_id, hand_id): # ask when you show them if outcome["available"]: var err := flow.play(card_id, outcome["gameId"], hand_id)Card views and outcome views are Dictionaries. A card carries id and gameId, plus title,
purpose, and fields when the card has them. fields holds only what the card sets;
StoryletEngine.effective_fields(StoryletEngine.field_decls(bundle, "village"), card["fields"])
fills in every declared default, and StoryletExpression.compare_stages(decl, a, b) orders a
quality field’s stages. An outcome carries id, gameId, and
available, plus title and purpose when it has them, and fields when the box declares
outcome fields. play() returns an error String, empty on
success, and changes nothing 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.
Your game’s state
Section titled “Your game’s state”flow.set_property("world.time_of_day", "night") # write before you dealflow.get_property("story.reputation")flow.get_property("value.docks.danger") # a zone's value: one for every box on the mapflow.list_properties() # every declared property
flow.advance_turns("village", 1.0)var turn := flow.turn("village")var boxes := flow.list_boxes()Your game’s state has the paths, and when to write them.
Save and load
Section titled “Save and load”var envelope := engine.save_game()var report := engine.load_game(envelope) # rebuilds every flow...flow = engine.get_flow("main") # ...so re-take your handlesAn engine built on its own carries every property value in its envelope, its self-backed host
scopes included, so those two calls are the whole run. The envelope is storylets/save@3,
written in the same order every time, so the same run always saves the same bytes, and an
older storylets/save@2 or @1 envelope or file still loads. A game that
hands the engine its own registry saves that registry once, beside the envelope
(below).
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. preview_load(envelope)
says what that would cost before you spend it and changes nothing. load_game returns the
same report Dictionary once it has, with "exact" true when the save goes back exactly as it
was and "evicted", "droppedProperties", "defaultedProperties", "retypedProperties", and
the "version" / "hash" pairs naming what moved. A save for another project, or in a save
schema this runtime doesn’t read, is refused, with an empty Dictionary and a push_error.
save_flow(id) takes one flow’s state, for a playthrough stepping away, and
open_flow(id, {"restore": saved}) puts it back. Closing the flow in between is what releases
the cards it was holding. On the way back, a shared card another flow now holds is dropped and
reported (preview_flow_restore(id, saved) asks in advance, and
{"on_restore_report": Callable} hands you what the restore actually did).
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:
var memory := engine.save_durable() # the installation's memory: the shared halfvar pocket := flow.save_durable() # one player's pocket: their flow's half
var next := StoryletEngine.create(bundle)var memory_report := next.load_durable(memory)var alice := next.open_flow("alice", {"durable": pocket, "on_restore_report": func(r: Dictionary) -> void: print("pocket in" if r["exact"] else "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", and a half from another project is refused with a push_error. Each half is a
plain Dictionary: StoryletSave.to_json(pocket) writes it as the same text every runtime
writes, and JSON.parse_string reads it back.
StoryletSave.serialize_state(engine, world_values) and
StoryletSave.deserialize_state(engine, text, {"world": world}) are the .storyletsave
string boundary. They matter when your game binds @world through "host_scopes": those
values are your game’s, and the engine never saves them
(why). Pass your world (a Dictionary, which is updated in
place, or an object with values() and load(values)) 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 the option, the call hands the
values back for you to apply, and you should apply them before loading. Like load_game, it rebuilds every
flow, so take your handles again from engine.get_flow(). A foreign, malformed, or
wrong-project blob is refused with a push_error and null, so a bad file can’t corrupt a run.
One registry for the game
Section titled “One registry for the game”Every property value lives in a registry, a StoryletScopeRegistry. Without the "registry"
option the engine makes its own and acts as its own game, which is all a game with one engine
needs. A game running Patterplay beside the Storylet Engine makes one registry, registers
@world in it, and hands it to both:
var registry := StoryletScopeRegistry.new()registry.define_owned("world", StoryletBundle.host_scope_decls(bundle, "world"), {"owner": "Game"}) # stored and savedvar engine := StoryletEngine.create(bundle, {"seed": 7, "registry": registry})The engine registers @story under story and every other bag under a key starting
storylets/, each carrying the owner label “Storylet Engine”. Either addon’s registry class
will do, since both wrap the same shared source. Every scope in the registry reaches your
cards’ conditions, and get_property("patter.gold") or set_property("patter.gold", 5) reads
or writes another engine’s value by its path.
Given your registry, the engine leaves every property value out of save_game(), and your
game saves the registry once:
var save := {"registry": registry.save(), "storylets": engine.save_game()}# ...and later, in either order:registry.load(save["registry"])engine.load_game(save["storylets"])@world is then your game’s to register, and so is any other scope the project declares.
define_owned keeps one in the registry, saved with the rest;
define_foreign("world", {"get": getter, "set": setter}, StoryletBundle.host_scope_decls(bundle, "world")) leaves it in your
game’s own state, and nothing saves it but you. Pass the engine "host_scopes" instead and it registers each
foreign scope for you. A token is taken once: a second
engine that wants a token another already holds is refused, create returns null, the error
names the holder, and the registry is left as it was.
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 the registry
under Patter’s rules. The bundle records the tokens it names in externalScopes
(StoryletBundle.external_scopes(bundle) reads it). That content runs only where Patter is on
the same registry. If it is not, open_flow and load_game refuse before anything changes: each
push_errors this content names @patter, which no engine on this registry registered: give every engine the game's one registry, then open_flow returns null and load_game returns an
empty Dictionary. If Patter takes its scope away mid-game, an outcome writing it fails with an
error String naming the scope.
engine.hot_swap(edited_bundle) rebuilds the engine on an edited bundle with the run carried
over, and works on your registry too. It returns {"ok": true, "engine", "report"}: the
replacement, on the same registry, and the load report, which names the properties the edit
dropped or defaulted. The old engine hands its own values over and is spent, its flows closed,
so re-take every handle from the new one; nothing belonging to Patter or your game is touched.
A bundle for another project, or one the engine can’t read, comes back as
{"ok": false, "error"} with a push_error before anything moves, and a rebuild that fails
part way puts the old engine and the registry back exactly as they were.
Errors
Section titled “Errors”GDScript has no exceptions, so the addon reports errors as values:
play()andset_property()return an error String, empty on success.StoryletEngine.createreturns null with apush_errorfor an option of the wrong shape, a scope token another engine already holds, or a bundle it can’t read.load_game()andpreview_load()return the load report, or an empty Dictionary with apush_errorwhen they refuse.- Bad references and bad option Dictionaries
push_error. - An unknown box on
board(box_ref)is refused withpush_errorand an empty Dictionary. - An evaluation error inside a deal or peek makes that card or deck unavailable and puts a diagnostic in the trace, exactly as the reference runtime does. Never a silent pass, never a crash.
The other small differences from the other runtimes are listed on Compatibility.
The state panel
Section titled “The state panel”Add a StoryletStatePanel to your scene. It’s an in-game overlay, debug_only by default, so
it builds nothing in a release export and is safe to leave in a scene that ships. With an
engine registered through StoryletDebug, it saves and loads .storyletsave files with
Save State… / Load State… and shows the run log (every flow’s events in one order),
then a section per open flow, with that flow’s declared properties (with a filter, editable),
its per-box turns, its board, and its own retained log, each log behind per-kind filters with
Autoscroll, Copy, and Clear. It reads the flows off the engine, so one
registration covers every flow, however many you open later.
To watch one engine without the registry, set the panel’s engine property instead. Register a
Live Link with StoryletDebug.register_link(link) and the panel shows whether it is connected,
and to which build.
To watch the game from Storyletter instead, and to have saves reach the run without a
restart, add a StoryletLiveLink node and attach your engine (the link finds your flows
itself). It opens only in a debug
build. A pushed bundle goes in through StoryletLiveLink.apply_live_bundle(engine, data),
which does what hot_swap does but hands a refusal back instead of raising a push_error, so
a refresh works whether the engine made its own registry or shares yours with Patterplay. Live Link has the wiring and the protocol.
The bundle inspector
Section titled “The bundle inspector”Select an imported bundle in the FileSystem dock and the Inspector shows what the bundle offers your code: hands, boxes, tags, declared properties, and the project map when there is one. Nothing running needed. See the bundle inspector.
Exporting your game
Section titled “Exporting your game”With the plugin enabled there’s nothing to configure, because the addon’s export hook puts the raw
.storyletsc into the exported build at its original path, so
FileAccess.get_file_as_string("res://story.storyletsc") reads the same bytes in the editor
and in the export, on every platform. load("res://story.storyletsc") works in the export too, and
so does a scene that holds the bundle as a resource: the bundle still ships only once.
If you run with the plugin disabled, Godot treats a .storyletsc as a non-resource file and
leaves it out of the export. In that case add *.storyletsc to your export preset’s
Resources ▸ “Filters to export non-resource files/folders”.
Using C#
Section titled “Using C#”A game written in C# with Godot’s .NET build uses this same addon. Godot runs GDScript and C# side by side, so your C# scripts call the Storylet Engine directly. There’s nothing extra to install, and the editor half (the importer, the bundle inspector, and the export hook) works as it does for a GDScript game.
C# can’t name a GDScript class_name, so load each class you need by its script path. The calls are
the GDScript ones by name, and what comes back are Godot types: a board is a Godot.Collections.Dictionary
of hands, each an array of card Dictionaries.
using Godot;using Godot.Collections;
public partial class Storylets : Node{ static readonly GDScript StoryletBundle = GD.Load<GDScript>("res://addons/storyletengine/runtime/bundle.gd"); static readonly GDScript StoryletEngine = GD.Load<GDScript>("res://addons/storyletengine/runtime/engine.gd");
GodotObject _engine; // keep it: a flow holds its engine weakly GodotObject _flow;
public override void _Ready() { var loaded = StoryletBundle.Call("load_from_string", FileAccess.GetFileAsString("res://story.storyletsc")).AsGodotDictionary(); if (!loaded["ok"].AsBool()) { GD.PushError(loaded["error"]); return; }
_engine = StoryletEngine.Call("create", loaded["bundle"], new Dictionary { ["seed"] = 7 }).AsGodotObject(); if (_engine == null) return; // create has already said why _flow = _engine.Call("open_flow", "main").AsGodotObject();
_flow.Call("deal_many"); var board = _flow.Call("board").AsGodotDictionary(); foreach (var (hand, cards) in board) foreach (Dictionary card in cards.AsGodotArray()) GD.Print($"{hand} holds {card["gameId"]}"); }
public void Play(string handId, string cardId) { foreach (Dictionary outcome in _flow.Call("outcomes", cardId, handId).AsGodotArray()) { if (!outcome["available"].AsBool()) continue; var error = _flow.Call("play", cardId, outcome["gameId"], handId).AsString(); // "" on success if (error != "") GD.PushWarning(error); return; } }}Everything on this page works the same way: save_game() and load_game() hand back Dictionaries
(re-take the flow with get_flow after a load), option keys are the GDScript ones, and errors are
values and push_errors, never C# exceptions.
Your game’s own C# state goes behind host_scopes as a get / set pair of C# lambdas, so your
cards’ conditions read your C# objects directly and outcomes write to them:
var world = new System.Collections.Generic.Dictionary<string, Variant> { ["time_of_day"] = "day" };_engine = StoryletEngine.Call("create", loaded["bundle"], new Dictionary{ ["host_scopes"] = new Dictionary { ["world"] = new Dictionary { ["get"] = Callable.From((string name) => world.TryGetValue(name, out var v) ? v : default), ["set"] = Callable.From((string name, Variant value) => { world[name] = value; }), }, }, ["on_error"] = Callable.From((Dictionary e) => GD.PushWarning($"{e["kind"]}: {e["message"]}")),}).AsGodotObject();Returning default (a nil Variant) means unset. As in GDScript, have the lambdas capture the store
they need, not the object that holds the engine.
Names are strings and values are Variants, so a typo shows up when the game runs, not when it
compiles. If you call the engine from many places, wrap the calls you use in a small typed class of
your own.
Godot’s C# builds don’t export to the web yet, so a game that has to run in a browser needs GDScript.
Which Storylet Engine is this?
Section titled “Which Storylet Engine is this?”StoryletEngineVersion.CURRENT is this runtime’s version, as in its plugin.cfg ("1.0.0"). A game, a tool
or an extension that ships apart from the engine checks it at start-up with
StoryletEngineVersion.in_range(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.
The demo
Section titled “The demo”addons/storyletengine/demo/board_demo.tscn is the Board demo, the Hamlet bundle dealt
onto a board you can play, with the same hands, control labels, and transcript as the other
three runtimes. Open the scene and press Run Current Scene (F6). The smallest part to read first in
board_demo.gd is building the engine, opening a flow, dealing, and reading board(). The
rest is UI. Delete
the folder freely, since nothing depends on it.
The Hamlet on Godot 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; hamlet_game.gd is the whole
integration, and Running it with Patter explains the handoff.
- Dev tools covers what every runtime shares.
- Compatibility & conformance explains why it matches the other engines exactly.
Open source under the MIT licence, made by Ian Thomas.