Skip to content

Art

A game’s art is ordinary files: OBJ models, PNG pictures and a few TOML files that say how they are used. ploom build turns them into the formats the DS draws (display lists, paletted textures, 8 × 8 tiles). You never convert art by hand, but the DS’s limits shape what you draw, so this page says what the build does with each file and why.

The full contract is the art specification in the repository (docs/art-spec.md). It has two parts. The contract is what the engine accepts; breaking it is an error of ploom check or the build. The style is how to draw art that sits beside the generation-4 look; not following it is not an error. Imported games keep their own art and are held only to the contract.

A map is a grid of cells, and each cell holds pieces. maps/pieces.toml lists them, one table each. There are two kinds.

A ground piece is a 16 × 16 tile of a picture. Without tile, the piece fills its texture, and neighbouring cells with the same piece are drawn as one polygon with the picture repeated. That is what keeps a map inside the DS’s polygon limit, so use it for anything that covers an area (grass, floor, water). A piece with tile is cut from a sheet and costs one polygon a cell; use it for edges and corners.

A ground piece can also stand over a cliff. Where its cell is higher than the ground beside it, the build draws a face down to that ground with the picture face names. From the sample:

[cliff]
ground = "cliff"
[lawn_top]
ground = "lawn"
face = "cliff"

Ground pieces can be lowered (drop), turned (turn), made see-through (alpha), drawn over another piece (under) and darkened (shade). Maps shows a pond built that way.

An object piece is a model standing on the map, with a footprint whose cells take its behaviour. Again from the sample, a house whose windows light up at night:

[house_red]
model = "pieces/house_red.obj"
size = [4, 3]
behavior = "blocked"
[house_red.materials.window_lit_lamp]
light = "lamp"
[house_red.materials.shadow]
alpha = 9
id = 1

size is the footprint in cells (east, south). origin moves the model inside its footprint, door = true makes a leaf that slides open, and first = true draws a room’s shell before its furniture. The comment block at the top of the sample’s maps/pieces.toml explains every key.

After adding or changing a piece, run ploom tiles. It redraws the thumbnails Tiled shows and the tileset maps/pieces.tsj.

Models are Wavefront OBJ files with their MTL file. Blender’s default export (“Y up”, “-Z forward”) is what the engine reads.

  • One unit is one cell. x is east, y is up, z is south; the ground is y = 0.
  • Triangles and quads only. A quad stays one polygon, half the cost of two triangles, so do not triangulate on export. A face with more corners is an error.
  • Vertex colours are the shading. The DS lights imported games’ models with its hardware lights, but a piece you model is shaded by its vertex colours (v x y z r g b), which multiply the texture. Paint the dark sides dark.
  • Textures come from the MTL’s map_Kd (the file name only). Texture positions are moved to whole texels; ploom check notes one that was off by more than a hundredth.
  • Reach. A vertex must lie less than 8 cells from the model’s origin, because a DS vertex is a 16-bit fixed-point number. A model that reaches further has its origin moved to its middle (the build does this and notes it). One that is 16 cells or more across, deep or high is an error: split it.
  • Normals, smoothing groups and object names are ignored.

What the DS limits is what one screen shows, not one model. ploom check counts every view of every map; a piece over 310 polygons gets a note. The measured style is about 70 to 100 polygons for a small building, 20 to 50 for a prop and 4 for a tree. See Limits.

Pictures are PNG files. DS textures have sides that are powers of two, so each side of a texture must be 8, 16, 32, 64, 128, 256, 512 or 1,024 pixels. Sides over 256 are for imported ground; your own textures seldom need them, and video memory still holds per map. Anything else is an error that names the file and the fix.

The DS draws textures from palettes, and every picture has its own:

  • A PNG with a palette keeps it, in its order. The format is chosen by the length of the palette stored in the file: 4 entries or fewer make a 4-colour texture, up to 16 a 16-colour one, more a 256-colour one (twice the memory of 16). Its first entry is cut out when it is fully transparent in the file.
  • A true-colour PNG gets a palette made for it, the same every time. Fully opaque, it gets up to 16 colours. With pixels less than half opaque, those are cut out: 15 colours and clear. With more colours than that, the build reduces them and says so; reduce them yourself to choose which stay.
  • A true-colour PNG with partly see-through pixels becomes a translucent texture (32 colours, 8 levels of opacity), for water, glass and glows.

