Skip to content

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.

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.

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 palette key of textures.toml orders a true-colour picture’s colours, and a 16-colour tileset has a palettes.png beside 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/*.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.

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.

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.

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.

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.

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