Skip to content

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.

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).

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"])
return
var 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.

var engine := StoryletEngine.create(bundle, {"seed": 7, "log": true})
if engine == null:
return # create has already said why
var flow := engine.open_flow("main")
StoryletDebug.register(engine, "main") # optional: lets the state panel find it

create 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.

flow.deal_many() # refresh every hand
var board := flow.board() # hand gameId -> Array of card views
for 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.

flow.set_property("world.time_of_day", "night") # write before you deal
flow.get_property("story.reputation")
flow.get_property("value.docks.danger") # a zone's value: one for every box on the map
flow.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.

var envelope := engine.save_game()
var report := engine.load_game(envelope) # rebuilds every flow...
flow = engine.get_flow("main") # ...so re-take your handles

An 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 half
var 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.

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 saved
var 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.

GDScript has no exceptions, so the addon reports errors as values:

  • play() and set_property() return an error String, empty on success.
  • StoryletEngine.create returns null with a push_error for an option of the wrong shape, a scope token another engine already holds, or a bundle it can’t read.
  • load_game() and preview_load() return the load report, or an empty Dictionary with a push_error when they refuse.
  • Bad references and bad option Dictionaries push_error.
  • An unknown box on board(box_ref) is refused with push_error and 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.

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.

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.

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”.

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.

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.

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.

Open source under the MIT licence, made by .