maps/textures.toml holds settings for the pictures that need any (format, repeat, transparent, palette, glass, frames, steps). A picture without an entry is maps/pieces/<name>.png under the rules above. From the sample:

[window_lit]
glass = ["#efad52", "#ffd67b", "#fff7ce"]
[glow]
format = "a5i3"

glass lists the colours that take a lamp’s light while the rest of the picture (a window’s frame) stays in the sun. a5i3 is the DS’s other translucent format: 8 colours, 32 levels of opacity, right for soft pools of light.

Water, flowers and flames move by swapping images. The picture holds every image one under the other, each the size of the texture, sharing one palette. From the sample:

[flowers_white]
frames = 3
steps = [[0, 17], [1, 17], [2, 17], [1, 17]]

Each step is an image and how many sixtieths of a second it shows. Without steps each image shows for 10. Every place the texture is used moves together, because the engine rewrites the texture in video memory once. That copy costs time in proportion to the texture’s size, so keep moving textures to a cell or two. A texture has at most 18 steps and a map at most 16 moving textures.

A material of a model is drawn as [<piece>.materials.<name>] says: texture, alpha (1 faint to 31 solid), id (see-through polygons of one id do not darken each other; with edge marking on, opaque ones are outlined where ids meet), both_sides, and light:

light What it does
"sun" (default) the day’s light through the periods of the day
"lamp" dark by day, lit in the evening until midnight: windows, lanterns
"constant" its own colours at every hour: signs, screens
"glow" a pool of light on the ground, drawn only while the lamps are lit

How the periods and the DS’s hardware lights work is on Lighting and weather and Lights and materials.

People on the field are flat sprites on cards. A sheet is graphics/characters/<name>.png, 128 × 128 pixels: four rows (facing down, left, right, up) of four 32 × 32 frames (stand, step, stand, other step). Sheets are named in graphics/sprites.toml. Two rules matter most:

  • No shadow in the drawing. The engine draws one under every character.
  • One height. Every standing figure is 24 rows tall, its feet on row 29; age and gender are drawn, never sized. ploom check holds a project’s own sheets to it. Sheets listed in not_people (things, creatures) are not measured.

More is on Characters. Battle pictures have their own limits, set by how many sprites the battle screen reserves:

Picture Largest File
Trainer, and the player from behind what is drawn at most 64 × 80 graphics/trainers/<class>/front.png, graphics/trainers/player/back.png
Creature front and back 96 × 96 after trimming graphics/creatures/<id>/front.png, back.png
Creature icon made smaller if over 32 × 32 graphics/creatures/<id>/icon.png

Battle pictures are reduced to 15 colours and clear. Where creature pictures come from is on Creatures and data.

ploom check --art holds every picture under graphics/ and maps/ to the contract by where it lies: sheet layout and height, battle picture sizes, texture sides, colours, transparency. Each problem comes with its file and a fix. Errors make the command fail; notes say what the build will do for you (reduce colours, fit a sheet) and how to do it yourself.

ploom check --art --preview previews

--preview writes, for every picture whose colours will change, the picture as drawn beside the picture as the DS will show it. ploom fit <in.png> <out.png> does the same for one picture.

Three converters bring art drawn for other engines into the engine’s layouts. Check that you may use a picture before you do; the repository holds none.

Command Converts
ploom sheet <in.png> <out.png> --from gba a generation-3 style overworld sheet of nine frames side by side
ploom sheet <in.png> <out.png> --from rpgmaker an Essentials or RPG Maker XP sheet (four rows of four frames), its plain background cut out
ploom sheet <in.png> <out.png> --from rpgmaker-vx a VX, MV or MZ character of three columns and four rows
ploom battle-pic <in.png> <out.png> --kind creature a plain front or back picture: trimmed, fitted under the limit, 15 colours and clear (--kind trainer for trainers)

A converted figure keeps its size, so a figure taller than 24 rows still fails the one-height check: redraw or scale it. Every subcommand is listed on the command reference.

Planned (plan 40): models, sheets, maps and sounds in standard formats (glTF, LDtk, MIDI and others) read as asset sources, tagged by role and picked into a project like an imported game’s assets. See Asset roles and style chains.