Skip to content

Script language

The language for dialogue, cutscenes, gifts, watchers and story logic. Scripts are text files ending in .pfs. The compiler (pl-scriptc) turns each into a small binary module; the game never reads the text.

A complete example is in sample/scripts/. Every item, hook, statement, expression, command (with its number, arguments, kinds and defaults), built-in word, movement action and limit is listed, one row each, in docs/reference/script-language.md: it is generated from the command table the compiler and the machine read, so it is complete and never out of date. This guide explains them with examples.

# Comments run from # or // to the end of the line.
const GOT_GIFT = flag(12)
on talk greeter {
lock
faceplayer
say "Hello! Welcome to Ashgrove."
if !GOT_GIFT {
say "Take this."
giveitem TONIC, 3
set GOT_GIFT
} else {
say "Stay safe."
}
release
}
  • One file per map, next to the map, holding that map’s scripts.
  • One shared file for scripts any map can call (compile it with --shared). In a project it is scripts/common.pfs, followed by every .pfs file of scripts/shared/ in the order of their names: one module from several files, so that a game’s intro can be a file of its own (an import writes scripts/shared/intro.pfs beside its own common.pfs). An error names the file and the line it is in.
  • A symbol file (.pfsym) giving names to numbers, so scripts never contain a bare flag number or actor number:
# kind NAME = number
flag DOOR_UNLOCKED = 12
var STORY = 0
lflag WHISTLED = 0 # map-local flag
lvar TRIES = 0 # map-local variable
actor watchman = 2 # position in the map's actor list
spot signpost = 3 # a sign or trigger spot's number
map town = 1
item TONIC = 3

flag, lflag, var, lvar, const and actor names work anywhere. Every other kind (item, species, map, sound, music, trainer, shop, spot, string, and any you add) is looked up where a command expects that kind, so an item and a species may share a name.

pl-scriptc --shared -s game.pfsym --index shared.pfsym -o shared.pfsb shared.pfs
pl-scriptc -s game.pfsym -s shared.pfsym -o town.pfsb town.pfs

Without -o the file is only checked. Errors give the file, line and column, the line itself and a caret; one run reports every mistake it can find.

For a project the build does this for the whole folder: ploom build (for the sample game also cargo xtask data and every build-nds, test-nds and build-desktop) compiles scripts/common.pfs as the shared module and every other .pfs there with all the folder’s .pfsym files and the names the maps give (a map’s folder is a map name; a named actor, sign or trigger of a map is an actor or spot name), and puts the modules into the game’s pack, pack/game.pak. The game loads the shared module and, for each map, the module called after the map’s folder, or the one its map.toml names with script = "..." (the sample’s lab map runs station.pfs).

Live reload. The desktop game run with a window watches the project the data folder belongs to (sample for sample/pack, or --project DIR): save a .pfs or .pfsym file and it is compiled and loaded into the running game as soon as no script is running. (--scripts DIR watches a scripts folder alone and replaces the modules of the same names in the pack; scripts that use names from their maps need the project.) The map’s scripts are stopped 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.

Item Meaning
const NAME = value A name for a number, text, flag(n), var(n) and so on
array NAME = kind[from..to] A name for a range of flags or variables (below)
script name { ... } A script that call and start can name
on <event> [when condition] { ... } A script the game starts by itself (below)
hide actor when condition The actor is not there when the map loads if the condition holds
Event Starts when
on load The map has loaded, before anything is drawn. Every on load whose condition holds runs. Use it to put the map in its saved state; do not wait in it.
on enter The player has arrived and the screen has faded in
on resume Play has come back to the map without leaving it: a menu screen (the party, the bag, the options…) or a screen a script opened has closed, a battle is over, or a saved game was continued (after its on load). Every on resume whose condition holds runs, in the background, also while a script waits for the battle it asked for. Use it to put back what the map shows; do not wait in it. Not on arriving: that is on load.
on load, resume Once each time the field is set up: on arriving (as on load) and on every return (as on resume); a continued save, which runs on load, does not run it again. For a change that must hold whenever the map is shown.
on idle when condition Nothing else has the field (no script in the foreground, no menu, no warp or fade, no door being walked out of) and the condition holds: checked every tick, after on enter, before the player’s step and on sight (a game whose symbols say setting idle_after_sight = 1 checks it after on sight, as Emerald does). The first that holds runs in the foreground; nothing is checked while it runs, and as soon as it has ended the check goes on, so the script must make its own condition false or it runs again at once. It is how a scene starts by itself in the middle of a visit, when a variable changes (the original games’ frame tables). when is required.
on talk actor The player talks to the actor. self is that actor.
on read spot The player examines a sign or other spot
on step spot The player steps on any cell of a trigger spot (a trigger drawn over several cells covers all of them)
on step area(x, y, width, height) The player steps on any cell of the rectangle (area(x, y) is one cell)
on sight actor, range The actor, looking the way it faces, has the player straight ahead within range cells with nothing solid between. self is the watcher. It fires once, and not again until the player has been out of its sight. A hidden actor sees nothing.
on headbutt The player presses the talk button facing a tree one can headbutt (a cell of the map’s headbutt.toml, docs/creating-a-game.md). The map’s own hook first, else one in common.pfs. encounter headbutt in it reads the tree faced.
on fieldmove KIND In common.pfs: a field move is to be used (cut, surf, strength, rocksmash, waterfall, rockclimb, defog, flash, fly, dive): A before the tree, the rock, the boulder, the water, the waterfall, the rock wall or on deep water, or the move chosen on the party screen. self is the tree, the rock or the boulder. See docs/creating-a-game.md, “Field moves and getting about”
on follower The player talks to the following creature (a game with followers = true). self is the follower. The map’s runs if it has one, else the one in common.pfs; with neither the engine says a line of its own (docs/creating-a-game.md, “The following creature”).
on steps n The player has taken a multiple of n steps (1 to 65,535) in the whole game: the counter behind eggs, friendship, a charging device. In a map’s file or in common.pfs; see below.
on newgame A new game has begun: the start map is loaded and the screen is still dark. The shared module’s runs if there is one (the first whose when holds), else the start map’s. It is a game’s intro: say lines on the black, show pictures (below), ask for the player’s gender and name. The map’s on enter waits until it ends; when it ends, whatever pictures it left are taken down and the map fades in (from black or white, as the script left it)
on gameover In the shared file: a challenge game whose rules say challenge_over = "script" (in game.toml, or setrule challenge_over, 1) has nothing left that can fight after a battle (docs/creating-a-game.md). It runs once no other script is running; the game goes on from where it is, and the script decides what follows (give a creature, warp, endgame)
on option NAME In the shared file: the player changed the game’s option NAME ([ui.options] in game.toml) on the options screen and kept it. It runs once the menu is closed and no other script is running; several changed at once run one after another, in the options’ order. getoption NAME is already the new value. See “Rules, options and cheats” below

Except for on load and on resume, only one of these runs at a time (it is the foreground script), and among several that fit, the first in the file whose when condition holds is the one that runs. That is how a map plays a different scene on each visit:

on enter when STORY == 0 { ... } # the first visit
on enter when STORY == 3 { ... } # after something else has happened
on step area(9, 9, 3, 1) when STORY == 1 { ... } # a doorway, once

