Skip to content

Script machine

What a creator writes is in scripts and events and the script language reference. This page is how it runs.

The DS never sees script source (plan 06, a [user] decision for compiled bytecode):

  • Size. A parser and an interpreter of text would cost code and RAM on a machine with 1.5 MB for all code. The bytecode runner is a small loop.
  • Errors at build time. Every unknown name, wrong argument count or type is reported by ploom check and ploom build with file, line and a caret, never found by a player.
  • Speed. Opcodes are one byte with fixed-layout operands; nothing is looked up by name at run time.

WebAssembly was considered and deferred: the DS interpreter that exists is unmaintained, about ten times slower than native, and allocates in 64 KB pages. The command table is the seam where such a layer could attach later. Heavier logic is a game’s Rust instead (see Rust extensions).

crates/pl-script/src/ops.rs is the single definition of the language’s numbers:

  • the opcodes (flow, stack, references, MOVE, the operators, CALLV, the indexed loads and stores);
  • the command table, written with a commands! macro: one row a command with its name, its parameters and their kinds, defaults, and whether it returns a value;
  • movement actions, built-in words, hook kinds (ops::hook), system call numbers (ops::sys).

The machine executes these numbers; pl-scriptc compiles to them by reading the same tables. The language and the runner cannot drift apart. The language reference is generated from the same table (tools/pl-scriptc/src/reference.rs), and a test refuses a command without a line of documentation.

Adding a command is appending a row. Rows are kept in order, never renumbered: a pack is always built with its runtime, so no number is stored anywhere that would need to stay stable across versions.

File Does
lexer.rs Source text to tokens
parser.rs Tokens to a syntax tree, by recursive descent. An error is recorded, the rest of the line skipped, and parsing goes on, so one run reports many errors
compile.rs The tree to a PFS1 module
symbols.rs Symbol files: kind NAME = number lines
project.rs A game’s whole scripts/ folder, as the build and live reload compile it
fake.rs A stand-in game for running scripts in tests: records every call as a line
reference.rs The generated language reference

A project’s scripts compile in two steps. The shared module (the shared file and the shared folder) compiles first; its script numbers and procedures’ arities become names the maps’ files can call. Then one module a map. Names of flags, variables, items, species, maps, sounds, strings and the rest come from the *.pfsym symbol files in scripts/ and from the names the build knows from the game’s own data (see the pack). flag, var, lflag and lvar (map-local), const and actor are usable anywhere; any other kind is a namespace a command’s argument looks in.

Compatibility is held by byte equality: when the language grew to its second version, every existing script had to compile to the same bytes (plan 30, section 4).

crates/pl-script/src/module.rs. Little-endian:

Part What
Header PFS1, counts of named scripts, hooks and strings, the code’s length
Scripts the code offset of each named script
Hooks 10 bytes each: kind, a number, a cell, a height, the code offset
Strings where each string starts in the text
Code at most 32 KB
Text UTF-8, strings back to back

The magic is the format’s only version.

crates/pl-script/src/machine.rs. Its limits are constants:

Constant Value Means
MAX_SCRIPTS 4 scripts at once: one in the foreground that locks the player, the rest in the background
BUDGET 2,000 instructions a script may run in one tick before it is made to yield
STACK 16 values on the expression stack
CALLS 16 call depth
TEMPS, FRAME 16, 64 temporaries of the outermost frame; words of a script’s frame stack for procedures
MENU_ENTRIES 64 entries of a menu a script builds

Plus one slot for an editing hook (EDIT_BUDGET, 4,000 instructions), which runs to the end inside the tick that asked for it (plan 46).

Nothing allocates. The machine is a fixed-size struct made once.

Resumable. A command that has to wait (a message, a movement, a fade, a battle) leaves the script where it is; the machine asks Host::busy on the next tick and carries on when the wait is over. That is what lets a cutscene read as straight-line code. A script that runs past its budget yields and resumes next tick, so a loop cannot freeze the game.

Deterministic. The same bytes, store and host answers give the same calls on every platform. Randomness comes from the host’s generator (Host::random), which is the game’s pl-core RNG. machine_hash.rs digests every field of the machine for the replay proof and co-op’s desync check; a field added without a line there does not compile.

store.rs: 4,096 saved flags and 512 saved variables (they are a section of the save), and map-local ones that are cleared each time a map is entered. A script’s temporaries are in the machine, not the store.

Plan 30 added, without changing the meaning of anything older:

  • procedures with parameters and a value: CALLV moves arguments into a new frame of temporaries, RETV returns a value; a version-1 call name still shares its caller’s temporaries;
  • arrays: names for ranges of existing flags and variables, read and written by the indexed opcodes; they add no storage, so saves are unchanged;
  • text values: the existing text handle, plus eight text registers a machine owns, never saved;
  • data queries into the pack’s species, move and item records, and party queries;
  • menus built by a script, entry by entry at run time.

The machine knows nothing of the game. crates/pl-script/src/host.rs is the trait the game implements:

  • questions: actor, opaque (a sight line), busy(Wait), result, random;
  • text: say, choose, close_text, the menu builder;
  • movement, actors, the camera, sounds;
  • system(call, args, modules): every command from weather on in the table is a system call, its number its place after weather. The game answers giving items, starting battles, opening shops, the clock, rules and options.

pl-game’s FieldHost (crates/pl-game/src/host.rs) implements it over the world, the text box, sound and the game systems. Tests implement it with pl-scriptc’s fake.rs. That split is why scripts can be tested on the host with no game running.

A module’s hook table says which script runs when: on load, on enter, on talk, on read, stepping on a spot, being seen, using an item, the follower, steps, game over, options, a new game, resuming, idling, and the editing hooks on wildmon, on trainerparty and on givemon. Hook numbers are given out in docs/registry.md and checked against pl_script::ops::hook by a test. A guard that evaluates to zero declines, and the next hook is tried.

Editing hooks (plan 46) run when the engine is about to make something (a wild creature, a trainer’s team, a gift): the script changes the pending record through the pend commands, within its budget, and the engine stores the result.

A command a game adds is named in scripts/ext.pfsym with its parameters: ext dig_site = 0 (x, y) -> value. Scripts write dig_site 4, 7, which compiles to ext 0, 4, 7. On the engine side an ext call becomes a system call above the table’s range.

Planned (plans 30 and 46): a game crate supplies a static table of ExtCommand rows, each a plain function over an ExtCx (flags, variables, the party, the bag, money, text registers, the game’s RNG, the log; nothing of the field’s internals), returning a value, a wait or a scene to open. ploom build writes ext.pfsym from that table. A game with no crate runs NoExt, where every ext logs and returns 0, as it does today. Imported games’ unmapped commands are written as named ext stubs a creator can fill one at a time.

Planned (plan 34): battle procedures in the script language, run synchronously inside the battle’s dispatcher for effects that data cannot express.