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:
cd sampleploom runFolders
Section titled “Folders”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 creditsgame.toml
Section titled “game.toml”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 settingsmap.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.
Scripts
Section titled “Scripts”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 outvar STORY = 0
flag HAS_PASS = 4flag STATION_UNLOCKED = 5The 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}Characters
Section titled “Characters”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 EVsopt_max_evs_about = On: the party gets the most effort\nvalues the rules allow, once.cur_coins = Coinsgame.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 = SproutailTypes = MOSSBaseStats = 45,50,52,44,60,58Abilities = THICKBARKMoves = 1,NUDGE,1,GLOWER,5,LEAFLASH,9,SPOREPUFF,13,NEWGROWTH,18,THORNVOLLEY,24,SAPDRINKMOSS 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 fieldLand,21 40,SPROUTAIL,2,4 30,BUDSHELL,2,41 = "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.xmmusic found_it music/found_it.xm oncesfx bump sfx/bump.wav keepMusic 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.
Connections
Section titled “Connections”| 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.