on steps works differently: every one whose count fits and whose when holds runs, the map’s then common.pfs’s, each in the background (as on load), after any on step the same step set off. The player keeps walking unless the script says lock. The count is the game’s (steps, saved with it), so on steps 256 fires on the 256th, 512th… step of the game, not of the visit. A step hook that finds all four script places taken does not run that step.

on steps 256 { EGG_STEPS += 1 } # common.pfs
on steps 1 when POISONED { say "Ouch." } # a map's file

A change to the map that should last (a door that stays unlocked) is a flag plus an on load:

on load when DOOR_UNLOCKED { setcell 10, 7, walk }

on enter when is looked at once, on arriving. A scene that must start as soon as something changes during the visit (a variable set by a talk, a battle or a background script) is an on idle when, which makes its own condition false. Back from a screen or a battle, on resume counts or puts back (sample/scripts/weir.pfs has both):

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
}

Three hooks change what the engine is about to make, before it is used (plan 46, task 46b). They run at once, inside the engine’s own step, so they may not wait: no say, no battle, no screen, no move (the compiler refuses them; one that waits anyway through a procedure is stopped). Each has at most 4,000 instructions; one stopped for its budget or a fault leaves what it was changing as it was, and the next hook runs. Hooks of one kind all run, common.pfs’s first in the order written, then the map’s. Their parameters are named like a procedure’s; fewer names take the first ones.

Event Runs when What it changes
on wildmon(method, map) A wild battle is about to begin, however the creature was met: a step in grass or water (method is the method word’s number: 0 land, 2 water…), encounter, a rod, a tree, a rock, a roamer, or a script’s wildbattle (8). map is the map’s number. The creature. pendcancel calls the meeting off: no battle, and a script that asked for it gets 0.
on trainerparty(class, version) A trainer’s team has been made from trainers.txt, before the battle; once for each trainer of a tag or multi battle. The team: pendcount() members, each by its index.
on givemon(species, level, how) givemon is about to store a creature (how 0). The creature.

The pend* commands work only in these hooks (and in procedures they call):

Command Does
pendget(field, index = 0, which = 0) A field of the creature, or of member index of the team; -1 for none
pendset field, value, index = 0, which = 0 Sets it, held to the rules monset keeps (a level 1 to 100, IVs 0 to 31, a move the pack has…); the value afterwards. field must be a word.
pendcount() Members (1 for one creature)
pendadd(species, level) In on trainerparty: a member added at the end (up to six); its index, or -1
pendremove index In on trainerparty: a member taken out (never the last)
pendcancel In on wildmon: no meeting

The fields are the monfield words (species, level, iv, ev, nature, ability, shiny, move, item, friendship …) and form, gender (0 male, 1 female, 2 none; only one the species can have) and ball. A creature whose species or form is set is made again as that species at its level, keeping its IVs, nature, shininess and item. A trainer’s member knows species, level, iv, ev, nature, move, item, friendship and gender.

Every wild creature met on one route shiny (the route’s own file):

on wildmon(method, map) { pendset shiny, 1 }

Level scaling (common.pfs): every trainer’s team follows the party’s highest level, each member keeping how far it stood below the team’s highest:

on trainerparty(class, version) {
let top = 0
let i = 0
while i < partycount() {
if monget(i, level) > top { top = monget(i, level) }
i += 1
}
let most = 0
let m = 0
while m < pendcount() {
if pendget(level, m) > most { most = pendget(level, m) }
m += 1
}
m = 0
while m < pendcount() {
pendset level, top - (most - pendget(level, m)), m
m += 1
}
}

random in a hook draws from the same generator as any script’s (pl-core’s), so a hook that draws gives the same creatures on desktop and DS and in a replay.

  • Numbers are whole, from about -2 billion to 2 billion: 12, 0x1F, 1_000.
  • Text is in double quotes. \n starts a new line, \p a new page, \r waits for a button and then moves the text up a line (“wait, then scroll”), \" and \\ are a quote and a backslash. {0} to {7} show the message buffers (see buffer).
  • Flags are yes or no: flag(0) to flag(4095) are saved; lflag(0) to lflag(63) are forgotten whenever the map is left.
  • Variables hold a number: var(0) to var(511) are saved; lvar(0) to lvar(31) are forgotten whenever the map is left; temp(0) to temp(15) belong to the running script and start at 0. A script called without brackets shares its caller’s temporaries, which is how values are passed to it; a procedure (below) has its own. let name = value names a temporary.
  • Actors: player, self (who the script was started for), marker (an invisible stand-in for the camera to follow), follower (the party’s lead walking behind the player, in a game with followers; hide follower keeps it in until show follower), npc(n), or a name from the symbol file.
  • Directions: down, left, right, up.
  • true is 1 and false is 0.

Expressions, tightest first: ! and -; * / %; + -; == != < <= > >=; &&; ||. Brackets group. A flag in an expression is 1 or 0. Both sides of && and || are always worked out. Dividing by zero gives 0. A command or a procedure that has a value can be used as name(arguments).

One to a line, or separated by ;. A line that ends in a comma continues.

Statement Meaning
set FLAG, clear FLAG
VAR = expr, VAR += expr, VAR -= expr
if cond { } else if cond { } else { }
while cond { }, break A loop without a wait is made to pause each tick; it cannot hang the game
for i in from..to { }, for i in ARRAY { } i runs from from up to to - 1, or over the array’s indices (below); break leaves it
call name Runs another script and comes back (16 deep at most)
call name(args), name(args) Runs a procedure (below); its value, if any, is dropped
let name = expr Names the next free temporary until the end of the block, and sets it
return Back to the caller; ends the script if there is none
return expr In a procedure with -> value: back to the caller with this value
end Ends the script, however deep in calls
start name Starts a script of this file in the background (see below)
move actor, [actions] A movement list (below)
command arg, arg, name: arg A command; -> VAR stores its value

When a script ends, the message box is closed and the lock released if the script left them.

A text value is what say and every other command that takes text takes: a string in quotes, a key of text.txt, or a line made as the script runs. Two commands make lines:

let who = name(species, partyspecies(0)) # a name
let line = text("{0} looks happy with {1}!", who, name(item, ORAN))
say line
if choice(line, ["Yes", "No"]) == 0 { ... }
Command Meaning
name kind, [value] → The name buffer would show for the kind and value (number, item, species, move, map, player, rival, pocket, tmmove, nickname), as a text value
text format, [values...] → The format with {0} to {7} replaced by the text of the values after it, as a text value. The format may be text in quotes, a key of text.txt, or another text value. A {n} with no value stays, and shows message buffer n when the line is said
  • A text value may be kept in a temporary, a variable or an array element.
  • The lines live in eight text registers of 64 bytes: each text and each name takes the next, and the ninth takes the first again. A line longer than 64 bytes is cut (on a whole character). Registers are not saved: a script that needs a name later asks for it again.
  • text’s values are text: a number is shown with name(number, n).

menu(prompt, ...) { entries } asks a question whose entries the script adds as it runs, each with a value of its own; the menu’s value is the value of the entry chosen.

