Skip to content

Asset roles

Most maps name concrete art: a 3D map names pieces, a tile map names metatiles. To give a game another look you would have to replace each piece by hand. Roles put a shared vocabulary between the maps and the art: a map says what stands on a cell (a small tree, tall grass, a house), an art set says how one style draws it, and ploom build joins the two. Changing a game’s look is then choosing another art set, not converting trees one by one.

A role names a kind of thing in the world, in the engine’s own words. It carries a kind, a default behaviour, a usual footprint and a parent, and says nothing about how it looks. The engine’s vocabulary is tools/pl-assets/roles.toml; a project’s own roles.toml adds roles or replaces entries.

[tree]
kind = "object"
behavior = "blocked"
fill = true
parent = "bush"
[tree.small]
[tree.big]
footprint = [2, 2]
[house]
kind = "object"
behavior = "blocked"
footprint = [4, 3]
door = true
parent = "building"
[house.small]
[house.big]
footprint = [6, 4]
  • Names are dotted. The part before the last dot is the parent unless parent says otherwise. A request for tree.big that no art set draws falls back to tree, then bush.
  • Kinds. ground is one a cell, under everything; object stands on cells, may cover several and may have a door.
  • Behaviour is only a default. A map’s own behaviour layer always wins, and an import always writes one, so walking, encounters and ledges are the original’s whatever art is chosen.
  • Fill. A larger placement of a role with fill = true (a row of trees, a fence) is filled with copies; one without it (a house) takes one model, fitted.

A role map places roles instead of pieces: a tile layer roles (one ground role a cell) and an object layer role_objects (one rectangle a placement, its class the role, its door cell given). The map’s ordinary ground and objects layers still work and win where they are set: concrete art is an override. Imports write role layers for every map.

An art set is art/<set>/artset.toml: for each role, the pieces (3D style) or metatiles (tile style) that draw it. Your own art set is art/artset.toml and always comes first. An example, with invented piece names:

style = "grid3d"
[roles.grass.short]
ground = "meadow" # a ground piece of maps/pieces.toml
[roles.tree.small]
piece = "oak" # an object piece
footprint = [2, 2]
place = [1, 0] # where in the footprint the piece is put
[roles.house.small]
piece = "cottage"
footprint = [5, 4]
place = [2, 1]
door = [2, 3] # the door cell inside the footprint
also = [
{ piece = "hut", footprint = [3, 2], place = [1, 1] },
]

also gives a role more entries with other footprints or variants (when = "colour=red"). Imported games do not need a hand-written art set: one is generated from their organized assets.

Roles are resolved by ploom build, on your machine, before a map is converted. The pack is an ordinary pack of pieces or metatiles; nothing on the DS knows about roles, so they cost no memory and no time while playing. For each cell or placement:

  1. an entry for the role in the art sets, in order, with every variant asked for, then fewer, then none;
  2. the same for its parent, and its parent’s parent;
  3. for ground, the map’s commonest ground; for an object, nothing drawn (its cells keep their behaviour).

Fitting follows fixed rules, because gameplay must never move:

  • Art is never scaled.
  • Art never covers a walkable cell its source did not cover.
  • Buildings are fitted by their door: the art’s door cell goes on the map’s door cell, so the warp and the way in stay where they were. A building no entry fits is refused by the build, with the sizes it tried.
  • Rows are filled with the largest art that fits, then a fallback role.
  • Footprints, doors, warps and behaviours are the map’s; art changes only what is drawn.

Every fallback is counted. Nothing is silent.

An import sorts every asset of the world by source, family and role, with a readable name:

assets/<source>/world/tree/small/tree_small_03.obj
assets/<source>/world/building/center/center_01.obj
assets/<source>/world/_untagged/<original name>.obj

Each folder has an assets.toml sidecar: the original name, where in the source it came from, its roles, how sure the tag is (confidence), its footprint and size, and a preview. “Every tree of one game” is one folder. An asset the importer could not tag keeps its original name under _untagged/.

