Skip to content

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.

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 = 0
flag HAS_HAIRPIN = 1
flag ROOM_UNLOCKED = 2
lvar TRIES = 0 # forgotten whenever the map is left
item HAIRPIN = 17
sound CREAK = 13

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.

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

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.

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.

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

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.

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.

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.

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.

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.