Quick start
This page takes you from nothing to a running game you have changed. It assumes
ploom and the desktop program are built and on your PATH (Install).
Create a project
Section titled “Create a project”ploom new mygameploom new takes the folder to make, which must not exist or must be empty. It
prints what to do next:
mygame: a new project, "mygame" open mygame/maps/town/map.tmj in Tiled to change the town cd mygame ploom build converts it into pack/ ploom run plays it, and follows what you savedocs/creating-a-game.md describes every file.--title "My Game" sets the title; without it the folder’s name is used.
Project contents
Section titled “Project contents”A small working game: a room to start in and a town outside it.
mygame/ game.toml the title, the two maps, where a new game starts maps/ pieces.toml the pieces the maps are made of textures.toml settings for pictures that need any pieces/ placeholder models and pictures pieces.tsj, markers.tsj tilesets for Tiled, drawn from the pieces home/map.tmj, map.toml the room, and its settings town/map.tmj, map.toml the town, and its settings graphics/ sprites.toml which pictures are the characters ui/font.pff, skin.pfk the interface's font and skin scripts/ common.pfs scripts every map can call home.pfs, town.pfs one file a map text.txt the game's strings .gitignore ignores .ploom/, what the build remembersThe art is placeholder, drawn by code. Real art replaces it file by file. Every file is described in The project folder.
The whole of game.toml is five lines:
[game]title = "mygame"
# Map folders under maps/. To add a map, make its folder and list it here.maps = ["home", "town"]# The map a new game starts on, where its `start` event is.start = "home"cd mygameploom runploom run builds the project, then opens the desktop program on it. Every command
except new and import works on the project found from the current folder: the
nearest folder at or above it with a game.toml, as cargo finds Cargo.toml. From
anywhere else, name it: ploom -C mygame run.
On a keyboard, the arrows are the pad, Z is A, X is B, Enter is START and Backspace is SELECT. The mouse over the lower screen is the pen.
Live reload
Section titled “Live reload”Leave the game running. Open scripts/town.pfs:
# The town outside. `notice` is a sign and `villager` an actor on the map's# `events` layer.
on read notice { say "A new game starts here."}
on talk villager { faceplayer say "Everything you see is a placeholder.\nDraw over it!"}notice and villager are the names of objects on the town map’s events layer in
Tiled. on talk villager runs when the player presses A facing the villager. Change
the villager’s line and save the file:
on talk villager { faceplayer say "You changed me.\nThat was quick."}Talk to the villager again: the new line is there. Live reload converts what you saved and hands it to the running game. Scripts are taken in place. For a map, a piece, a picture or a map’s settings the screen fades and the map you are on comes back around you, where you stand. For 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.
Why it works this way: a script can be swapped without disturbing anything, but a changed map may move the cell you stand on, and changed strings may be on screen already. Each kind of file reloads in the smallest step that is safe for it.
\n continues a sentence on the next line of the text box. Text can also live in
text.txt under a key, say taking the key instead of the quoted line; see Text and
dialogue.
Edit a map
Section titled “Edit a map”Open maps/town/map.tmj in Tiled. The maps are made of pieces: each tile of the
pieces tileset is a 3D piece (ground, a tree, a house). Paint, save, and the running
game shows the change. After adding or changing a piece itself (in maps/pieces/ and
pieces.toml), run:
ploom tilesIt redraws the thumbnails and tilesets Tiled shows. See Maps.
ploom checkploom check converts everything and writes nothing. It reports every problem, with
the file and the place, and what each map costs against the DS’s limits (polygons,
video memory, characters). A mistake in game.toml or map.toml is reported with
its line, every mistake at once.
ploom check --artchecks every picture against the DS’s art limits (sizes, frame layout, colours,
transparency) and says how to fix each. --preview DIR writes a before-and-after
picture of each whose colours will change.
Why check at all, when ploom run already works: the desktop is far more forgiving
than the DS. A map can draw well on a desktop and be over the DS’s polygon or memory
budget. ploom check catches that before a player does.
ploom buildconverts what changed into pack/game.pak: one file with the maps, sprites, font,
text, scripts and data. The first build converts everything; after that, only what
reads a changed file. A mistake in one map does not stop the others; that map keeps
its last good version. --loose also writes each part of the pack beside it under
its own name, if you want to look at one.
ploom build desktopbuilds, then writes dist/: the desktop program named after the game, its data and
its sounds. Copy the folder to a player; it needs nothing else installed. It is for
the operating system you build on.
A DS ROM today needs the DS toolchain: cargo xtask build-nds --project mygame, from
the repository. Planned (plan 13, plan 26): ploom build nds, with no toolchain.
Next steps
Section titled “Next steps”- A tour of the sample game: a larger project, read file by file.
- Scripts and events and Maps.
- The ploom command for every command and option.