Skip to content

Project layout

A game is a folder of ordinary files. Maps are drawn in Tiled, models are OBJ files, pictures are PNG files, and everything else is text. ploom build turns the folder into one file, pack/game.pak, which the engine loads on every platform. Nothing in the folder is compiled by hand, and you need no Rust to change any of it.

The folder is plain files for three reasons. They work with version control, so a team can see what changed. Any editor can open them. And the build can check every one of them at once and say exactly which line is wrong.

Every ploom command except ploom new and ploom import works on the project found from the current folder: the nearest folder at or above it that holds a game.toml, the way cargo finds Cargo.toml. -C <dir> names another project from anywhere: ploom -C mygame build. See the command reference.

This is the sample game’s folder (sample/ in the repository), with the files a larger game adds marked.

sample/
game.toml the game's settings: title, maps, rules, sounds
lights.toml optional: the game's own light tables
region.toml optional: the region map
credits.txt optional: what the credits show
text.txt the game's strings, key = text
text/ optional: more strings, one bank a file
maps/
pieces.toml the pieces maps are made of
textures.toml settings for pictures that need any
pieces/ models (.obj, .mtl) and pictures (.png) of pieces
pieces.tsj tilesets for Tiled, written by `ploom tiles`
markers.tsj, levels.tsj
world.toml optional: maps joined into one world
town/
map.tmj the map, drawn in Tiled
map.toml the map's settings
shade.png optional: baked shade on the ground
headbutt.toml optional: trees that can be headbutted
graphics/
sprites.toml which pictures are the characters
shadow.png, emotes.png
characters/ one sheet a character
effects/ footprints, splashes, grass cards
creatures/ one folder a species: front, back, icon, follow
trainers/ trainer pictures
items/ item icons
battle/ scenes, platforms, move animations (anims.txt)
ui/ the font, the skin, type icons
menus/ optional: pictures of built-in menu styles
layouts/ optional: built-in menu styles and their numbers
scripts/
common.pfs scripts every map can call
town.pfs ... one file a map
sample.pfsym names of flags, variables and the rest
audio/
audio.txt the game's music and sounds, by name
music/, sfx/ tracker modules and samples
pbs/ creature, move, item and trainer data
pack/game.pak written by `ploom build`; never edited
.ploom/ the build's memory; safe to delete

The files fall into two kinds, and the difference matters when something goes wrong.

Settings say how the engine behaves for this game. Every key of them is declared once in the engine, with its type, range and default, and a key the engine does not know is an error. The build reports every mistake in a settings file at once, each with its line.

File What it sets Page Reference
game.toml The game as a whole: its identity, field, rules, sounds, menus Game settings game.toml
maps/<name>/map.toml One map: its name, kind, music, camera, light Map settings map.toml
maps/world.toml Which maps lie side by side in one world The joined world world.toml
lights.toml The light of each period of the day Light and weather lights.toml
layouts/ The numbers of built-in menu styles Menus the comments in each file

Content is what the game shows and says: maps, pieces, pictures, text, scripts, data and sound. Content is converted, and the converter checks it against the DS’s limits (polygons, colours, video memory), but its form is free.

Folder or file What it holds Page
maps/ Pieces and the maps drawn from them Maps
graphics/ Characters, creatures, trainers, battle scenes, the interface Characters, Art
scripts/ Event scripts (.pfs) and their names (.pfsym) Scripts and events
text.txt, text/ Every string the player reads Text
pbs/ Creature, move, ability, item and trainer data Creatures and data
audio/ Music and sound effects Audio

ploom build sorts the folder into units and converts each unit only when one of its files changed. Each output remembers the files it read (in .ploom/), so a second build is quick. A mistake in one map does not stop the others: that map keeps its last good file and the error is printed.

  • Maps are read with maps/pieces.toml, the map’s map.toml, its Tiled file and lights.toml. A map folder holds one map; its name is the folder’s name, and that name is how warps, scripts and saves refer to it.
  • Scripts are compiled with the names the maps give (actors, signs, triggers) and the names declared in .pfsym files. A script file that no map runs is noted.
  • Text is checked line by line against the width of the box that shows it.
  • Data in pbs/ (or data fetched with ploom fetch-data) becomes the game’s creatures, moves and items. No official data is kept in the repository; see Creatures and data.
  • Sound is listed by name in audio/audio.txt. Music and sound files are built by the engine’s own build and are the one part of a game that is not inside game.pak yet.

ploom build --loose also writes each converted file beside the pack under its own name, if you want to look at one. The game does not need them.

ploom run watches the folder. Save a map in Tiled, a model, a picture, the text or a script, and the running game takes the change:

  • A script is replaced in place.
  • A map, a piece, a picture or a map’s settings: the screen fades and the map arrives again around the player, who stays where they stood.
  • The text, the font or the skin: the game starts again from its beginning.

A file that does not convert is reported in the terminal, and the game carries on with what it had.

  • tiles.toml marks a project drawn in the tile-map style instead of 3D pieces. See The tile-map style.
  • sources.toml, assets/ and art/ hold art taken from other projects and imports, sorted by role. See Assets and style chains.
  • overlay/ holds the changes a copy of another project makes to it (ploom sync). See Importing games.

Planned (plan 46): packages/<name>/ holds a package added with ploom add: a folder shaped like a project (scripts, text, maps, data) with a package.toml, copied into the project and locked to a version. See Packages.

Planned (plan 46): a game’s own Rust crate in the project, for what scripts cannot do. See Rust extensions.

pack/ and .ploom/ are made by the build and are not checked in. Imported games and anything taken from a commercial game stay out of a public repository: the importer writes them into your own copy only. See Building and shipping for what you may ship.