File formats
A project holds only ordinary formats that other programs open: Tiled’s JSON, OBJ
models, PNG pictures, tracker modules, WAV, TOML and plain text. None of them is read
by the game itself. ploom build converts them into one file, pack/game.pak, in
formats made for the DS: no pointers, fixed records, read in place. This split is why
a creator never needs a DS tool to change a game, and why the DS never parses text.
The build checks each file against the DS’s limits as it converts it, and a mistake names the file, the line or cell, and the fix. See The project folder for where each file sits and Limits for the numbers.
Settings files declare how the engine behaves. Each key is declared once in the engine with its type, range and default; an unknown key is an error with its line. The four main files have generated references.
| File | What it sets | Reference |
|---|---|---|
game.toml |
The game as a whole: identity, field, rules, sounds, menus, the lower screen | game.toml |
maps/<name>/map.toml |
One map: name, kind, music, camera, light, weather, battle scene, variants | map.toml |
maps/world.toml |
Maps placed side by side in one world | world.toml |
lights.toml |
The game’s own light tables, period by period | lights.toml |
ploom schema <file> --markdown prints the same references from the program.
Other TOML files hold content that is structured rather than settings. Their keys are described at the top of each file in the sample, or on the page named.
| File | What it holds | Page |
|---|---|---|
maps/pieces.toml |
The pieces maps are made of: ground pieces (a texture or a tile of one) and object pieces (a model, its footprint, its behaviour, its materials’ light) | Art |
maps/textures.toml |
Settings for textures that need any: format, repeat, glass colours, transparency, palette order, animation frames | Art |
graphics/sprites.toml |
Which pictures are the characters, the shadow, the emotes and the ground effects | Characters |
maps/<name>/headbutt.toml |
Trees on a map that can be headbutted | Encounters |
region.toml |
The region map: where places sit on it | Game systems |
layouts/<family>.toml |
A built-in menu style and every number of it (party, summary, bag, Start menu, signs) | Menus and UI styles |
tiles.toml, tilesets/<name>/tileset.toml, pieces/<name>.toml, sheets/<name>.toml |
A tile-map project: its start, its tilesets and metatiles, set pieces, character sheets | The tile-map style |
roles.toml, art/<set>/artset.toml, assets/.../assets.toml, sources.toml |
Roles, art sets, an asset’s sidecar, the project’s sources | Asset roles and style chains |
import/maps.toml, import/text.toml, import/tags.toml |
An import’s options and your corrections of asset roles | Importing games |
overlay/reskin.toml |
Pieces, textures and pictures of a source mapped to another project’s | Importing games |
In the pack: settings become fixed records the engine reads at start or when a map loads. Layout files become one directory of screen blocks, each read only when its screen opens.
Tiled JSON
Section titled “Tiled JSON”| File | Written by | What it is |
|---|---|---|
maps/<name>/map.tmj |
Tiled | The map: orthogonal, 16 × 16 pixel tiles, tile layers by name (ground, objects, height, behavior, tag, encounter, battle_ground, the _upper layers) and an events object layer |
maps/pieces.tsj |
ploom tiles |
The tileset of pieces, with a thumbnail of each in maps/pieces/thumbs/ |
maps/markers.tsj, maps/levels.tsj |
ploom tiles (markers), the sample (levels) |
Behaviour and number tiles; height levels above 15 and half levels |
Layer data must be CSV or uncompressed base64, and tilesets JSON (.tsj), not XML.
Flipped tiles, object templates, and isometric or hexagonal maps are errors that say
what to do instead; image layers, offsets, tint and animations are ignored. See
Maps for the full list.
In the pack: each map becomes an area file: its cells (32 bits each: ground, height, behaviour, tag and the rest), its pieces merged into meshes chunk by chunk (32 × 32 cells), and its events with their names turned into numbers. Maps of one world are also written into a world file that places them on one grid of chunks. A tile-map map becomes its own map format, read by the DS’s 2D engine.
OBJ and MTL
Section titled “OBJ and MTL”maps/pieces/<name>.obj with its .mtl, from any modelling program. One unit is one
cell; y is up and z is south. Faces must be triangles or quads (a quad costs half of
two triangles, so do not triangulate on export). Vertex colours are read where the
file has them. A material’s texture is the file name of its map_Kd. Normals,
smoothing groups and object names are ignored.
In the pack: a mesh of the DS’s own form, with fixed-point positions, texture positions moved to the nearest whole texel, and each material’s drawing settings (translucency, polygon ID, light). Models are merged with the ground into each chunk’s meshes so a map draws in few calls.
Every picture is a PNG. What the build does with it depends on where it lies.
| Where | What it is | Size rules |
|---|---|---|
maps/pieces/ |
Textures of ground and models | Each side 8, 16, 32, 64, 128 or 256 pixels |
maps/<name>/shade.png |
Baked shade on a map’s ground, grey from white (full light) to dark | One pixel larger than the map each way: a pixel for each cell corner |
graphics/characters/ |
Character sheets: four rows (down, left, right, up) of four frames | 128 × 128 (ploom sheet converts other layouts) |
graphics/effects/, shadow.png, emotes.png |
Footprints, splashes, grass cards; the shadow; the marks over a head | As the sample’s |
graphics/creatures/<species>/ |
front.png, back.png, icon.png, follow.png |
One frame for the whole game: 64 × 64, or 96 × 96 |
graphics/trainers/<class>/front.png, player/back.png |
Trainer pictures | At most 64 × 80 |
graphics/items/<item>.png |
Item icons, named by the item’s identifier in lower case | At most 32 × 32, 15 colours |
graphics/types/<type>.png |
Type icons | As the art specification says |
graphics/battle/scenes/<scene>/ |
A battle scene: background.png, optional night.png, near.png, far.png |
Background 256 × 192 (up to 320 wide) |
graphics/battle/platforms/<ground>/ |
The platforms of one battle ground | As the scene’s |
graphics/menus/<family>/ |
Pictures of a built-in menu style, named in its layout file | As the layout says |
graphics/ui/skin/window.png, frame_<n>.png |
The window and text-box frames laid over the skin | 24 × 24; 48 tall |
tilesets/<name>/tiles.png, pieces/<name>.png |
A tile-map project’s tilesets and set pieces | Cut into 16 × 16 metatiles |
How colours are kept:
- A PNG with a palette keeps its palette and the order of its colours. A texture takes the smallest format that holds it: 4, 16 or 256 colours. A fully transparent first colour is cut out.
- A true-colour PNG gets a palette made for it, the same every time. Above 16 colours it is reduced and the build says so; reduce it yourself to choose which colours stay.
- Partly see-through pixels make a translucent texture (32 colours, 8 levels of opacity), for water and glass.
- A palette can be given apart from the picture: the
palettekey oftextures.tomlorders a true-colour picture’s colours, and a 16-colour tileset has apalettes.pngbeside it.
ploom check --art checks every picture against the art specification and
ploom fit shows one after the DS’s colour fit. See Art.
In the pack: textures in the DS’s texture formats with their palettes; sheets and icons as tiles for sprites; battle and menu pictures fitted into the tiles and palettes a screen has (the build says when it had to bring colours or tiles down).
PBS text
Section titled “PBS text”pbs/*.txt, the text format of Pokémon Essentials v21.1: pokemon.txt,
pokemon_forms.txt, moves.txt, abilities.txt, items.txt, types.txt,
trainer_types.txt, trainers.txt, encounters.txt, shops.txt. Sections in
brackets, Key = value lines, comma lists. pbs/map_ids.toml maps the map numbers of
imported data to map names.
A project may instead, or as well, use Pokémon Showdown’s data, fetched by
ploom fetch-data into external/showdown-data/ with a lock file
showdown-data.lock. [game] data in game.toml chooses which.
PBS names an effect; it does not hold it. A move’s FunctionCode and each ability
and item map to behaviour written in the engine. ploom pack --coverage lists what
the data names and the engine does not implement. No official data is ever in the
repository; see Creatures, moves and data.
In the pack: fixed-size records (species, moves, items, trainers, encounters)
addressed by number, and the symbol file pack/game.sym that gives scripts and the
tools each name’s number.
Scripts
Section titled “Scripts”| File | What it is |
|---|---|
scripts/common.pfs |
Scripts every map can call, and the shared hooks |
scripts/<map>.pfs |
One map’s events: on talk, on read, on step and the rest |
scripts/*.pfsym |
Names for numbers, one a line: flag HAS_HAIRPIN = 1, var STORY = 0, items, species, sounds |
scripts/roles.pfsym |
The roles a story’s scripts refer to, for a game that tells another project’s story |
Names of maps, actors, signs and triggers come from the maps; everything else a script
names is declared in a .pfsym file, so a script never holds a bare number.
In the pack: compiled bytecode, one module a file (.pfsb), with every name
resolved to its number. The DS runs bytecode only, never text. See
Scripts and events and the
language reference.
text.txt holds every string the player reads, one key = text line each. The
engine’s own keys come first, in its order; a game’s own follow. text/<name>.txt
files hold more strings as banks, read when one of their strings is shown.
Control codes in a line: \n, \r, \p, {player}, {var:N}, {color:red},
{pause:N}, {wait}. A line too wide for the box is an error. credits.txt holds the
rows of the credits. See Text and dialogue.
In the pack: the strings numbered in order, text.txt first, then the banks by
file name; the engine finds its own by key, never by position.
audio/audio.txt lists the game’s sounds, one a line: kind, name, file and options.
The position of a line among lines of its kind is its number.
| Kind | File | Options |
|---|---|---|
music |
A tracker module: XM, IT, S3M or MOD | once: a jingle |
sfx |
A WAV file, played as 8-bit mono | keep: always loaded on DS; priority=N |
cry |
A WAV file named by the species’ number |
Music is tracker modules because the DS’s sound hardware plays samples on 16 channels:
a module is a few samples and a score, so a track takes kilobytes where streamed audio
would take megabytes. ploom import-midi turns a MIDI file and a list of instruments
into a module. See Music and sound.
Not in the pack: sound is the one part of a game not inside game.pak. On
desktop ploom build desktop copies audio/ beside the program; the DS’s sound bank
is made by the engine’s own build, which needs the DS toolchain. Planned (plans 13
and 26): the sound bank written without it.
Move animations
Section titled “Move animations”graphics/battle/anims.txt holds a move animation script: one command a line, a
fallback by type and category for moves without their own. See
Move animations.
In the pack: one file of compiled move animations, played the same on desktop and DS.
Copied files
Section titled “Copied files”A few binary files are made by the engine’s tools and copied into the pack unchanged, because their converters from pictures are not written yet:
| File | What it is |
|---|---|
graphics/ui/font.pff |
The interface’s font |
graphics/ui/skin.pfk |
The skin: tiles, palettes, frames, icons. Its window and frames can be overridden by pictures (above) |
graphics/battle/battlers.pfb |
A battle’s capsule, default trainer and plain scene colours. Without it they are made from capsule.png, trainer.png and colours.png |
Planned: the font and the rest of the skin converted from pictures.
Build output
Section titled “Build output”| File | What it is | Kept in version control |
|---|---|---|
pack/game.pak |
The game’s data: one file of records found by the hash of their names | No: made from the project |
pack/game.sym |
Every data name and its number | No |
.ploom/ |
The build’s memory: what each output read, so a second build converts only what changed; source images for style chains | No: safe to delete |
build/report.json, build/battle.pfext |
For a game with Rust of its own: what it changes of the engine’s battle, and its battle tables | No |
import/report.md |
What an import converted and what it could not | Your own copy only |
dist/ |
ploom build desktop’s folder: the program, data/game.pak, data/game.id, audio/ |
No |
Each binary format starts with a short magic that names its version, so the engine refuses a file it cannot read instead of misreading it. See The pack format.
Planned
Section titled “Planned”| File | What it is | Plan |
|---|---|---|
tests/*.pbt |
A game’s battle scenario tests, run by ploom test |
plan 34 |
package.toml, packages/<name>/, ploom.lock |
A package, the packages a game uses, and their pinned versions and hashes | plan 46 |
records/<name>.toml |
Saved records a game declares, kept across builds by name | plan 46 |
quests.toml, achievements.toml, portraits.toml, outfits.toml |
Data of the built-ins | plan 46 |
layouts/screens/<name>.toml with screens/<name>.pfs |
A screen of a game’s own, built from parts and driven by script | plan 46 |
gadget/gadget.toml, gadget/apps/*.toml |
A lower-screen device: its shell and its apps | plan 45 |