Skip to content

Tile-map style

The engine draws the field in one of two styles. The 3D style builds the world from pieces and models, as the DS games do (Maps). The tile-map style builds it from small square tiles on flat layers, as the GBA games do. Both run the same scripts, battles, menus, saves and party; a script cannot tell which style its map is drawn in.

A GBA-style world is not a 3D world seen from above. Its look comes from tiles: every building, tree and ledge is a pattern of 8 × 8 squares, and characters walk between layers rather than in front of models. Drawing that with polygons would cost most of the DS’s polygon budget and could never match a GBA picture exactly.

The DS’s 2D engine, on the other hand, works the way the GBA’s does: the same tile format, the same map entries, palettes of 16 colours, layer priorities and sprite rules. So the tile style draws with the 2D engine on the top screen. Scrolling is three registers; characters go over or under a layer by priority, for free. The desktop draws the same 2D picture pixel for pixel, and the whole 3D engine is left free. How those GBA worlds are put together is on GBA tile worlds.

Part What it is
Tile 8 × 8 pixels, the unit of video memory
Metatile 16 × 16 pixels: eight tile entries, four below and four above. One cell of the map
Tileset a primary set and a secondary set of up to 512 metatiles each; a map uses one of each
Layers bottom and middle under characters, top over them; one more for the talk box and questions
Characters sprites between the layers; lower on the screen is in front
Cell a metatile, a collision value and an elevation (levels, stairs that join levels, and bridges with two floors)

Each metatile says which layers its two halves go on, and so whether a character walks in front of it or behind it: a treetop or a roof’s edge is drawn over characters, a rock on the ground under them. A 16-colour (GBA) metatile says it as its layer type; a picture tileset’s metatile as its kind (below).

The world’s logic runs at 30 steps a second as in the 3D style. The tile view draws at 60, placing characters and the camera half a step on between world frames, which gives the GBA’s one and two pixels a frame exactly.

A tile-map project is a folder with tiles.toml. With a game.toml beside it, it is built as a whole game (data, pictures, sound, title, menus) and its tile maps are added to the same pack. The folders:

Path What
tiles.toml the start map and cell, the player’s sheet, [world] picture, [ui.bottom]
tilesets/<name>/ a tileset: tileset.toml and tiles.png, plus palettes.png and metatiles.json for a 16-colour set
maps/<name>/map.toml style = "tiles", the two tilesets, the border, connections, weather, a meter
maps/<name>/map.tmj Tiled: a blocks layer (a metatile a cell), a permissions layer (collision and elevation), objects
pieces/<name>.png a set piece and its pieces/<name>.toml
sheets/<name>.png a character’s frames, with an optional sheets/<name>.toml

The keys of a tile map’s map.toml and of tiles.toml are read by the tile build and are not yet in the generated map settings reference. The examples on this page are from the tile showcase, an original project written by pl-assets tile-showcase <folder>: a snowy camp with a temple, tents, a frozen lake, a campfire and a hovering spirit. ploom build makes its pack and pl-desktop --program tiles --data <folder>/pack plays it.

tiles.toml
start = "camp"
x = 14
y = 10
player = "hero"

A 16-colour tileset is the GBA’s own: indexed 8 × 8 tiles in tiles.png, rows of 16 colours in palettes.png, and metatiles.json listing each metatile’s eight tile entries (tile, palette, flips), its layer kind and its behaviour. This is what an imported GBA game gets, and it is exact: the pixels are the original’s.

A picture tileset is for drawing in any image editor. tiles.png is any PNG, RGBA or indexed, with as many colours as you like; colors = 256 in tileset.toml tells the build to cut it into 16 × 16 metatiles, row by row. Metatile n is Tiled’s tile n of that picture, so Tiled can use the picture itself as its tileset.

tilesets/snow/tileset.toml
colors = 256
primary = true
ground = 0
metatiles = [
{ cells = [2], behavior = "water", reflective = true },
{ cells = [3], kind = "mid", on = 2, reflective = true },
{ cells = [4, 6, 7, 8, 9], kind = "mid", behavior = "blocked" },
{ cells = [5], kind = "over" },
]
anims = [{ metatile = 7, every = 10, frames = ["anim/fire1.png", "anim/fire2.png"] }]

