Skip to content

Sample game

The sample game is the engine’s own test game and a small tutorial. Everything in it is original: its town, its story and the data of its sixteen creatures were written for it, and the creatures’ pictures come from an openly licensed sprite pack (credited in sample/graphics/creatures/CREDITS.md). Most of its maps and art are made by code (tools/pl-samplekit); a few maps are made by hand, as a creator would.

The story in one line: you wake in a locked room, slip out at night past the town’s watch, and reach a field station. It is short; its job is to use every system once.

Build and play it from the repository:

Terminal window
cd sample
ploom run
sample/
game.toml the game's settings
maps/ seven map folders, the pieces and Tiled's tilesets
scripts/ one script file a map, the shared common.pfs, sample.pfsym
text.txt the game's strings
pbs/ creature, move, item, trainer and encounter data
graphics/ characters, creatures, trainers, battle scenes, interface
audio/ music modules and sound effects, listed in audio.txt
credits.txt the ending's credits

The game’s profile. It starts with its identity and its maps:

[game]
title = "PokeLoom sample game"
# Map folders under maps/, in the order warps and scripts number them.
# The last 4 are made by hand, not by the generator.
maps = ["home", "town", "lab", "parlour", "garden", "hill", "weir"]
# The map a new game starts on.
start = "home"

The order of maps matters: it is how the engine numbers maps, and warps and scripts refer to them by those numbers. The rest of the file chooses rules and features, each group documented in the reference. Two examples:

# The day care keeps HeartGold's rules: an egg cycle of 255 steps, Power
# items and the Everstone from either parent (docs/creating-a-game.md).
[rules]
daycare = "heartgold"
# Field moves (docs/creating-a-game.md, "Field moves"): the sample's own
# moves do them, once the weir keeper's permit (flag 10) is given.
[world.field_moves]
cut = { move = "GUSTCUT", flag = 10 }
surf = { move = "UNDERTOW", flag = 10 }

Each feature is off until its table is there. The sample turns on fishing ([world.fishing]), its own warp sounds ([world.warps.panel]), music rules ([audio.music]), interface sounds ([audio.sounds]), tutors and a second currency. A game that leaves them out gets the engine’s defaults.

maps/parlour/ is a room made by hand in Tiled, a good map to read first. It has two files:

maps/parlour/
map.tmj the map, drawn in Tiled
map.toml its settings

map.toml says what kind of place it is:

name = "Moss Cottage"
kind = "indoor"
camera = "interior"
allow = []
shade = "shade.png"
# Indoors the town's music stops.
music = "none"

kind = "indoor" picks the indoor defaults, such as a constant light; camera picks the room camera; allow = [] forbids running, cycling, escaping and flying here. Every key is in the map.toml reference.

map.tmj is a 32×32-cell Tiled map with five layers:

Layer Kind What it holds
ground tiles The floor pieces
objects tiles Object pieces: walls, furniture, one a cell
height tiles Optional: each cell’s level, 0 to 31½ by half levels
behavior tiles Optional: what a cell does, overriding what its pieces give it
events objects People, warps, signs and other things scripts name

The events layer holds three objects. One is an actor named neighbour, with two properties: sprite = "townswoman" and facing = "up". Two are warps, each with to, to_x, to_y and facing: one back to the town, one through to the garden.

A map’s scripts are scripts/<map name>.pfs unless its map.toml names another file. scripts/parlour.pfs is the whole of the parlour’s:

# The neighbour's parlour (maps/parlour): a map made by hand. The actor's name
# is the one it has in Tiled.
on talk neighbour {
lock
faceplayer
say "You're the one from next door.\pThe garden's through the back, if\nyou want air."
release
}

on talk neighbour is an event: it runs when the player talks to the actor named neighbour on the map. lock stops the player and the world while it runs; release gives control back. \p starts a new paragraph of the text box, \n a new line of the same one. See Scripts and events.

