Maps
A map is a grid of cells. Each cell holds pieces: a ground piece (a 16 × 16 tile of a picture, the floor) and at most one object piece (a model: a tree, a fence, a house). The engine draws the pieces in 3D and walks characters from cell to cell. This is how the DS games build their fields, and it keeps maps cheap: a cell is a few bytes, and a run of the same ground is drawn as one polygon.
Maps are drawn in Tiled, a free map editor, and saved as
its JSON format: maps/<name>/map.tmj. Tiled shows each piece as a flat thumbnail;
the game shows the model. A map’s other settings (name, music, camera, light) are in
its map.toml: see Map settings.
Pieces
Section titled “Pieces”Pieces are listed in maps/pieces.toml, one [name] each. Two from the sample:
[boards]ground = "boards" # a ground piece: the texture maps/pieces/boards.png
[wallpaper]model = "pieces/wallpaper.obj"size = [0, 0] # footprint in cells; [0, 0] takes no cellbehavior = "walk"origin = [-1.5, -1]A ground piece without a tile fills its texture, and neighbouring cells of the same
piece merge into one polygon with the picture repeated. Use that for anything that
covers an area (grass, floor, water); it is what keeps a map inside the DS’s polygon
limit. Ground pieces can also sit lower or higher than their cell, slope, be
see-through and lie over another piece (water over a pond bed), and can name a cliff
face. Models, materials and the art limits are on Art.
- Make an orthogonal map with 16 × 16 pixel tiles. Any size works: the engine cuts it into chunks of 32 × 32 cells.
- Run
ploom tiles. It writes the tilesets Tiled needs:maps/markers.tsj(behaviours and numbers) andmaps/pieces.tsj(one tile a piece, with its thumbnail). Addmarkers.tsjfirst, thenpieces.tsj. A map with heights above 15 or half levels addsmaps/levels.tsjafter them. - Paint the layers below, by name.
- Save.
ploom runshows the change at once.
Run ploom tiles again whenever pieces.toml, a model or a picture changes. Pieces
keep their tile numbers, so maps already drawn stay right.
Layers
Section titled “Layers”Layers are found by name, whatever their capitals, also inside group layers.
| Layer | What goes on it |
|---|---|
ground |
A ground piece on every cell that can be stood on. A cell without ground is blocked. |
objects |
Object pieces, one a cell. A piece is placed by the south-west cell of its footprint, so its thumbnail covers the cells it stands on. |
height |
Optional. The cell’s level, 0 to 31½ in half levels. A level is one cell high. |
behavior |
Optional. A behaviour tile: overrides what the pieces make the cell (water, ledge_s, stairs, sand, contact …). |
tag |
Optional. A number from 0 to 255 that scripts can test. |
encounter |
Optional. Marks ground where wild creatures appear whatever its behaviour (a cave floor). grass needs no mark. |
battle_ground |
Optional. The battle platforms of a battle begun on the cell. |
height_upper, objects_upper, behavior_upper |
Optional. A second floor over the cell: a bridge’s deck, its model, and what the deck is to walk on. |
events |
Objects, not tiles: people, signs, triggers, warps, camera zones, the start. |
The list of behaviours (walking surfaces, ledges, ramps, water, cells for field moves) is in Art with the pieces that set them. The behaviours that leave footprints and splashes are on Characters.
Events
Section titled “Events”Draw a rectangle (hold Ctrl to snap to the grid) or a point on the events layer,
then set its class and its custom properties.
| Class | What it is | Main properties |
|---|---|---|
actor |
A character | sprite, facing, mover, param; obstacle for a tree or rock a field move clears |
sign |
Something to read | read_facing, walk_into |
trigger |
Cells that run a script when stepped on | id |
warp |
A door, a stair, a hole, a panel | to, to_x, to_y, facing, kind, enter |
start |
Where a new game begins | facing |
camera |
A part of the map with its own camera framing | pitch, distance, fov, blend … |
Give an actor, a sign or a trigger a name in Tiled and the map’s script can use
it. The sample’s garden has an actor named gardener with sprite = "old_man" and
mover = "look", and a sign named garden_sign; its script answers them with
on talk gardener { ... } and on read garden_sign { ... }. Names must be unique
across all maps, or declared in a .pfsym file. See
Scripts and events.
People are described on Characters, warps on The joined world and camera zones on Cameras.
A map holds at most 63 people besides the player; ploom check says when one has
more. Hide the ones a scene does not need yet (hide, then show) rather than
splitting a crowded town.
Heights
Section titled “Heights”Heights are drawn on the height layer, cell by cell, in half levels from 0 to 31½.
One rule decides where a character can step: a step joins two cells whose facing
edges are at the same height. Two flat cells at the same level join; a cliff stops a
step by itself; nothing else needs marking. The sample’s hill map, through the
garden’s gate, has each case below.
- A hill. Paint its cells a level or two up, with a ground piece that names a
cliff
face. The engine draws the faces down to the lower ground on the hill’s south, east and west sides. (The camera looks north, so a face looking north is never seen and never drawn.) - A ramp. Cells of
ramp_n(or_s,_e,_w) climb as one walks that way, from the cell’s own level at its low edge to the level of the cell it points at. Paint each ramp cell at the level of its foot. A ramp climbs half a level or one level a cell;ploom checksays when one does not. Its sides are cliffs. - A ledge (
ledge_sand the others) is a one-way hop over its cell, from any height to any lower one. - A bridge. Give the deck’s cells a level on
height_upper, put the bridge’s model onobjects_upper, and leave the ground under it as it is. A character on the path walks under the deck and one on the hill walks over it, each on its own floor. An actor withupper = truestands on the deck.
Limits: levels 0 to 31½, two floors a cell, and the ground of one 8 × 8 block of cells
may span about 15 levels (ploom check names a block that spans more).
Stairs
Section titled “Stairs”A warp on a cell whose behaviour is stairs, with no door on it, is a stair to
another map: a slow step, then a slow fade. Give it enter, the one direction that
steps onto it, so the flight cannot be climbed from the side. Its to_x and to_y
are the cell beside the other floor’s stair where the player arrives. Do the same on
the other map, pointing back, and the stairs work both ways. Give the stair cell the
level the character should stand at on it: a level up for a flight that rises, one
below the floor for a well that goes down.
Occlusion
Section titled “Occlusion”A character is an upright card standing at the middle of its cell, and it is drawn into the picture’s depth like any model. So whatever a model puts between a card and the camera hides the part of the figure behind it, on the DS and on desktop alike. There is no setting: to hide someone’s legs, model the thing that hides them, in front of them and tall enough.
- A counter or a fence on the cell south of someone hides their lower part.
- Stairs need a solid rail on the near side, high enough to cover the legs.
- Tall grass is done for you: a card of blades stands in front of the legs of anyone
in
grass. - A cut-out (a balustrade drawn with gaps) hides only with its drawn pixels.
- A card is two cells wide: keep a tall rail short of the cells people stand on beside it, or it cuts the side of the figure.
How tall a rail must be depends on the camera: a lower camera sees more of a figure
over a rail of the same height, and something low and far in front hides nothing.
A figure is 24 pixels tall at every framing, its legs at most the lowest 3.
ploom check does not judge what is hidden, so look at the result in the game.
Tiled support
Section titled “Tiled support”Read: orthogonal maps; fixed-size and infinite maps (an infinite map must not have
cells before 0, 0); tile layers as CSV or uncompressed base64; object layers with
rectangles, points and tile objects; group layers; tilesets in their own .tsj file
or embedded; custom properties of tiles, objects and the map; class or type, as
either version of Tiled writes it.
Refused with an error that says what to do: compressed layer data (set Tile Layer
Format to CSV), tilesets saved as .tsx (save them as .tsj), object templates
(detach the object), isometric and hexagonal maps. Flipped and rotated tiles are an
error on the piece layers: pieces cannot be turned that way yet.
Ignored: image layers, layer offsets, opacity, tint, parallax, animations, Wang sets, text objects. Polygons and ellipses count as the cell their middle is on.
Planned
Section titled “Planned”Planned (plan 20): paths, a graph of straight and curved segments with a width, for streets and bridges that curve. A character on a path moves by the same rules (steps, facing, collision) and is drawn along the curve; warps and signs can sit on it. Grid maps are untouched. The plan is parked.
Planned (plan 20): room templates, so that several interiors share one room’s ground and pieces and add their own people and scripts.
Planned (plan 25): moving map parts (rotating gates, lifts with heights that change at run time, rides on rails) and forced movement cells (currents, spinners, arrows, cracked floors) as general features. Ice is built.