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.
Overview
Section titled “Overview”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.
Drawing
Section titled “Drawing”| 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.
Project
Section titled “Project”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.
start = "camp"x = 14y = 10player = "hero"Tilesets
Section titled “Tilesets”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.
colors = 256primary = trueground = 0metatiles = [ { 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.
Set pieces
Section titled “Set pieces”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:
over = 1 # rows of cells from the top drawn over characterssolid = 3 # rows from the bottom that blockopen = [[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 and shadows
Section titled “Reflections and shadows”- Reflections. A character standing above a
reflectivemetatile 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 = trueinsheets/<name>.tomldraws a small translucent ellipse at the character’s feet. - Hovering.
hover = 8draws the character that many pixels up, bobbing, over its shadow on the ground. The showcase’s spirit hasframe = [16, 16]andhover = 8.
Weather
Section titled “Weather”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:
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, 100meterhideborder 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.
Limits
Section titled “Limits”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.
Lower screen
Section titled “Lower screen”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.
Game Boy
Section titled “Game Boy”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.