Actions Reference

All built-in actions for scenes and choices.

Core Actions

property Examples

// String format (= set, += add, -= subtract)
{ property: "gold += 100" }              // add 100 to gold
{ property: "score = 0, lives -= 1" }    // set score to 0, subtract 1 from lives

// Object format (for setting complex values)
{ property: { settings: { volume: 80, theme: "dark" } } }

Dungeon Actions

asset property glide

Re-staging an asset that is already on screen glides it to the new values over tween seconds (default 0.5). Position, scale, rotation, opacity and the filters (blur, brightness, contrast, saturate, sepia, hue) glide; z and fit_mode snap. Staging an asset for the first time never glides — its enter transition owns how it appears.

{asset: "bg_mountain(scale = 2)"}              // grows over ~0.5s
{asset: "bg_mountain(scale = 2, tween = 3)"}   // slow approach
{asset: "bg_mountain(scale = 2, tween = 0)"}   // hard cut
{asset: "bg_mountain(x = 20, alpha = 0.4)"}    // drifts and fades together
{asset: "bg_mountain(sepia = 1, saturate = 0.5)"} // washes into a memory

Spine assets are positioned by their viewport through the Spine renderer rather than by these props, so they are unaffected.

Scene Params

intro

Add {intro: true} to the first paragraph of a scene. On the first visit, column 1 plays normally. On any subsequent visit, the engine skips column 1 and plays column 2 instead.

Example (DryadScript):

#npc~talk{intro: true}
1
%
The old man looks up from his desk.

old_man: Ah, a visitor. I am Gareth, the keeper of this archive.

old_man: What brings you here?
%
Gareth nods as you approach.

old_man: Back again? What do you need?

Column 1 (before %) plays on first visit. Column 2 (after %) plays on every subsequent visit. Both share the same choices below.

Note: Column 2 must exist. If missing, the engine logs an error.

Encounter Params

Params on an @ encounter line. These are not actions — they configure the encounter itself.

discover

statId#number — "this stat, at least this high". Checked against every party member, so the sharpest eyes in the group find it. Comma-separate for several stats ("perception#6, wits#4"); each has to be met by someone.

@bats{discover: "perception#6", if: "_defeated(bats) = false"}
!listen
!attack{battle: "bats"}
Something shifts in the dark above you.

Discovery is permanent. The first time the party clears the threshold the engine writes the encounter into the save. Drop the stat afterwards — swap the gear, bench the character, lose the buff — and it stays found.

if keeps working alongside it. discover decides whether you have found the encounter; if decides whether it is there right now, and it keeps evaluating. Above, the bats are revealed forever once you are perceptive enough, yet still vanish once killed.

Checked on room entry and on scene exit — the two moments a stat can have changed. A buff gained while standing in a room reveals nothing until you step out and back in. Anything else that moves a stat in place can force a re-check with game.scanDiscoverableEncounters() (the turn_system plugin does this whenever the clock advances, so waiting works too).

The engine renders a cue on an encounter found this way (Perception[6] check success), and fires the Game Emitters encounter_discovered emitter.

Choice Params

Params on a choice (!, ~ or >). These are not actions — they configure the choice itself.

wip

An authoring marker for a branch that isn't written yet. The choice renders greyed out and unclickable — the same unavailable styling as a failed active condition — with [wip] prefixed to its label, so planned options stay visible in-game without being reachable.

@crossroads
!north<Head north>{scene: "north_road"}
!south<Head south>{wip: true}
Two roads lead away from the crossroads.

The player sees [wip] Head south, greyed out.

Unconditional — unlike active, there is no condition to satisfy and no way to enable it. It also takes no action handler, so the choice can never fire. Placeholders in the label still resolve normally (|my|, if{} logic, text styles).

Note: a row whose choices are all wip leaves the player with nothing to pick. Keep at least one live choice, or an exit, in every row.

enc_sensitive