Command Does
ploom assets --source <s> --role tree every tree of that source (tree matches tree.small, tree.row and so on)
ploom assets --untagged what still needs a role
ploom assets tag <asset> <role> corrects a role in import/tags.toml; the next import moves the asset
ploom assets sheet --role tree one contact sheet PNG of the matching previews
ploom catalogue the same over every kind of asset, the maps too; --json for tools

A correction is your file and survives re-import. It holds names, not art, so it can be shared on its own.

A project can take its story from one source and its look from others. Sources are listed in sources.toml, with paths on your machine:

[source.story]
path = "../my-decomp-tree"
[source.look_a]
path = "/home/me/roms/game-a.nds"
[source.look_b]
path = "/home/me/roms/game-b.nds"

ploom source reads each into a source image: an ordinary, organized project in a per-user cache, keyed by the source’s content, so a second project that uses the same game reads it for free. ploom source add <name> <path> adds one; ploom source list shows them.

game.toml then says which source is the story and which draw the world:

[content]
source = "story"
[style]
world = ["look_a", "look_b"]
pick = { "lab" = "look_b" }
  • The content source owns every number. Maps, flags, variables, trainers, encounters, text and scripts are the story’s. Style sources contribute art by role and nothing else.
  • The chain is tried in order after your own art set. The first source is the anchor: its camera, light and edge rules are the world’s, because a scene lit by two games’ lights looks like two games.
  • pick pins a role and the roles under it to one source. Pinning a role to the content source keeps its own art.
  • [style.order] world chooses "chain" (the default: every fallback of one source before the next source) or "role" (a role’s exact art in any source before a parent role’s).
  • Lifting. A role no source draws takes the content source’s own art converted to the project’s style: a tile game’s metatile becomes a ground piece, a block of metatiles an upright card on its footprint.

The keys are in the settings reference.

ploom restyle --maps <a,b> writes the content source’s tile maps as 3D role maps of the project; --like <kind>=<map> takes how maps of a kind are shown from one of the anchor’s maps. ploom build then draws them through the chain and writes import/style.md (every cell by the step that drew it: own, exact, fallback, a later source, lifted, engine) and import/style/<map>.png (each cell in its step’s colour), so you can see what to replace first.

A project built this way is still one game: one pack, checked against every budget after the art is chosen (Limits), drawn the same on desktop and DS.

Before roles there was the reskin, and it still works. A project made with ploom sync <source> (another project’s story on its own creature data, described on Creatures and data) can take its look from a third project, keeping the source’s maps, story and scripts. overlay/reskin.toml names that project and maps the source’s art to the other’s:

from = "../other" # the project the look comes from
prefix = "other_" # names its copied models and textures get here
[textures] # a texture of the source = one of the other's
lawn = "grass"
[pieces] # an object piece of the source = one of the other's
sign = "post"
cottage = { piece = "house", origin = [2, 2.1875] }

ploom sync applies it after the overlay and says, line by line, what was mapped and what did not fit. The same rules hold as for roles: a replaced piece keeps the source’s footprint, behaviour and door, and what does not fit keeps the source’s art. Seams the source never drew can be made from the other’s edge tiles ([edges]), and any other picture replaced by its path ([files]).

Planned (plan 40): another PokeLoom project as a source of a style chain, which retires reskin.toml into [style] world.

Planned (plan 40):

  • More families. [style] chains for characters, trainers, creatures, battle, menus, music and sounds, each with its own vocabulary of roles, and units that stay whole (one creature’s pictures, one character’s frames, one menu screen’s art) so a creature never gets one game’s front and another’s back.
  • Picking. ploom import <source> --asset <id> --into <project> takes one map, a town or a building into any project, with what it needs, renamed and renumbered into the project, and a ledger so the next import keeps your edits. --dry-run prints the plan first.
  • 3D into tiles. A 3D map drawn in a tile game’s art, buildings with no tile art rendered to set pieces.
  • More sources. Standard formats (PNG, glTF and OBJ, MIDI, XM, WAV, Tiled, LDtk), community packs, and other PokeLoom projects.
  • Sharing. A build that refuses to package assets read from a ROM or a tree, and hack files that name each source by role so players rebuild the game from their own copies.