Script machine
What a creator writes is in scripts and events and the script language reference. This page is how it runs.
Overview
Section titled “Overview”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 checkandploom buildwith 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).
Definition
Section titled “Definition”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.
Compiler
Section titled “Compiler”| 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).
Module format
Section titled “Module format”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.
Machine
Section titled “Machine”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.
Flags and variables
Section titled “Flags and variables”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.
Language 2 in bytecode
Section titled “Language 2 in bytecode”Plan 30 added, without changing the meaning of anything older:
- procedures with parameters and a value:
CALLVmoves arguments into a new frame of temporaries,RETVreturns a value; a version-1call namestill 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 fromweatheron in the table is a system call, its number its place afterweather. 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.
Custom commands
Section titled “Custom commands”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.