let pick = menu("What will you buy?", at: right, cancel: -1) {
"Potion — 300" -> 1 when money() >= 300
text("{0} — 600", name(item, SUPERPOTION)) -> 2
for each in LIT { if LIT[each] { name(map, each) -> 100 + each } }
}
  • An entry is text -> value, with when condition to add it only when the condition holds. The body may hold any statements (for, if, let) around its entries; a line with -> in a menu’s body is an entry (store a command’s value with VAR = command(...) there).
  • Up to 64 entries; more than eight scroll. at: right (the default) or left places the list; cancel: is the value when the player cancels (-1 unless given). columns: n (2 to 4) lays the entries out in a grid, filling each row left to right: four rows show and more scroll; left and right move along a row, up and down a column, and on the touch screen a cell is touched.
  • A menu with no entries is not shown: its value is the cancel value.
  • Each entry’s text is read when it is added, so a text value may be made afresh for every entry.
  • It compiles to menubegin prompt, [at], [columns], [cancel], a menuitem text, value, [enabled] for each entry, and menushow →, which may also be written by hand (an imported game does).
  • choice stays as it was: options by place, at most 32.

An array is a name for a range of flags or variables that already exist; it adds no storage, so a save does not change.

array SEEN = var[100..120] # 20 saved variables: SEEN[0] is var(100)
array LIT = flag[2000..2064] # 64 saved flags
array HERE = lvar[0..8] # map-local; lflag and temp work too
SEEN[i] = SEEN[i] + 1
SEEN[i] += 1
set LIT[n]
if LIT[n] { ... }
len(SEEN) # 20, a constant
for i in SEEN { SEEN[i] = 0 }
for i in 0..partycount() { ... }
  • The range is from..to, to not included; at most 255 entries.
  • The index is any expression, written right after the name (SEEN[i]; with a space between it would be a list). Outside the array a read gives 0 and a write does nothing; the game logs it and the script goes on.
  • An array of temp is in the running script’s own frame: in a procedure, the procedure’s temporaries.
  • for keeps its counter in a temporary (and a second one when the end is worked out as it runs); the end is read once, before the first turn.

A script whose name is followed by brackets is a procedure: it takes arguments and may give a value.

script give_berries(kind, count) -> value {
let given = 0
while given < count {
if !giveitem(kind) { return given }
given += 1
}
return given
}
on talk farmer {
lock; faceplayer
let n = give_berries(ORAN, 3)
buffer 0, number, n
say "Here are {0} berries."
release
}
  • The parameters are the procedure’s first temporaries, in a frame of its own: what it does to its temporaries does not touch its caller’s. A let takes the next free one; it is named until the end of its block ({ }), and skips any temporary the body names itself as temp(n).
  • -> value says it gives a value: return expr gives it, and reaching the end (or a bare return) gives 0. A procedure without -> value is called as a statement, call name(args) or just name(args).
  • The number of arguments is checked when the file is compiled, for a shared procedure too: the shared index says how many it takes (script give_berries = 4 (2) -> value).
  • Procedures may call themselves. 16 calls deep at most, and all the frames of one script share 64 words: the outermost script’s 16 temporaries, then each procedure’s parameters and lets. Past either, the script stops with a fault.
  • A script without brackets keeps its version 1 meaning: call name shares the caller’s temporaries (a procedure’s, when a procedure calls it). A procedure cannot be named in call name without brackets, nor started.
  • let, value, array, for, in and the other words of the second version are words only where they are used: a script or actor already named let keeps working.

Arguments in square brackets may be left out. A name with a → has a value. The full list, with each command’s arguments by name and kind, is the generated reference (docs/reference/script-language.md).

Command Meaning
say text Shows a message and waits until the player has read it. The box stays up until closetext, release or the end of the script. text is text in quotes, or the key of a line of the project’s text.txt (say b02_bed_1): that line may use every code of text.txt ({pause:20}, colours, \r), and its {var:0} to {var:7} show message buffers 0 to 7. The line may also be in a file of text/ or of a folder in it (a bank of text, read when it is said).
sign text, [style], [icon] The same in the sign’s box. icon (0 by default: none) is graphics/ui/sign_icons/N.png, at most 7 x 4 tiles, shown at the left of the box with the text after it, as Platinum’s map and arrow signs show a map (task 25o). style (0 by default) is a frame of the game’s skin: 0 the sign’s own frame, n the frame n after it, so a game can have one look for each kind of sign (Black 2’s four, Platinum’s map and arrow signs); a skin without that frame shows the sign’s own. Written with a style or an icon it compiles to signex text, style, icon (a plain sign text keeps the bytes it always had)
sayline first, n Says the line n after first: first is a key of text.txt or of a bank of text/ (the lines of a file are numbered in their order), or a script’s own text (its file’s texts in the order they first appear). sayline t0012_0000, temp(3) says line temp(3) of bank 12: a message chosen at run time
choice prompt, [option, ...] → Asks; the value is the option’s position from 0, or -1 if cancelled. The prompt and each option may be text in quotes or a key of text.txt or a bank. Up to 32 options; more than 8 show in a list of 8 rows that scrolls with the cursor. (A choice of more than 8 compiles to one option text for each and listchoice prompt →, which can also be written by hand.)
yesno prompt → 1 for yes, 0 for no
closetext
buffer slot, kind, [value] Puts a name or number in buffer slot for {slot} in later text. Kinds: number, item, species, move, map, player, rival; pocket (a bag pocket’s name by its number, 1 to 8, as pocket gives it); tmmove (the move the machine item value teaches, by name); nickname (the name of the party’s creature in place value from 0, or its species’ when it has none; nothing for an empty place).
Command Meaning
lock, release Holds and frees the player and everyone’s own movement
wait ticks 60 ticks are a second. The overworld itself moves 30 times a second, so an odd number of ticks can show as one more or one fewer.
waitmoves Until every movement list is finished
waitbutton Until the player presses the button
waitsound Until the sound or fanfare has finished
random below → A number from 0 to below - 1
lastresult → The value of the last battle, choice or screen
setflag n, clearflag n, checkflag n → A saved flag by a number worked out at run time (setflag temp(2) + 100): 0 to 4095. Outside that nothing is set and checkflag is 0. set FLAG stays the way to name a flag
Command Meaning
faceplayer [who] Turns who (default self) to the player
face who, direction
look who, at Turns who towards another actor
approach [who] who walks in a straight line up to the cell next to the player, and the script waits. Does nothing when they are not in line.
show who, hide who A hidden actor is not drawn, blocks nothing and sees nothing
emote who, emote Shows alert, question, dots or glad above the actor and waits
place who, x, y Puts an actor on a cell at once. It stays there, shown or hidden, until the map is left: a hidden actor placed and shown later appears where it was put. The next visit starts from the map’s own places
mapnumber() → The number of the map the player is on, as its map name gives it: if mapnumber() == jubilife_mart { ... }
mover who, kind, [param] Changes how an actor moves by itself (below)
xof who →, yof who →, facing who → Where an actor is and which way it faces (-1 if there is no such actor)
sees who, range → Whether who can see the player now, by the rule of on sight

Movers, and what param means for each:

Kind The actor param
still stands as it was left
face stands facing one way, and turns back to it the direction’s number: 0 down, 1 left, 2 right, 3 up
in_place steps on the spot facing one way, step after step, the feet in turn the direction’s number + 4 × a speed’s (slowest 0 to instant 5: 2 walks, 3 jogs)
look turns now and then which ways: add 1 for down, 2 left, 4 right, 8 up; 0 is all four
spin turns a quarter clockwise at a steady pace
pace walks to and fro the way it faces cells each way
wander takes a step now and then how many cells from where it is now
range wanders within separate ranges; a range of 0 keeps it off that axis x range + 16 × y range (each 0 to 15)
circuit, circuit_back walks round a rectangle, turning right or left at its corners cells along x + 16 × cells along y