Scripts every map can use live in scripts/common.pfs. Names shared by every script file, such as the story’s variables and flags, are declared in scripts/sample.pfsym:

# Story progress, saved.
# 0 asleep in the locked room 3 has been outside
# 1 the room's door is open 4 inside the field station
# 2 has seen the hall 5 has taken a creature; the watch is out
var STORY = 0
flag HAS_PASS = 4
flag STATION_UNLOCKED = 5

The town’s script uses them to change the place as the story moves:

hide dropped_pass when HAS_PASS
# Once the bells ring the watch at the crossing has run to the station.
hide crossing_watch when STORY >= 5
on load when STATION_UNLOCKED {
setcell STATION_X, STATION_Y, door
}

The actor’s sprite = "townswoman" names a sheet listed in graphics/sprites.toml:

characters = ["player", "watchman", "townswoman", "old_man", "pickup", "player_bike", "player_surf", "small_tree", "boulder", "rock", "fruit_tree", "player_fish"]

Each name is a picture, graphics/characters/townswoman.png: four rows (facing down, left, right, up) of four frames. See People and characters.

text.txt holds the game’s strings, one a line, key = text. The engine’s own keys come first, in a fixed order; a game adds its own after them:

opt_max_evs = Max EVs
opt_max_evs_about = On: the party gets the most effort\nvalues the rules allow, once.
cur_coins = Coins

game.toml uses those keys for the game’s own option row and its currency:

[ui.options]
max_evs = { label = "opt_max_evs", about = "opt_max_evs_about" }
[rules.currencies]
coins = { label = "cur_coins", max = 9999 }

The engine shows text by its key, never text built in its code, so a game’s words can all be changed without touching code. The build refuses a line wider than its box. See Text and dialogue.

pbs/ holds the creature data in Pokémon Essentials’ PBS text format: species, moves, abilities, items, types, trainers, encounters and shops. All of it is invented for the sample:

[SPROUTAIL]
Name = Sproutail
Types = MOSS
BaseStats = 45,50,52,44,60,58
Abilities = THICKBARK
Moves = 1,NUDGE,1,GLOWER,5,LEAFLASH,9,SPOREPUFF,13,NEWGROWTH,18,THORNVOLLEY,24,SAPDRINK

MOSS is a type of the sample’s own, in pbs/types.txt: nothing in the engine assumes the official types. Encounters are listed by map number, and pbs/map_ids.toml ties those numbers to map folders:

[001] # the town and its field
Land,21
40,SPROUTAIL,2,4
30,BUDSHELL,2,4
1 = "town"

Trainers live in pbs/trainers.txt; a script starts a battle against one. A game that uses real creatures instead fetches Showdown’s data with ploom fetch-data and never commits it. See Creatures, moves and data.

audio/audio.txt lists the music and sound effects by name. The position of a line among those of its kind is its number:

music town_night music/town_night.xm
music found_it music/found_it.xm once
sfx bump sfx/bump.wav keep

Music is tracker modules, which the DS plays with its own sound library. once marks a jingle; keep keeps an effect loaded at all times instead of loading it when played. game.toml refers to sounds by these names (victory = "found_it"). See Music and sound.

From Names Found in
game.toml maps a map folder maps/<name>/
A map’s events layer an actor, a sign, a spot the map’s script: on talk <name>, on read <name>
An actor’s sprite a character sheet graphics/sprites.toml, then graphics/characters/
A warp’s to a map folder maps/<name>/
A script’s say, a setting’s label quoted text or a key text.txt
A setting’s sound a sound’s name audio/audio.txt
A script’s playmusic a name declared in sample.pfsym (music NIGHT_TOWN = 0) its position in audio/audio.txt
A script’s givemon, a trainer, an encounter a species, move or item identifier pbs/
pbs/encounters.txt a map number pbs/map_ids.toml

Other map layers (encounter ground, battle grounds, bridges’ decks) are described in Maps; every file of a project in The project folder.