Tilemap layer Z (#174): Tilemaps, Scene-editing, Architecture, Development; check total 1076

Architecture.md

@@ -95,7 +95,8 @@ src/ui/                widget toolkit (generic, knows nothing about assets)
 src/viewport/          view (transforms), items (what to draw), symbols (how to draw it),
                        FileLibrary (load once, never retry a failure, tell the listeners) ← TextureLibrary, FontLibrary;
                        SoundLibrary, ShaderLibrary, ParticleLibrary,
-                       particles (one ParticleContainer per source), activeCamera — no editor concepts,
+                       particles (one ParticleContainer per source), tilemap (one container per layer),
+                       drawOrder (objects and tilemap layers by z, #174), activeCamera — no editor concepts,
                        so tests reach it freely
 src/editor/            App → Editor (layout + ticker), PlaySession (the run), ProjectSession (load/create),
                        EditorRun (run in editor), state, actions, shortcuts, debugHook, autosave,

Development.md

@@ -12,7 +12,7 @@ npm run check        # typecheck + lint + format:check + tests, the gate CI runs
                      #   code is lost (tail's is reported), so a red run reads as green
 npm run build        # writes dist/ and regenerates index.html
 ./build.sh           # the same under `set -o pipefail`, for callers that pipe the output
-node tools/seed-e2e.mjs && node tools/e2e.mjs                 # 1075 editor checks, screenshots in /tmp/gm-e2e-*.png
+node tools/seed-e2e.mjs && node tools/e2e.mjs                 # 1076 editor checks, screenshots in /tmp/gm-e2e-*.png
 GM_STEPS=20 node tools/e2e.mjs                                # or 1-12, or 6,20 — a subset while working on one step
 ./e2e.sh start [GM_STEPS]                                     # the same run detached, see below
 ./e2e.sh status                                               # live progress, or the last run's result

Scene-editing.md

@@ -18,7 +18,8 @@ Scene tab and the frame names of the Texture tab — read that size from one tok
 
 **Z-order is part of the position.** `position.z` is the draw order of a scene object: higher
 `z` is drawn on top; objects with equal `z` keep their hierarchy (tree) order. It is edited in the
-inspector next to X/Y, undoable like any move, and applies in edit and play mode alike.
+inspector next to X/Y, undoable like any move, and applies in edit and play mode alike. The layers
+of a tilemap are sorted in one by one, each at the map's `z` plus its own (see [Tilemaps](Tilemaps), #174).
 
 **Transform.** Sprites, texts, colliders and containers carry four more rows next to their
 position: **Scale** (one factor, default 1), **Rotation** (degrees, positive turns clockwise on

Tilemaps.md

@@ -110,6 +110,15 @@ Below the list (#138):
 
 - **Name** renames the layer you paint on. A blank name is not taken; the field goes back to the
   old one.
+- **Z** (#174) is that layer's place among the other objects of the scene, **added to the map's own
+  Z**, just as a child's Z is added to its parent's. Every layer starts at 0, where it is drawn right
+  after the map in list order, exactly as before. Give a layer "Treetops" a Z of 10 on a map at 0,
+  and a figure at 5 walks between the ground and the treetops. Because it is relative, moving the
+  map in Z takes all its layers along, and two placements of the same map each keep their layers
+  the same steps apart from their own Z. A negative Z sorts a layer below the map. Layers of equal
+  Z keep their list order; against other objects of equal Z the hierarchy decides, as always.
+  One undo step per change; the running game draws the same order, and a map whose Z a run changes
+  takes its layers with it.
 - **Show** decides how the scene view draws the *other* layers of the selected map: **All layers**
   as they are, **Others faded** at 30 %, or **Active layer only**. It is a way of looking while you
   paint, not a property of the map: it touches neither the project nor the game, a map that is not