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.
Project discovery
Section titled “Project discovery”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.
Folders
Section titled “Folders”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 deleteSettings and content
Section titled “Settings and content”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 |
Readers
Section titled “Readers”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’smap.toml, its Tiled file andlights.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
.pfsymfiles. 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 withploom 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 insidegame.pakyet.
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.
Live reload
Section titled “Live reload”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.
Extra folders
Section titled “Extra folders”tiles.tomlmarks a project drawn in the tile-map style instead of 3D pieces. See The tile-map style.sources.toml,assets/andart/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.
Excluded files
Section titled “Excluded files”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.