cells names metatiles by number. kind is plain (the default: on the middle layer), mid (under characters, over its ground) or over (over characters); on is the metatile drawn under a mid or over one (the set’s ground without it). An animated metatile’s picture is its first frame; each frame file is 16 × 16 and shows for every ticks.

256-colour tiles use the DS’s extended palettes: each layer may have 16 palettes of 256 colours, where the GBA had 16 palettes of 16 for everything. While a tile map is on the top screen, the engine lends the 3D engine’s video memory banks to the 2D engine to hold them, which is possible only because this style draws no 3D. The build gives each picture a palette of up to 255 colours and clear, and merges pictures whose colours fit together.

A set piece is a picture far bigger than a cell: a temple, a tent, a wrecked ship. It is pieces/<name>.png, any size, with a TOML file beside it:

pieces/tent.toml
over = 1 # rows of cells from the top drawn over characters
solid = 3 # rows from the bottom that block

open = [[x, y], ...] leaves cells of the solid rows walkable, for a doorway. Place a set piece in Tiled with an object of type piece, its property piece naming the picture, its top-left corner on a cell. The build cuts it into tiles, stands it on the ground under each cell it covers (so one tent can stand on snow, grass or sand), and stores repeated tiles once, flipped either way too. It costs nothing at run time: the piece is part of the layers.

  • Reflections. A character standing above a reflective metatile shows its frame upside down beneath it, translucent, under the middle layer, so ground on the middle layer clips the reflection at the water’s edge. It reuses the character’s tiles.
  • Shadows. shadow = true in sheets/<name>.toml draws a small translucent ellipse at the character’s feet.
  • Hovering. hover = 8 draws the character that many pixels up, bobbing, over its shadow on the ground. The showcase’s spirit has frame = [16, 16] and hover = 8.

A tile map’s map.toml may name a weather (any kind the 3D style has; its particles fall over the map) and a meter, a bar with a label at the top right of the screen:

maps/camp/map.toml
style = "tiles"
tilesets = ["snow", "camp"]
border = [[0, 0], [0, 0]]
weather = "snow"
meter = { label = "Warmth", start = 100, max = 100, drain = 12 }

Given as data, the meter loses a point every drain ticks. A script shows its own and takes it down:

meter "Oxygen", 40, 100
meterhide

border is the 2 × 2 metatiles repeated outside the map, always impassable, as on the GBA. [connections] joins a map to its neighbours so you walk from one onto the next.

The build de-duplicates tiles and fails, naming the picture and the fix, past a hard limit. ploom check --art prints each map’s numbers:

note: maps/camp/map.tmj: maps/camp: 190 of 1024 tiles; one view shows at most 178 (from cell 2, 0); 2 of 16 palettes; metatiles 10 and 61 of 512 each; sprites in the busiest view 50 of 128
Limit Value Why
Different tiles a map 1,024 (512 a tileset) the tile memory the top screen’s layers read
Palettes a map 16, of 255 colours and clear the DS’s extended palettes for a layer
Metatiles 512 a set, a primary and a secondary the cell’s 10-bit metatile number
Sprites a screen 128 the DS’s sprite table: characters, reflections, shadows, weather, the meter

Planned (plan 37): a tile cache that gives tiles in view a slot as the camera moves, so a map may hold any number of different tiles and only one view must fit; set pieces as large 256-colour sprites, for pieces that move or fade; palette effects on extended palettes (the hour’s tint, fades, shimmering water); followers in the tile field.

The field fills the 256 × 192 top screen by default. [world] picture makes it smaller, centred with a black border, with the talk box, questions and Start menu kept inside it, as a GBA game’s 240 × 160:

[world]
picture = [240, 160]

Both sides must be whole tiles. The lower screen of a tile game is the 3D field’s panel, set by [ui.bottom]: the skin’s picture, the menu as touch buttons, a map page with the player’s square (nav) and the party at a glance (party). Every key is in the settings reference and on Gadgets and the lower screen.

Planned (plan 35): the Game Boy’s picture is a mode of the tile style, not a third renderer. Its 8 × 8 tiles of four shades, its colour attributes and its single background map onto the DS’s 2D engine: a 160 × 144 view inside the top screen with a border picture around it, a second layer for sprites half hidden in grass, and a palette model a game chooses (four grey or green shades, palettes per screen, colour palettes, or palette sets by the hour). The importer converts; the runtime draws as it does for any tile map.