Skip to content

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 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 cell
behavior = "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.

  1. Make an orthogonal map with 16 × 16 pixel tiles. Any size works: the engine cuts it into chunks of 32 × 32 cells.
  2. Run ploom tiles. It writes the tilesets Tiled needs: maps/markers.tsj (behaviours and numbers) and maps/pieces.tsj (one tile a piece, with its thumbnail). Add markers.tsj first, then pieces.tsj. A map with heights above 15 or half levels adds maps/levels.tsj after them.
  3. Paint the layers below, by name.
  4. Save. ploom run shows 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 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.

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 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 check says when one does not. Its sides are cliffs.
  • A ledge (ledge_s and 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 on objects_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 with upper = true stands 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).

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.

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.

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