A level that exists only as painted Tilemaps can be looked at and played, and nothing else. It cannot be diffed, generated, converted from another editor, validated outside the Editor, or asked "can the runner reach that pickup". Asking a Tilemap "is this cell solid" is a native call per cell; its bounds grow when painted and never shrink when erased; and its collider catches up with its tiles later in the frame. None of that is a bug — a Tilemap is a renderer. The level is the small data structure it was painted from.

1. Build the layer stack.

   resources/Editor/TilemapLayerStackBuilder.cs

   → Tools ▸ Unity Dev ▸ 2D Level ▸ Build Layer Stack (Side View) or (Top-Down). It reports the Grid, the six Tilemaps, their colliders and sorting, names any sorting or physics layer the project lacks, and waits. →

   reference/layer-stack.md

2. Get one level into data. Start from

   templates/sample-level.json

   (a 40 × 12 side run: four roofs, a hazard, a ledge, a launch pad, a sentry, three pickups, a gate); or convert a Tiled map; or paint the stack and export it. →

   reference/level-data.md

3. Validate it before it is ever loaded:
   bash

   python3 scripts/level_validate.py templates/sample-level.json \
       --jump-height 2.85 --jump-distance 5.17 --fall-multiplier 1.5

   Exit 0 with

   "verdict":"ok"

   . Delete the

   launch-1

   entity and it exits 1 naming

   pickup-2

   ,

   pickup-3

   and the gate — the third roof is four cells up and the apex is 2.85. The jump numbers come from the controller, never from the level:

   --metrics metrics.json

   reads what

   unity-gameplay

   →

   scripts/level_metrics.py

   prints.
4. Load it:
   csharp

   loader.spawnEntity = (entity, position) => _spawner.Spawn(entity.type, position, entity);
   loader.Load(LevelData.FromJson(levelJson.text));    // throws on a bad shape or an unbound tile id
   _runner.position = loader.SpawnPosition;

   One

   SetTilesBlock

   per layer, colliders synchronised before

   Load

   returns, the marker layer hidden. →

   reference/runtime-tilemap.md

5. Prove the rendering is the data:

   loader.Verify(level)

   returns 0 mismatched cells. Then write the level's rules into

   templates/LEVEL_INVARIANTS.md

   , one id each.

• The data is the truth; the Tilemap is painted from it. Gameplay asks

  LevelData.IsSolid

  , not

  Tilemap.GetTile

  . A runtime change goes through

  TilemapLevelLoader.SetCell

  , which writes the data and then the tile, so the two cannot drift.
• Ids, never asset references. A tile is an integer bound in one table; an entity is a type string the game maps to a prefab. A level that references assets cannot be read by a script, survive a rename, or arrive after release.
• Row 0 is the bottom. That is Tilemap cell space. A converter from an editor that counts rows downwards flips once; a level that loads upside down was flipped zero times or twice.
• Six layers, fixed names. Collision, drawing in front of the runner and one-way behaviour are properties of a layer, not of a tile. A seventh Tilemap is one the loader never paints and the validator never reads.
• Validate the file, then load it.

  LevelData.Problems()

  for the shape and

  scripts/level_validate.py

  for reachability, in CI, over every level and every generated seed. A level that loads with a hole is found by a player.
• The jump belongs to the controller. The validator takes its numbers from the metrics file. A level that passes only with a wider jump is a level bug, not a reason to widen it.
• Paint in blocks, then synchronise the collider. One

  SetTilesBlock

  per layer, a z size of 1,

  ProcessTilemapChanges()

  before a body is placed on the result.
• Generate the path first. Reachability that holds by construction needs no repair pass; the check confirms the construction. One failing seed in a thousand is a generator bug.
• One seeded

  System.Random

  , passed down. Never

  UnityEngine.Random

  , never the iteration order of a set, never the clock. The seed goes in the level id and in every bug report.
• Check the pair, not the chunk. Two fair chunks form a join nobody checked; every chunk has a flat run-in and run-out, and entry height equals the previous exit height.
• A room is at least one screen, on tile boundaries, and names no camera. It raises one event; the camera, the spawner and the checkpoint listen.
• What the cell search cannot see gets a journey. Curved ground, a wall jump, a pickup collected mid-arc: list it as waived with the journey that proves it.