Marks a travel/exit choice as encumbrance-sensitive: it greys out and becomes unclickable while the party inventory is over capacity (too heavy or too many slots). Authored as !leave{enc_sensitive: true}. A proactive affordance only — the engine also blocks all free room-to-room movement while over-capacity (map clicks, pathfinding, and {enter} actions when no scene is active), so a choice without this flag is still stopped, just without the grey-out. No-op unless the game caps the party inventory's max_weight / max_size. Drop items (the auto Drop item action) to recover.

clue

Marks a choice as a hint the player hasn't followed yet. It renders highlighted, and stops standing out the moment it is picked — permanently, since taken choices are remembered in the save.

@chest
!force<Force it open>{clue: true, loot: "chest1"}
!leave<Leave it be>
A heavy chest, its lock crusted shut.

In map and screen dungeons the encounter itself also glows on the map for as long as it still holds an untaken, visible clue choice — so the player can see there is something here they haven't done, without having to click through everything.

A greyed-out choice never glows: active wins over clue, so a hint you cannot act on yet stays quiet.

Character Actions

create_character and reset_character take the same shapes — a string, a comma-separated list of ids, an object, or an array of either. They differ only on an id that is already live: create_character logs an error and skips it, reset_character rebuilds it.

{ create_character: "villager" }                  // id doubles as the template id
{ reset_character: "orc, goblin" }                // `,` separates ids
{ create_character: [
    { id: "slime_2", template: "slime_small" },
    { id: "slime_3", template: "slime_small" }
]}
{ reset_character: { id: "orc", template: "orc_veteran", party: false } }

Without a template, reset_character falls back to the live character's own templateId, then to the id — so { reset_character: "orc_boss_2" } rebuilds from orc when that is the template it was built from.

create_character also accepts the template body inline — any object without a template key is used as the template itself:

{ create_character: { id: "custom_npc", traits: { name: "Stranger" }, stats: { health: 20 } } }

skill flashes

Party-only, the same rule status keeps. A first learn flashes "Fireball has been learned!"; a level gain flashes "Fireball has been upgraded to level 2!"; a slot already at max_upgrade_level flashes nothing. skill takes dot paths, never the -> syntax below.

Targeted-spec syntax (status, skin, item_slot, ability)

Each action takes a string of the form targetId->item & item & ..., targetId->!item, ...:

• Comma separates per-target groups.
• Within a group, & separates items.
• Items prefixed with ! are removed; bare items are added.

{ status: "alice->blessed & focused, bob->!cursed" }
{ skin: "mc->armor_dirty, mc->!armor_clean" }
{ item_slot: "alice->extra_ring, bob->!ring_3" }

status posts a flash notification ("Alice has gained Blessed!") only when the target is in the party. Statuses set on NPCs, enemies, or a character staged before recruitment apply silently. skin, item_slot, and ability never flash.

Item Actions

equip

Equip and unequip items using real character ids and item template ids (no uids). Comma separates specs; two spec shapes:

• Targeted (char -> payload & payload): & separates payloads; a payload is itemId to equip or !itemId to unequip. char.slot_type targets a specific slot type (an equip fills its first empty slot, else the first; an !itemId is restricted to that type).
• Clear (!char / !char.slot_type, no arrow): !char.slot_type unequips every occupied slot of that type; !char clears all of the character's equipment.

slot_type is the slot's id from Item Slots (e.g. outfit_ordelia), not a per-character instance name. On equip, if no matching instance exists in the character's inventory one is created from the template and the item.added flash shows (same as add_item); equipping an instance already in inventory stays silent. Invalid ids/slots log a console warning and skip that spec — the scene continues.

{ equip: "ordelia -> armor1 & ring1" }        // equip both (auto slot)
{ equip: "ordelia.trinket_ordelia -> ring1" } // equip into a slot type
{ equip: "ordelia -> !armor1" }               // unequip by item id
{ equip: "!ordelia.outfit_ordelia" }          // clear a slot type
{ equip: "!ordelia" }                         // clear all equipment

equip vs equip_item/unequip_item: prefer equip for scripting — it uses stable ids. equip_item/unequip_item act on the active item (its uid) and are mostly internal UI plumbing; { equip_item: true } / { unequip_item: true } stay useful inside active-item flows (e.g. the tutorial's equip/unequip cancel handling).