Scripting
Everything a game says and every scene it plays is an event script: dialogue, gifts, trainers who see you, doors that unlock, cutscenes, the intro and the ending. This page introduces scripts. The language guide is Scripting and every command is listed in the script language reference.
Overview
Section titled “Overview”A script is text in a .pfs file. ploom build compiles it into a small module of
bytecode, and the game runs that module. The game never reads the text.
Why compile? The DS has 4 MB of memory and a slow processor. A parser for a text language would cost memory and time on every map load. A bytecode runner is a few KB of code, and the compiler can check every name, argument and limit on your machine, before the game runs. One run of the compiler reports every mistake it finds, each with its file, line and column.
The files of a project:
| File | Holds |
|---|---|
scripts/common.pfs |
Scripts any map can call, and the shared hooks (on use, on fieldmove, on option…) |
scripts/shared/*.pfs |
More of the shared module, in the order of their names |
scripts/<map>.pfs |
The scripts of one map, named after its folder (or the file its map.toml names with script) |
scripts/*.pfsym |
Names for numbers: flags, variables, items, species, sounds |
Names of maps, actors, signs and triggers come from the maps you draw in Tiled. Names of
flags, variables, items and the rest are declared in .pfsym files, so a script never
holds a bare number. From the sample’s sample.pfsym:
var STORY = 0flag HAS_HAIRPIN = 1flag ROOM_UNLOCKED = 2lvar TRIES = 0 # forgotten whenever the map is leftitem HAIRPIN = 17sound CREAK = 13Triggers
Section titled “Triggers”A script runs because something happened. You write on and the event:
| Event | Runs when |
|---|---|
on load |
The map has loaded, before it is drawn. Put the map in its saved state here |
on enter |
The player has arrived and the screen has faded in |
on talk <actor> |
The player talks to someone |
on read <spot> |
The player examines a sign or a spot |
on step <spot>, on step area(x, y, w, h) |
The player steps on a trigger or a rectangle of cells |
on sight <actor>, range |
Someone sees the player straight ahead |
on resume |
Play comes back to the map from a menu, a screen or a battle |
on idle when <cond> |
Nothing else has the field and the condition holds |
on steps n |
Every n steps of the whole game |
The shared file has hooks of its own: on use ITEM (an item used from the bag),
on fieldmove KIND, on follower, on option NAME, on newgame (the intro),
on gameover (the end of a challenge run). on headbutt (a tree faced) runs the map’s
own first, else the shared one. The full table, with each hook’s number, is in the
reference.
Any event may have a condition: on enter when STORY == 0. Among several that fit,
the first in the file whose condition holds runs. That is how one map plays a different
scene on each visit.
First NPC
Section titled “First NPC”The sample’s parlour is a map made by hand. Its whole script file:
on talk neighbour { lock faceplayer say "You're the one from next door.\pThe garden's through the back, if\nyou want air." release}neighbour is the name the actor has in Tiled. lock holds the player and everyone’s
own movement while the scene plays; release lets go. \n continues on the next line
of the box and \p starts a new paragraph (see Text and dialogue).
Flags and variables
Section titled “Flags and variables”A story is state. Flags are yes or no; variables hold a number.
| Kind | Range | Lasts |
|---|---|---|
flag(n) |
0 to 4095 | Saved with the game |
var(n) |
0 to 511 | Saved with the game |
lflag(n), lvar(n) |
0 to 63, 0 to 31 | Until the map is left |
temp(n) |
0 to 15 | The running script only |
A change that must last is a flag and an on load. The sample’s home keeps its door
open once it has been picked:
on load when ROOM_UNLOCKED { setcell DOOR_X, DOOR_Y, walk door DOOR_X, DOOR_Y, open}on load runs every time the map loads, so the door is open on every later visit and
after a saved game is continued. The scene that opened it ran once.
The sample’s weir keeper gives three creatures and two items on the first visit, and never again:
on enter when !WEIR_GIFTS { lock say "Old keeper: You came over the hill?\nThe pool's behind my hedge." givemon RIPPLET, 26 giveitem BICYCLE set WEIR_GIFTS release}An item lying on the ground is not a kind of its own. It is an actor with a hide rule and a talk script; a hidden item is a spot with a read script. The sample’s field station has one of each:
hide floor_salve when GOT_STATION_SALVE
on talk floor_salve { temp(0) = SALVE temp(1) = 1 call ground_item if temp(7) { set GOT_STATION_SALVE }}ground_item is a script of the shared file. A script called without brackets shares
its caller’s temporaries, which is how temp(0) and temp(1) reach it.
Cutscenes
Section titled “Cutscenes”Movement lists move actors; a stand-in actor, marker, moves the camera. The sample’s
first step into the hall looks down the corridor and back:
on step area(9, 9, 3, 1) when STORY == 1 { lock place marker, xof(player), yof(player) camera marker move marker, [speed(fast), down * 6, pause(40)] emote keeper, dots move marker, [speed(fastest), up * 6] camera player say "Asleep in the chair. The front door is past it." STORY = 2 release}move waits until the list ends unless it ends in wait: false; several lists given
with wait: false run together, and waitmoves waits for all of them. For the field
camera’s own commands see Cameras.
Automatic scenes
Section titled “Automatic scenes”on enter when is looked at once, on arriving. A scene that must start when something
changes during a visit is an on idle when. It runs as soon as nothing else has the
field, and it must make its own condition false or it runs again at once. The weir
counts the player’s returns from a screen or a battle, and speaks after the first:
on resume when WEIR_GIFTS { WEIR_RETURNS += 1 }
on idle when WEIR_RETURNS == 1 { lock WEIR_RETURNS = 2 say "Old keeper: That's the way.\nLet them do the work." release}These two hooks stand in for the original games’ per-frame script tables (decision 240).
Background scripts
Section titled “Background scripts”start name runs a script beside everything else: a guard’s rounds, a flickering lamp.
Up to four scripts run at once, counting the one in the foreground. A background script
does not stop the player and ends when the map is left. The sample’s town:
script crossing_rounds { while STORY < 5 { move crossing_watch, [face_left, pause(120), face_down, pause(90)] }}
on load { start crossing_rounds}A loop that never waits cannot hang the game: a script is made to pause after 2,000 instructions in a tick.
Language 2
Section titled “Language 2”Version 2 added procedures with parameters and a value, arrays that name ranges of flags
or variables, text values made as the script runs, menus a script builds entry by entry,
and read-only questions about species, moves, items and the party (speciesget,
partyfind). Every version-1 script compiles to the same bytes it always did. The
sample’s shelf asks with a script-built menu in two columns:
temp(0) = menu(text("{0}'s books, read to pieces.", name(player)), columns: 2) { "Maps" -> 0 "Leave them" -> 2 "Field notes" -> 1}A game may also name its own commands in scripts/ext.pfsym and call them like any
other. Planned (plan 46): the Rust table that gives those commands their behaviour, on
desktop and DS; until then such a command answers 0. See
Rust extensions.
Editor hooks
Section titled “Editor hooks”Three hooks change what the engine is about to make, before it is used:
on wildmon(method, map) (a wild creature), on trainerparty(class, version) (a
trainer’s team) and on givemon(species, level, how) (a gift). They run at once inside
the engine’s step, so they may not wait: no say, no battle, no movement. The pend*
commands read and change the pending creature or team. A level-scaling hook, a shiny
route or a randomizer is a few lines; the guide has examples.
Planned (plan 46): event hooks that run after something happened (on battleend,
on catch, on evolve, on levelup, on mapchange, on hour, on itemget,
on save), editing hooks for eggs, shop stock and battle setup, script screens laid
out by records, and saved records a game declares.
Live reload
Section titled “Live reload”ploom run watches the project. Save a .pfs or .pfsym file and it is compiled and
loaded as soon as no script is running. The map’s scripts stop and its on load hooks
run again, as on arriving; flags and variables keep their values. A file with a mistake
is reported on the terminal and the game keeps the scripts it had.
Limits
Section titled “Limits”A file holds at most 32,767 bytes of code. Four scripts run at once, eight actors move by lists at once, a call goes 16 deep. The limits page and the reference have the full list.