Skip to content

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).

Terminal window
ploom new mygame

ploom 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 save
docs/creating-a-game.md describes every file.

--title "My Game" sets the title; without it the folder’s name is used.

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 remembers

The 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"
Terminal window
cd mygame
ploom run

ploom 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.

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.

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:

Terminal window
ploom tiles

It redraws the thumbnails and tilesets Tiled shows. See Maps.

Terminal window
ploom check

ploom 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.

Terminal window
ploom check --art

checks 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.

Terminal window
ploom build

converts 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.

Terminal window
ploom build desktop

builds, 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.