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 isscripts/common.pfs, followed by every.pfsfile ofscripts/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 writesscripts/shared/intro.pfsbeside its owncommon.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 = numberflag DOOR_UNLOCKED = 12var STORY = 0lflag WHISTLED = 0 # map-local flaglvar TRIES = 0 # map-local variableactor watchman = 2 # position in the map's actor listspot signpost = 3 # a sign or trigger spot's numbermap town = 1item TONIC = 3flag, 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.pfspl-scriptc -s game.pfsym -s shared.pfsym -o town.pfsb town.pfsWithout -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.
What a file contains
Section titled “What a file contains”| 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 |
Events
Section titled “Events”| 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 visiton enter when STORY == 3 { ... } # after something else has happenedon step area(9, 9, 3, 1) when STORY == 1 { ... } # a doorway, onceon 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.pfson steps 1 when POISONED { say "Ouch." } # a map's fileA 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}Editing hooks
Section titled “Editing hooks”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.
Values
Section titled “Values”- Numbers are whole, from about -2 billion to 2 billion:
12,0x1F,1_000. - Text is in double quotes.
\nstarts a new line,\pa new page,\rwaits 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 (seebuffer). - Flags are yes or no:
flag(0)toflag(4095)are saved;lflag(0)tolflag(63)are forgotten whenever the map is left. - Variables hold a number:
var(0)tovar(511)are saved;lvar(0)tolvar(31)are forgotten whenever the map is left;temp(0)totemp(15)belong to the running script and start at 0. A scriptcalled without brackets shares its caller’s temporaries, which is how values are passed to it; a procedure (below) has its own.let name = valuenames 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 followerkeeps it in untilshow follower),npc(n), or a name from the symbol file. - Directions:
down,left,right,up. trueis 1 andfalseis 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).
Statements
Section titled “Statements”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.
Text values
Section titled “Text values”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 namelet line = text("{0} looks happy with {1}!", who, name(item, ORAN))say lineif 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
textand eachnametakes 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 withname(number, n).
Menus a script builds
Section titled “Menus a script builds”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, withwhen conditionto 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 withVAR = command(...)there). - Up to 64 entries; more than eight scroll.
at: right(the default) orleftplaces 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], amenuitem text, value, [enabled]for each entry, andmenushow→, which may also be written by hand (an imported game does). choicestays as it was: options by place, at most 32.
Arrays
Section titled “Arrays”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 flagsarray HERE = lvar[0..8] # map-local; lflag and temp work too
SEEN[i] = SEEN[i] + 1SEEN[i] += 1set LIT[n]if LIT[n] { ... }len(SEEN) # 20, a constantfor i in SEEN { SEEN[i] = 0 }for i in 0..partycount() { ... }- The range is
from..to,tonot 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
tempis in the running script’s own frame: in a procedure, the procedure’s temporaries. forkeeps 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.
Procedures
Section titled “Procedures”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
lettakes the next free one; it is named until the end of its block ({ }), and skips any temporary the body names itself astemp(n). -> valuesays it gives a value:return exprgives it, and reaching the end (or a barereturn) gives 0. A procedure without-> valueis called as a statement,call name(args)or justname(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 nameshares the caller’s temporaries (a procedure’s, when a procedure calls it). A procedure cannot be named incall namewithout brackets, norstarted. let,value,array,for,inand the other words of the second version are words only where they are used: a script or actor already namedletkeeps working.
Commands
Section titled “Commands”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).
Dialogue
Section titled “Dialogue”| 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 |
Characters
Section titled “Characters”| 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.
Movement lists
Section titled “Movement lists”move player, [up * 3, face_left]move watchman, [speed(fast), right * 4, pause(30), emote(alert)], wait: falsemove marker, [down * 6], wait: falsewaitmovesmove 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 |
Camera
Section titled “Camera”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 loadonlyticks: 0makes 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.mdfor 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.xmmusic found_it music/found_it.xm onceA 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
playmusicof aoncetrack, 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 keepsfx confirm sfx/confirm.wav priority=2 keepsfx ice_crack sfx/ice_crack.wavReading 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).
Items, creatures, battles, screens
Section titled “Items, creatures, battles, screens”| 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) |
Rules, options and cheats
Section titled “Rules, options and cheats”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 0setrule level_cap, 20The 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 game’s own commands
Section titled “A game’s own commands”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) -> valueext stamp = 2 (kind)ext chime = 7Scripts 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.
A game’s currencies
Section titled “A game’s currencies”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.
Move services
Section titled “Move services”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 defaultWARCRY = { cost = 1, pay = "OLDCOIN" } # an item from the bagand 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.
Asking the data and the party
Section titled “Asking the data and the party”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 { ... } }Pictures
Section titled “Pictures”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 TuesdaysA 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.
What the walking program does not do yet
Section titled “What the walking program does not do yet”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.
Background scripts
Section titled “Background scripts”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 }Limits
Section titled “Limits”| 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).