While a script holds the game with lock nobody moves by a mover; movement lists still run.

move player, [up * 3, face_left]
move watchman, [speed(fast), right * 4, pause(30), emote(alert)], wait: false
move marker, [down * 6], wait: false
waitmoves

move waits for all movement to finish unless it ends in wait: false. Lists given to several actors with wait: false run at the same time; one waitmoves waits for all of them. Giving an actor a new list replaces its old one. At most 8 actors can be moving at once.

Action Meaning
down, left, right, up Walk a cell; * n repeats
face_down … face_up Turn
mark_down … mark_up Walk in place; * n repeats
jump_down(n) … jump_up(n) Jump n cells, 0 to 3 (0 hops on the spot)
pause(ticks) Stand still
speed(s) Speed of the steps after it: slowest, slow, normal, fast, fastest, instant: a cell in 32, 16, 8, 4, 2 or 1 thirtieths of a second. normal is walking, fast is running.
lock_facing, unlock_facing Keep facing the same way while stepping (walking backwards)
hide, show
emote(e)
freeze, unfreeze Hold and resume the step animation

Scripted steps ignore the pad; the player is moved the same way as anyone else. They also ignore walls and other characters: the script is trusted to know the map. A jump of 1, 2 or 3 cells takes 8, 16 or 24 thirtieths of a second; on the spot, 8. An emote stays for 0.8 seconds.

Command Meaning
warp map, x, y, [facing] Leaves for another map. The script ends here. To carry on in the new map, set a variable and use on enter when.
setcell x, y, cell Changes what a cell is until the map is left: walk, blocked, grass, water, ledge_down (and _left, _right, _up), stairs, ice, door, counter, waterfall, rock_wall, bike_path, deep_water
settile x, y, tile, solid On a tile map: the tile at a cell becomes number tile of the map’s tilesets (the primary’s first, then the secondary’s), at the same height, and the cell takes the new tile’s behaviour (or is solid with solid 1), until the map is loaded again. Put it in on load to have a map start changed. A 3D map ignores it
door x, y, open / close Opens or closes the door leaf standing on a cell and waits for it: the leaf slides one cell along its wall in 8 frames, with a sound on the first (pl_world::doors; it slides rather than swings). It changes only what is drawn: use setcell to let people through. In on load it does not wait.
fade out / in, [colour], [ticks] Fades to or from black or white and waits; without ticks, the usual length. While the picture is faded right out to black a message can still be read: say shows its box on the black screen. In on load, fade out, black, 1 makes the map arrive dark, for a scene that starts with words.
shake strength, ticks See “Camera”
camera who The camera follows this actor, at once. For a slow pan see “Camera” below; a pan by a stand-in still works: place marker, ..., camera marker, move the marker, then camera player.
weather kind none, rain, heavyrain, snow, blizzard, sand, fog, sun, ash, diamonddust (what each draws: docs/creating-a-game.md, “Weather”), or dark (a dark map, no weather). The change fades over about two seconds and does not wait; in on load the weather is full at once. It lasts until the map is left; a map’s own weather in map.toml is on when it is entered
tint red, green, blue This colour becomes the main light (the sun’s, docs/creating-a-game.md, “Light”) in the place of the hour’s, the map’s grade and the weather’s: each 0 to 255, 255, 255, 255 shows the pictures as drawn. Lamps and constant materials keep their light. It lasts until the map is left, or until tint alone (no colour) brings the hour’s light back: a room that must stay dark says it again in on load. Every palette is multiplied again at once (a few frames on a DS): do it under a fade

The camera follows the player at the map’s framing, or at a camera zone’s (docs/creating-a-game.md, “Camera zones”). These commands move it: each eases from wherever the camera is to the framing asked for over ticks (60 a second), and waits until it is there unless it ends in wait: false. A camera a script has moved stays where it was put, zones or not, until camreset.

Command Meaning
cammove [pitch], [distance], [ticks], [ease], [fov], [wait] A new framing: the tilt down in degrees (20 to 70), the distance back in sixteenths of a cell (96 to 1600), the field of view in tenths of a degree (40 to 400). What is left out stays as it is. Write it with names: cammove pitch: 38, distance: 420, ticks: 90
campan x, y, [ticks], [ease], [wait] Looks at the middle of a cell and stays there, whoever moves. At most 8 cells from the player (the world is loaded around the player); a cell further is brought in to 8
camfollow who, [ticks], [ease], [wait] Goes to an actor and follows it from then on (camera who does the same at once)
camreset [ticks], [ease], [wait] Back to the map’s or the zone’s framing, following the player
camwait Until a move given with wait: false is over
shake strength, ticks Shakes the picture from side to side by strength sixteenths of a cell (1 or 2 is a jolt)

ticks is 30 unless given (0 is at once). ease is how the move speeds up and slows down: inout (the default: starts and ends slowly), in (starts slowly, arrives at speed), out (starts at speed and settles) or linear. A move given while another is under way starts from where the camera is.

A camera move, a fade and a message can go on together: give the move with wait: false, then the fade or the say, then camwait if what follows must wait for the camera.

on load when !IN_STATION {
cammove pitch: 38, distance: 420, ticks: 0 # low, behind the fade
}
on enter when !IN_STATION {
lock
set IN_STATION
wait 30
campan 9, 10, 150 # slowly along the floor to her
say b05_enter # said while the camera holds there
closetext
camreset 90 # back to the room, following again
release
}
on read station_window {
...
cammove distance: 360, ticks: 50, ease: in, wait: false # in close...
move player, [jump_up(1)]
fade out, black, 30 # ...as it fades
warp station, 6, 12, up
}

What to keep in mind:

  • In on load only ticks: 0 makes sense (the picture is not up yet): it sets where the camera starts when the screen fades in.
  • A lower camera sees further north: keep to the distances of the table in docs/creating-a-game.md for the tilt you use, or the top of the screen shows the colour behind everything (the game notes it once in its log: pl-field: note: the camera shows past the drawn ground).
  • Leaving the map gives the camera back to the next map’s framing.
Command Meaning
playsound sound Plays an effect. waitsound waits for as long as it lasts
playmusic music Changes the music, fading over half a second; playmusic none stops it; playmusic map goes back to the map’s own track (its music in map.toml; nothing changes on a map that names none). A track marked once (below) plays once through and then stops
fademusic [ticks] Fades the music out over ticks (30 unless given) and waits. playmusic brings music back
cry species, [pitch], waitcry Plays a species’ cry, from audio.txt’s cry lines; pitch from -128 (an octave down, twice as long) to 127 (about a fifth up), 0 unless given. waitcry waits until it has played, as long on every platform; with no cry for the species it does not wait
fanfare music Plays a jingle over the music and waits for it: the music is put aside and comes back where it was when the jingle ends. The track must be marked once; a track that loops is not played as a fanfare (it would never end) and is not waited for

Jingles: tracks that play once. A fanfare, a jingle for an item found or a level gained, a short sting: any track can be one. Mark it once in audio/audio.txt:

music town_night music/town_night.xm
music found_it music/found_it.xm once

A once track is not looped: it plays through once and ends where its song would start again. The build works out how long that is, from its rows, speeds and tempos, and adds a tenth of a second for the last note to ring; fanfare waits that long, the same on every platform, and the track is stopped then whatever it holds. Then:

  • after fanfare, the music that was playing comes back where it was (from the start of the row it had reached, on DS); over silence, silence comes back;
  • after playmusic of a once track, the music stops;
  • a battle during a jingle puts the jingle aside too, and the rest of the jingle plays after it before the music comes back;
  • playmusic (or a warp to a map with other music) during a fanfare replaces both the jingle and the music under it.

Nothing else is needed in the module itself.

Sound effects and memory. On a DS only the effects marked keep in audio.txt stay loaded all the time; every other effect, and every cry, is read from the cartridge the first time it is played and stays loaded while there is room for it, the oldest-played going first. A game can therefore have thousands of effects. Mark keep the few the player hears all the time (the menu’s cursor and confirm, doors, the bump), so that not even their first play waits for the cartridge:

sfx menu_move sfx/menu_move.wav keep
sfx confirm sfx/confirm.wav priority=2 keep
sfx ice_crack sfx/ice_crack.wav

Reading an effect takes about half a millisecond and a quarter of a millisecond per KB of it on DS, measured in melonDS (see docs/tasks/13c-audio-on-demand.md); what is loaded already plays at once. The build prints how much memory sound takes at most and stops if it is over the budget.

Of the DS’s 512 KB for sound, music has 320 KB: one module with its samples may take no more (the build says which module is over, and by how much). The rest, at least 192 KB, is for the effects kept loaded and the cache. On DS an effect or cry longer than two seconds at 16 kHz (32,768 samples) is stored as IMA ADPCM, half the room of 8 bits, by the build itself; the desktop plays it as it is. Modules that ploom import and ploom import-midi write are fitted to the 320 KB already (see docs/tasks/13d-audio-budget.md).

Command Meaning
giveitem item, [count] → 1 if it fitted in the bag
takeitem item, [count] → 1 if the player had that many
hasitem item, [count] →
canhold item, [count] → 1 if that many more would fit in the bag (a key item fits once; 999 of anything else); 0 for an item the pack does not have
pocket item → The item’s bag pocket: 1 items, 2 medicine, 3 balls, 4 machines, 5 berries, 6 mail, 7 battle items, 8 key items (as pbs/items.txt gives it); 0 for no such item. buffer s, pocket, n names it
istm item → 1 if the item is a machine (FieldUse = TM, HM or TR). buffer s, tmmove, item names its move
partycount →, partyspecies slot → How many creatures of the party are not eggs; the species in place slot from 0 (0 for an empty place or an egg)
badge n →, setbadge n, [on], badges → The player’s badges: marks 0 to 31, kept in the save. Whether the player has badge n; gives it (setbadge n, false takes it back); how many there are
gender →, setgender gender The player’s gender as the game counts it: male (0, and what a new game has) or female (1), or any number to 255. Kept in the save. Nothing in the engine reads it; scripts and hide rules do
record r →, addrecord r, [amount] The game’s records: 32 counters kept in the save. The engine counts steps (each cell the player arrives on), battles (each begun), wins, catches, trades (trademon) and saves itself (records 0 to 5; 6 to 15 are kept for more of the engine’s); 16 to 31 are the game’s own. addrecord adds 1 unless told otherwise. Name them in a symbol file: record FISH_CAUGHT = 16
journal kind, [a], [b], [c], [d] Notes an entry in the player’s journal: a kind and four numbers (0 to 65,535), all the game’s to give a meaning, and the map it was written on. The journal keeps the last 16, in the save. Nothing shows it yet
journalentry n, [field] → Reads entry n of the journal, the newest 0: field 0 its kind, 1 its map, 2 to 5 its numbers; -1 for no such entry or field
givemon species, level → 1 if it joined the party, 2 if the party was full and it went to storage, 0 if there was no room anywhere
hasmon species → 1 if a creature of that species is in the party
healparty Full HP, no status, full PP for the whole party. Where the player stands becomes the place a lost battle returns them to
setaside species, slot → The story takes the party’s first creature of that species away and keeps it, exactly as it is, in place slot (0 to 3). 1 if it did; 0 if the party has none or the place is taken. It may take the only creature: with the party empty no wild creature is met.
bringback slot → The creature kept in place slot rejoins the party, at its end, as it was. 1 if it did; 0 if the place is empty or the party is full (the creature stays kept). Creatures set aside are saved with the game.
wildbattle species, level → A battle with a wild creature of that species and level. The script waits; the value is its outcome: 0 lost, 1 won, 2 ran, 3 caught (0 also when the player has no creature that can fight)
trainerbattle kind, name, [version], intro: text, defeat: text, [lose: way], [money: false], [exempt: true], [mode: who], [called: rival], [music: kind] → Says intro, fights the trainer of that class and name in the data pack, shows defeat when the trainer loses, and pays the prize; the value is the outcome as above (1: the player won; 0 also when the pack has no such trainer). lose: is what a loss does: respawn (the default: the party is healed and the player is back where it was last healed, and the script ends), stay (nothing: the script goes on and reads the outcome, the party as the battle left it) or rest (as stay, with the party healed). money: false is a battle that neither pays nor costs. exempt: true marks it as outside the rules of a permadeath game (a spar). mode: says who chooses the trainer’s moves: class (the default: the trainer’s AI = line in trainers.txt, else its class’s skill level), or one of the levels random (also easy), basic, medium, hard, expert (docs/creating-a-game.md, “Trainer AI”). called: rival shows the trainer by the name the player gave their companion (askname rival), once there is one, instead of the class and name of the data, and plays the rival track of [battle.music] in game.toml. music: plays another of its tracks: wild, trainer, rival or final (the default, foe, is trainer, or rival with called: rival)
shop stock, [percent: n] Opens a shop with a stock list of pbs/shops.txt and waits until the player leaves it. percent multiplies every price asked (percent: 200 is a shop that charges double); what the shop pays for the player’s things is not multiplied
shopin stock, currency, [percent: n] A shop priced in a currency of [rules.currencies] (the frontier’s points, a game corner’s coins): the items’ prices times percent, paid from the currency, which the amount box shows. It only sells: it opens on its list, and leaving the list leaves the shop
storage → Opens the storage screen and waits until the player leaves it: the boxes beside the party, to move, withdraw, deposit and release creatures (docs/tasks/11e-storage.md). 1 if anything was moved or released, 0 if not
askname who → Opens the naming screen for player or rival, with the name there is (or the game’s own) already typed, and waits. 1 if a name was confirmed, 0 if the player left with nothing typed. The name is saved and is what {player} or {rival} and buffer slot, player / rival show
choosemon → Opens the party screen to have a creature chosen and waits: its place in the party from 0, or -1
givemoney n, takemoney n →, money → Adds money (to at most 999,999); takes it, 1 if the player had that much, else 0 and nothing taken; the amount the player has
showmoney, hidemoney Shows the money box at the top left, where it stays beside what is said and follows givemoney and takemoney, until it is hidden
respawn map, x, y Sets where a lost battle returns the player (kept in the save), as healparty does for where the player stands
menuentry map, [on] Lists the menu’s Map entry from now on (menuentry map, false: no longer), kept in the save. In a game with a region map (region.toml, docs/creating-a-game.md) the entry is not listed until this is said; a game without one lists it as before
menuentry journal, menuentry dex, menuentry card, [on] The same for the journal (listed always; until this it says “not yet”, and nothing is written in it), the dex and the trainer card (not listed until this). Kept in the save
journalnote text Writes a line in the journal screen’s diary on today’s page, if the game has given it: a string of text.txt by its key (journalnote met_garrick), or the script’s own words (journalnote "Met Garrick.", at most 24 bytes are kept). The same line twice in a day is written once
trademon slot, species, level, [item] → A trade with someone of the story: the party’s creature in place slot (from 0) leaves, and a new one of species at level, holding item, takes its place, with an owner of its own. If what arrives evolves by being traded (Trade, TradeItem, TradeSpecies and the others, docs/creating-a-game.md), the evolution screen shows it and the script waits. 1 if it was traded; 0 if the place is empty or the pack has no such species
evolveevent n → Every creature of the party that evolves by event n (Event, EventAfterDamageTaken) evolves, one after another on the evolution screen, and the script waits. The value is how many were to (B may still stop one)
encounter method → A wild meeting the player starts: the map’s table for method (land, cave, water, oldrod, goodrod, superrod, rocksmash, headbutt) is rolled once, as a step’s is (the time of day, the swarm and the radio count; no repellent does). Met: a wild battle, and the script waits; the value is its outcome as lastresult gives it. Nothing met, no table, or no creature that can fight: -1. In on headbutt, headbutt is the tree faced (its kind’s table; -1 for a tree the player’s identifier leaves empty). A rod’s battle counts as fishing for the Lure ball
fish method → A cast of a rod (oldrod, goodrod, superrod) into the water the player faces, as the game’s [world.fishing] plays it (docs/creating-a-game.md, “Fishing”); the script waits. Landed: a wild battle, and the value is its outcome as lastresult gives it. Else -1 nothing bit, -2 A pressed before a bite, -3 a bite let go, -4 no cast (no water ahead, not a rod, no creature that can fight, or a game that does not fish)
knowsmove move → The party place, plus one, of the first creature that knows the move; 0 for none (for field actions that want one)
fruitstage tree, [hours] → How far fruit tree tree (0 to 127, the game’s own numbering) has grown back: 0 just picked to 4 ripe. A tree never picked is ripe. hours is its time to grow; 0 (the default) is overnight: ripe again on any later day
pickfruit tree, item, [count], [hours] → Picks the tree if it is ripe: count (1) of item into the bag, and it starts growing again. The number given; 0 if it is not ripe or the bag has no room. Saved
craftorder fruit, product, [count] → Gives the craftsman count of fruit (0, the default: all the bag holds) to make into as many product. The number taken; 0 if an order is waiting or the bag has none. One order at a time; saved
craftstate → 0 no order, 1 waiting, 2 ready (from the day after it was given, by the calendar)
craftcollect → A ready order into the bag: the number given; 0 if none is ready or there is no room (the order stays)
swarm map, [on] Today’s swarm is on map (its ...Swarm tables are used there), or with false no longer. One map at a time; saved
radio sound The radio plays sound 1 or 2 (the ...RadioA, ...RadioB tables are used everywhere), or 0 for none; saved
daycare what, [slot] → Asks the day care (docs/creating-a-game.md, “The day care and eggs”): count left (0 to 2), egg 1 when the keeper has one; of place slot (0, the default, or 1) its species (0 for none), its level now, the levels it gained, the fee to take it back (100 and 100 a level), its gender (0 male, 1 female, 2 none; -1 for nobody); compat, how the two get on, 0 (never an egg) to 3
daycaregive slot → Leaves the party’s creature in place slot (from 0) at the day care, healed, for nothing: 1; 0 if both places are taken, it is an egg or it is the last that can fight
daycaretake slot → The day care’s creature in place slot joins the party as it has grown (its experience a point a step, by the game’s rules): 1; 0 with the party full, -1 with nobody there. The fee is the script’s to take (takemoney)
daycareegg → The keeper’s egg joins the party, made now from the two by the game’s daycare rules: 1; 0 with the party full, -1 with no egg
yard who, slot The actor shows the day care’s creature in place slot by its follow sheet, wandering as its mover says; hidden while the place is empty or the game has no follow sheets. Say it in on load; the day care’s calls show the change
canuse kind → Field moves: the party place of the creature that would use kind (its name in buffer 0, the move’s in buffer 1), 6 when an item gives it, -1 when nobody can or the game’s flag for it is not set
fieldmove kind → Uses the field move here: 1, or 0 where it cannot be used; rocksmash gives -1 when nothing was under the rock, else how the battle went. fieldmove bike gets on or off the bicycle. After fly and dive the player leaves the map: end the script
travel → How the player gets about: 0 walking, 1 cycling, 2 surfing, 3 diving
save → Saves the game where the player stands; 1 if it was saved. If it could not be, the engine tells the player why before the script goes on
endgame Saves the game, fades out and goes back to the title screen. The script does not go on
ext n, ... → A command the game added in Rust, by number; better by its name (below)

