Skip to content

Game systems

Each system below is data and scripts. The engine owns the screens, the rules and the saved state; a game chooses settings in game.toml and decides with scripts when each system appears and what it costs. Every key is in the game.toml reference and every command in the script language reference.

A game’s saves live in a folder named by [game] id, apart from every other game’s. Do not change the id once players have saves.

[game]
title = "My Game"
id = "my-game"

The save is written in sections: a head, a table of sections, then each section with its own checksum. Two copies are written in turn, so a power cut during a save leaves the other copy whole. A copy may be up to 256 KB, so two fill the 512 KB flash chip of a generation-4 or generation-5 cartridge. A section is as long as what it holds, so a game with few boxes has a small save.

Why sections: a new system adds a section without moving the others, and a damaged copy is reported by the section that failed. Maps are saved by name, so adding a map or reordering maps does not send an old save to the wrong place.

Scripts save with save (1 when it worked; the engine tells the player why when not) or endgame, which saves and returns to the title.

Planned (plan 46): several save slots ([save] slots), with a summary of each on the title’s Continue. Planned (plan 44): autosave on map change or every few minutes of play.

The game clock is the platform’s (the DS’s clock, the computer’s), read when the game starts and counted on in ticks, so a recorded session replays with the clock it was recorded with. Scripts read it with hour, minute, weekday, day, month and year. The parts of the day drive the light (see Lighting and weather), wild tables and evolutions.

[time] names runs of saved flags and variables that start again each day or each week, for a once-a-day gift or a weekly event:

[time]
daily_flags = [100, 131]
weekly_flags = [132, 139]
clock_changed = "penalty"

A clock turned back more than an hour holds new days back for penalty_hours (24 by default), and clockchanged is 1 meanwhile so a script can say so. "ignore" makes every change of date a new day. on steps n runs a script every n steps of the whole game: the counter behind eggs and friendship.

Planned (plan 44): a day of 24, 60 or 120 minutes of play instead of the real clock.

The player walks, cycles, surfs and dives, and ten field moves clear the way: cut, surf, strength, rocksmash, waterfall, rockclimb, defog, flash, fly and dive. A game says which move or item does each and which saved flag (a badge, a permit) it needs. The sample’s:

[world.field_moves]
cut = { move = "GUSTCUT", flag = 10 }
surf = { move = "UNDERTOW", flag = 10 }
strength = { move = "BRACE", flag = 10 }
rocksmash = { move = "BREAKER", flag = 10 }
fly = { move = "UPDRAFT", flag = 10 }

On the map, a small tree is an actor with obstacle = "cut", a rock "smash", a boulder "boulder"; water, waterfalls, rock walls, cycling paths and deep water are cell behaviours; a dark map says dark = true in its map.toml. A for the obstacle, or the move chosen on the party screen, runs the shared on fieldmove KIND hook:

on fieldmove cut {
lock
if canuse(cut) < 0 {
say "A small tree. A sharp move\ncould cut it down."
} else {
say "A small tree. {0} could\ncut it down with {1}."
if yesno("Cut it down?") {
say "{0} used {1}!"
closetext
fieldmove cut
}
}
release
}

canuse finds who can (their name in buffer 0, the move’s in buffer 1); fieldmove does it. fieldmove bike gets on or off the bicycle, and travel says how the player is moving. The player’s sheets for each way are named in graphics/sprites.toml. The sample’s weir has a tree, a boulder, a rock, a boardwalk and a pool.

Planned (plan 34): field moves of a game’s own, beside the ten.

A species evolves by the Evolution lines of pbs/pokemon.txt, in Essentials’ words:

Evolution = THORNTAIL,Level,16

Every method of Essentials v21.1 runs (decision 152), each checked at its moment: after a battle for those that levelled (level, time of day, weather, held item, friendship, moves known, party, place), when an item is used from the bag, on a script’s trade (trademon), and on a script’s event (evolveevent n). An Everstone stops all but an item’s. B stops an evolution after a battle, not one an item or a trade caused. Not reachable yet: Beauty, since nothing raises a creature’s beauty.

A keeper minds two of the player’s creatures; when they get on, an egg is found now and then, and an egg in the party hatches as the player walks. The rules are one game’s, chosen with daycare in [rules]: "emerald", "platinum", "heartgold", "black2" or "modern" (the default), each read from that game’s code. They differ in egg timing, inheritance, the egg’s level and the shiny bonus. The sample keeps HeartGold’s:

[rules]
daycare = "heartgold"

The script owns the conversation and the fee. From the sample’s weir:

on load {
yard yard_a, 0
yard yard_b, 1
}
on talk daycare_lady {
lock
faceplayer
if daycare(egg) {
if yesno("There you are! We found an\nEgg in the yard. Want it?") {
daycareegg
}
release
end
}
...
}

daycaregive, daycaretake and daycareegg move creatures; daycare(count), daycare(compat) and daycare(fee, n) ask. yard makes an actor show a lodger by its follow sheet. A hatching plays on the field once nothing else has it. Not built yet: a nickname asked for on hatching. Planned (plan 46): an on egg hook to change the egg before it is made.

A relearner, move tutors, a move deleter and a name rater are people whose scripts open the engine’s screens. A script picks the creature with choosemon, asks whether the service applies (teachable, movecount, rateable), and opens teach, forgetmove or namemon. A tutor’s list and prices are data, paid in money, a currency or an item:

[rules.tutors.cove.moves]
BRACE = { cost = 3, pay = "coins" }
BARGE = { cost = 400 }
WARCRY = { cost = 1, pay = "OLDCOIN" }

The relearner’s price is the script’s: the sample’s takes an Old Coin after a lesson. keep_field_moves = true is the older games’ rule: a field move stays until the deleter takes it. The sample’s four keepers at the weir show each service.

The menu’s Map entry shows the region: a picture, a cursor naming the place under it, the player’s mark, and places not yet visited as silhouettes. Most of it is worked out from the maps; region.toml at the project’s root says where the first ones go:

name = "Selvage"
grid = [32, 22]
style = "slate"
[maps.town]
at = [6, 6]
about = "A small town."

The build places maps joined by edges or warps, and notes every map it could not place. A painted picture can replace or lie over the drawn map. The entry appears once a script says menuentry map. The fly move opens the same map: a visited place with a fly cell can be chosen.

Planned (plan 21): zoom, scrolling for regions larger than a screen, labels on the map, and places revealed by a story flag.

Three screens a game gives the player when its story says, one line each: menuentry journal, menuentry dex, menuentry card. The journal writes itself as the player travels; journalnote adds a line. See Menus and UI.

The ending is a script of the game’s own, built from four commands, so each game orders the steps as it likes. The sample’s, in scripts/common.pfs:

script finish_story {
lock
healparty
halloffame
fade out, black, 20
playmusic NIGHT_TOWN
fade in, black, 20
credits
fademusic 30
fade out, black, 30
set STORY_FINISHED
STORY = 0
warp home, 10, 6, down
}

halloffame enters the party and shows it. The record keeps the newest [hall] limit teams (50 at most) and counts every team ever entered; hallview opens the viewer, for a PC. credits shows credits.txt, a small file of rows:

style scroll
speed 2
skip repeat
title Garden Row
text a small game for PokeLoom
gap 14
title The team
mon 1
mon 2

mon N shows the N-th creature of the team entered last. A line --- starts a second part, shown by credits 1.

A run where a creature that faints is lost, with optional first-meeting and game-over rules, is a setting and a script switch. See Rules, options and cheats.