What a game’s cheats, rewards, story and rules need, with data and scripts only (docs/creating-a-game.md, “Rules, options and cheats”, has the game.toml side).

Command Meaning
monget slot, field, [which], [box: b] → A field of the creature in party place slot (from 0), or with box: b of box b (from 1) at slot (0 to 29); -1 when there is none there. box: 0 (the default) is the party
monset slot, field, value, [which], [box: b] → Sets a field, held to the engine’s rules (below), and works the stats out again. The value is the field’s afterwards: what was asked, held to its range, or the old value when the change is not allowed; -1 when there is no creature there, the field cannot be set, or it is an egg
rule r → A rule of the game (below)
setrule r, value Sets a rule, held to its range, from now on and in the save
getoption NAME → The value of the game’s own option NAME (from 0, its values in the order game.toml lists them); -1 for an option the game does not have
setoption NAME, value Sets it, held to its values. It does not run on option
banner Shows the location banner with the map’s name again (task 25i), whatever the game’s [world.banner] says about arriving; nothing on a map with no banner style or no name

Fields (which is a stat for ev and iv: hp, atk, def, spa, spd, spe or all; a move slot, 0 to 3, for move and pp):

Field Read Set
species the species’ number cannot be set
level 1 to 100 1 to 100; the experience becomes that level’s first
exp the experience 0 to level 100’s; the level follows
ev one stat’s effort value; all their sum at most 252 a stat and 510 in all: a stat takes what room is left. all sets each stat in order, HP first
iv one stat’s individual value; all their sum 0 to 31; all sets the six
nature 0 to 24 0 to 24 (it changes the stats too)
ability the slot: 0 and 1 the species’ abilities, 2 and up its hidden ones a slot the species has; another is refused
shiny 1 or 0 on for anything but 0
move the move in the slot, 0 for none a move of the pack, with full PP, into that slot (or the first free one when the slot is past the moves known); one it knows in another slot is refused. 0 forgets the slot’s move, and the later ones move up; the only move cannot be forgotten
pp the PP of the slot’s move 0 to the move’s most
item the item held, 0 for none an item of the pack, or 0
friendship 0 to 255 0 to 255
hp the HP 0 to the most

A change of level or experience learns no move and starts no evolution: give the move with monset ..., move and the evolution with evolveevent. The level cap does not bind monset. A creature in a box keeps the challenge mode’s mark if it has one.

Rules (each off, or 0, unless game.toml or a script says otherwise):

Rule Value
challenge 1 in the challenge mode (“nuzlocke”), else 0. A script can turn it on or off at any time, with or without the title screen’s entry
challenge_box the box (1 to 20) a creature the challenge takes is kept in; 0 releases it
challenge_first 1: only the first wild creature met in each map may be caught
challenge_over 1: nothing left that can fight runs on gameover; 0: the game ends and the title screen comes back
level_cap 0 for none, or 1 to 100: no creature of the player’s gains experience past it, and no wild creature above it can be caught
exp_all 1: every creature of the party that can fight gains experience from a battle; those that were not in it half
no_battle_items 1: only capsules can be used from the bag in a battle
battle_style 1: the set style. The engine offers no switch when a foe faints in either style yet (the shift style is not built), so this is kept for when it is
tera 1: the player’s creatures may terastallize, one a battle, into their tera type (task 36a)

Until a script sets a rule the game follows its game.toml; once one is set the game keeps all of them with it (the save’s rules section), so a later game.toml changes new games only. challenge and exp_all are kept with the player as they always were.

# A cheat: an option of game.toml's [ui.options] and its script (common.pfs).
on option max_evs when getoption(max_evs) == 1 {
lock
temp(0) = 0
while temp(0) < partycount() {
monset temp(0), ev, 0, all
monset temp(0), ev, 252, atk
monset temp(0), ev, 252, spe
monset temp(0), ev, 252, hp # 6 left of 510: it gets 6
temp(0) += 1
}
say "The party's effort values are\nas high as the rules allow."
release
}
# Before the professor speaks: a nuzlocke without the title's entry.
on enter when !ASKED_RULES {
lock
set ASKED_RULES
if yesno("Play as a challenge?\nA creature that faints is lost.") {
setrule challenge, 1
setrule challenge_first, 1
}
closetext
# ... the professor's welcome
release
}
# After the first badge: a level cap.
setbadge 0
setrule level_cap, 20

The sample does all three: sample/scripts/common.pfs (on option max_evs), station.pfs (the question before the clerk) and town.pfs (the cap after beating the gate watch).

A command a game adds in Rust is named in a symbol file of scripts/, ext.pfsym by custom, with its number, its parameters and whether it has a value:

ext dig_site = 0 (x, y) -> value
ext stamp = 2 (kind)
ext chime = 7

Scripts then use it as any command: dig_site 4, 7, var(0) = dig_site(x: 4, y: 7), stamp 3. It compiles to ext 0, 4, 7; every argument is a number and must be given. One without -> value cannot be used in an expression. A game with no such command (or a number it does not have) answers 0, as ext always has. The Rust side (the table of commands a game crate gives the engine) comes with plan 29’s game crates.

Beside money a game may have currencies of its own (coins for a game corner, points for a battle facility, tokens): each is declared in game.toml with its name on screen (a line of text.txt) and the most the player may hold, and scripts use it by its name.

[rules.currencies]
coins = { label = "cur_coins", max = 9999 }
bp = { label = "cur_bp", max = 9999 }
Command Meaning
currency c → The player’s amount
givecurrency c, n → 1 if all of it fitted under the most, else 0 and nothing given
takecurrency c, n → 1 if the player had that much, else 0 and nothing taken
currencyroom c → How much more fits
showcurrency c, hidecurrency c Shows the amount in the money box, which follows it until hidden. The box shows one thing at a time: the currency, or money (showmoney)

A currency the game does not declare reads 0 and takes nothing. Up to 8. The amounts start at 0 and are kept in the save.

The four services of a creature’s moves and name (task 11l) are screens a script opens for a creature it chose with choosemon (the party picker). What each game asks of them (an item for the lesson, an egg turned away, one move always kept, another trainer’s creature left alone) is the script’s: the engine owns the lists, the screens and the deletion.

Command Meaning
teachable tutor, slot [, mode] → How many moves the tutor could teach the creature in that party place: those its species may learn (TutorMoves) and it does not know. 0 for an egg
teach tutor, slot [, mode] → The list of those moves as a window: each move’s price as the cursor passes it, A to learn one. A creature that knows four is asked which to forget (a field move cannot be, in a game with keep). The price is taken only when the move is learned. 1 if a move was learned, else 0
movecount slot → How many moves the creature knows
forgetmove slot → The deleter’s list of its moves; the one chosen, once confirmed, is forgotten and the later ones move up. 1 if one was. It takes no creature’s only move: check movecount first
rateable slot → 0 the name rater takes it, 1 an egg, 2 another trainer’s creature
namemon slot → The naming screen for the creature, starting from its name. 1 renamed, 2 the name it had, 0 left

tutor is a tutor of game.toml or relearn, the move relearner. The relearner offers the level-up moves up to the creature’s level that it has forgotten; mode 1 adds its egg moves and 2 every level-up move, whatever the level (0 is the default). A tutor is data:

[rules.tutors.cove.moves]
BRACE = { cost = 3, pay = "coins" } # a currency of [rules.currencies]
BARGE = { cost = 400 } # money, the default
WARCRY = { cost = 1, pay = "OLDCOIN" } # an item from the bag

and the moves it may teach a species are that species’ TutorMoves. A relearner’s price is whatever the script takes (takeitem after teach returned 1, as Emerald’s Heart Scale). keep_field_moves = true in game.toml is the older games’ rule: a creature keeps a field move until the deleter takes it, and the lists of these screens, of the evolution screen and of a level-up in battle do not let it be forgotten for another move.

Read-only questions about the game’s data (the pack’s records) and the party. Each has a value; -1 means the pack has no such record, or nothing fits.

Command Meaning
speciesget species, FIELD → A field of a species’ record: hp, atk, def, spa, spd, spe (base stats), statsum, type1, type2 (the first again for one type), ability1, ability2, hiddenability, genderratio, catchrate, egggroup1, egggroup2, growthrate, dexnumber (national), basehappiness, baseexp, hatchsteps, height (tenths of a metre), weight (tenths of a kilogram), form, basespecies
moveget move, FIELD → type, category, power, accuracy (0 never misses), pp, priority, target
itemget item, FIELD → pocket, price, sellprice, fielduse, battleuse, holdeffect, machinemove (the move a machine teaches), flingpower
partyfind KIND, value → The first place of the party (from 0) whose creature fits, -1 for none; eggs never fit. Kinds: species, move (knows it), type (either of its species’ types), item (holds it), fieldmove (can use it here and now: cut, surf…), able (can fight; the value is not read), lead (the first that is not an egg)
partytally KIND, [value] → How many of the party: creatures (not eggs, as partycount), eggs, fainted, species (of the species value), able (not eggs, not fainted)
if partyfind(move, CUT_MOVE) >= 0 { say "Someone could cut this tree." }
if speciesget(partyspecies(0), type1) == FIRE_TYPE { ... }
for i in 0..partycount() { if monget(i, hp) == 0 { ... } }

A game’s pictures for scenes that are not the field: the professor’s intro, the choice of a boy or a girl. They are the PNG files of graphics/art/ (up to 256 × 192 each), named by their file names (graphics/art/prof.png is prof), and shown on the main screen in front of the map, behind the text box. There are two places: behind (a backdrop) and in front (a person, a creature). On a black screen (fade out, or an intro before the map is seen) the pictures and the text box are seen and the map is not.

Command Meaning
showpic picture, [x], [y], [front: true], [touch: true] → Shows a picture with its top left at tile column x, row y (0, 0 unless given; a DS screen is 32 × 24 tiles), behind, or in front with front: true, or as the touch screen’s backdrop with touch: true (in front of its idle picture; it has that screen’s room to itself). It replaces what that place showed. 1 if it was shown; 0 if the game has no such picture or there is no room for it beside the others
showmon species, [x], [y] → Shows a creature’s front picture in front, at tile x, y (10, 4 unless given)
hidepic [which] Takes the pictures down: back, front, touch or all (the default)
choosepic first, second → Shows two pictures in front side by side, each standing on the text box in the middle of its half of the screen, the one not chosen darkened, and waits: left and right choose, A takes the chosen one (0 or 1), B leaves (-1). The text box stays as it was, so the question said before it stays up. The pictures stay after it: take them down or show the chosen one again
pickmon first, second, [third], [fourth] → A choice among the front pictures of two to four creatures (species; 0 is none), side by side on the text box, the ones not chosen darkened: left and right choose (round at the ends), A takes one (its place, from 0), B leaves (-1). The pictures go when it closes. A starter’s screen: while v < 0 { v = pickmon(a, b, c) }
pickitem pocket → Opens the bag on one pocket (1 to 8) to choose an item, which stays in the bag: the item, or 0 when the player leaves. Other pockets cannot be reached and nothing else is offered
on newgame {
say "Hello there!" # on the black
showpic intro_back # the backdrop
showpic prof, 12, 2, front: true # the professor in front of it
say "Are you a boy or a girl?"
setgender choosepic(boy, girl)
hidepic front
askname player
}

The pictures of one screen share its video memory: at most 522 tiles of 8 × 8 pixels and 6 palettes of 15 colours for all those shown at once (a backdrop that is one colour gradient takes a few tiles; a person of 64 × 128 pixels about 100 and one or two palettes). The build fits each picture into its share and says so when it had to bring colours together. | halloffame → | Enters the party (its eggs left out) in the Hall of Fame and shows the team, one creature at a time, until the player has pressed through them; the value is how many teams have ever been entered (0, and nothing shown, with nobody to enter). The record keeps the newest [hall] limit of game.toml (docs/creating-a-game.md, “The end”) | | hallview → | Opens the viewer of the Hall of Fame (entries and their creatures) and waits until the player leaves it; the value is how many teams have ever been entered | | hallcount → | How many teams have ever been entered in the Hall of Fame | | credits [part] → | Shows part part (0 by default) of the project’s credits.txt: scrolling or paged text and creature pictures, and waits. 1 when they were shown to the end, 0 when a button ended them (when the file lets one) or there was nothing to show. Play the music before it | | ext n, ... → | A command the game added in Rust |

Command Meaning
hour →, minute → The game clock’s time of day: 0 to 23, 0 to 59
weekday → 0 (Sunday) to 6 (Saturday)
day →, month →, year → The date: 1 to 31, 1 to 12, the year
clockchanged → 1 while new days are held back because the clock was turned back (below), else 0
steps → Steps the player has taken in the whole game

The game clock is the platform’s (the DS’s own clock, the computer’s) read when the game starts and counted on in ticks; the game looks at the platform’s clock once a minute and follows it if it has moved (the project’s resync_minutes). A recorded session replays with the clock it was recorded with. pl-desktop --hour 23:59 --date 2026-11-14 starts at a chosen time.

Daily and weekly flags. game.toml can name runs of saved flags and variables that start again each day or week ([time] in docs/creating-a-game.md): when the date changes, at midnight in play or when a save is loaded on a later date, the daily flags are cleared and the daily variables are 0; when a week begins (on Sunday), the weekly ones too. A once-a-day gift is a daily flag:

on talk gardener {
lock
faceplayer
if GOT_BERRY_TODAY { # a flag of `daily_flags`
say "Come back tomorrow."
} else {
giveitem BERRY
set GOT_BERRY_TODAY
}
release
}
on enter when weekday() == 2 { ... } # something on Tuesdays

A clock turned back. A clock moved more than an hour earlier than the game last saw it was turned back. Unless the project says clock_changed = "ignore", no new day or week begins for the next 24 hours (penalty_hours) and clockchanged is 1 meanwhile, so a script can say something about it. A clock turned forward cannot be told from time passing.

Scripts compile and run, but some commands have little or nothing behind them until other plans land. They are logged (pl-field: sound effect=..., pl-field: system call=...) and answer as follows:

Commands Now
playsound, playmusic, fanfare Played: the number is the sound’s or the track’s position in the project’s audio.txt; a number past its end plays nothing. Music fades over half a second. waitsound waits for as long as the effect or the jingle lasts.
ext Does nothing; its value is 0
a lost battle Costs no money unless the project says lose_money = true in game.toml. A wild battle lost sends the player back to where the party was last healed (healparty), healed, or leaves them in place if it never was
buffer slot, item / species The name in the data pack. Item and species numbers in a symbol file are the pack’s (pack/game.sym).
buffer slot, map The name the map gives itself in its map.toml. A map without one shows the sample’s map_N string of text.txt if there is one (maps 0 to 2), else its number. move shows the number.
choice, yesno with a named string as prompt or answer Shown empty; write the text in the script

An item used from the bag. An item whose FieldUse is Direct and which has no FieldEffect (see docs/creating-a-game.md) runs a script when the player chooses “use”: the bag and the menu close, and the shared file’s hook for it starts.

on use STATIONPASS {
lock
say "A staff pass for the field station."
release
}

on use hooks belong in common.pfs; an item without one says that it cannot be used here.

Items on the ground and hidden items are not a kind of their own: an item on the ground is an actor with a hide ... when FLAG rule and an on talk that calls the shared ground_item script and sets the flag; a hidden item is a spot with an on read that gives the item and sets a flag. sample/scripts/station.pfs has one of each.

start name runs a script beside everything else: a watchman’s rounds, a flickering lamp. Up to four scripts run at once, counting the foreground one. A background script does not stop the player or other events; it is stopped when the map is left. Start them from on load.

script rounds {
while STORY < 5 {
move watchman, [face_left, pause(120), face_down, pause(90)]
}
}
on load { start rounds }
What Limit
Code in one file 32,767 bytes
Text in one file 65,535 bytes
Values at once in one expression 16
call depth (procedures too) 16
Temporaries of one script 16, and 64 words with its procedures’ frames
Entries of an array 255
Text registers 8, of 64 bytes each
Saved flags 4,096 (flag(0) to flag(4095))
Saved variables 512 (var(0) to var(511))
Map-local flags and variables 64 and 32
Scripts running at once 4
Actors moving by lists at once 8
on sight events in a map 32
on steps count 1 to 65,535 steps
Entries in one movement list 255
Actors on a map (the player not counted) 63
Maps a warp, respawn or buffer ..., map can name 4,096

Not in the language: decimals, text beyond the eight text registers, data structures beyond arrays. A game that needs more adds commands in Rust (ext).