From 3fe5b16998fe37a5d57f4942edbcf29970f363d2 Mon Sep 17 00:00:00 2001
From: keanu-stitch8 <riski.aditia@gmail.com>
Date: Sat, 31 Oct 2026 22:56:42 +0700
Subject: [PATCH 1/2] DM_CTL texraw saves every slice of a texture

texraw saved slice 0 only, so a cube, array or layered render target
could be checked only through its first face or layer. It now saves level
0 of every slice one after another (a cube's six faces), with the slice
count after the header's four fields when there is more than one. A
single-slice texture's file is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dm/gfx/nvn/nvn_mtl.m        | 10 ++++++----
 dm/host/hle_hid.c           |  2 +-
 docs/agents/05-debugging.md |  2 +-
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/dm/gfx/nvn/nvn_mtl.m b/dm/gfx/nvn/nvn_mtl.m
index 1140f62fde..ac854ac30a 100644
--- a/dm/gfx/nvn/nvn_mtl.m
+++ b/dm/gfx/nvn/nvn_mtl.m
@@ -10973,7 +10973,7 @@ void td_note_layer(id<MTLTexture> t, uint64_t ser, NSUInteger lv, NSUInteger sl)
     [g_td_list addObject:@[t, @(ser), @(lv), @(sl)]];
 }
 // The next frame's targets, on request (the Mac's DM_CTL "texdump <path>", hle_hid.c): the path is kept (strdup), the frame number is the one after the current
-// The Mac's DM_CTL "texraw <serial> <path>" (hle_hid.c): level 0 / slice 0 of the host texture behind a serial, raw, after the GPU finishes (header line: width height Metal format bytes per row);
+// The Mac's DM_CTL "texraw <serial> <path>" (hle_hid.c): level 0 of every slice (a cube's six faces) of the host texture behind a serial, raw, after the GPU finishes (header line: width height Metal format bytes per row, then the slice count when above one);
 // for a texture that is no render target (a default texture, a lookup table) whose content a shader depends on
 void dm_gfx_texraw(uint64_t serial, const char *path) {
     __unsafe_unretained id o = tex_get(serial);
@@ -10981,12 +10981,14 @@ void dm_gfx_texraw(uint64_t serial, const char *path) {
     id<MTLTexture> t = o; mtl_finish_gpu();
     if (t.storageMode == MTLStorageModeMemoryless || t.pixelFormat == MTLPixelFormatInvalid) return;
     NSUInteger w = t.width, h = t.height, row = w * 16, sz = row * h;   // 16 bytes a texel: a multiple of every uncompressed texel size
-    id<MTLBuffer> buf = [g_dev newBufferWithLength:sz options:MTLResourceStorageModeShared];
+    NSUInteger ns = (t.textureType == MTLTextureTypeCube || t.textureType == MTLTextureTypeCubeArray ? 6 : 1) * MAX(t.arrayLength, 1u);   // every slice (a cube's six faces), one after another
+    id<MTLBuffer> buf = [g_dev newBufferWithLength:sz * ns options:MTLResourceStorageModeShared];
     id<MTLCommandBuffer> cb = q_cb(); id<MTLBlitCommandEncoder> b = [cb blitCommandEncoder];
     MTLBlitOption bo = t.pixelFormat == MTLPixelFormatDepth32Float_Stencil8 ? MTLBlitOptionDepthFromDepthStencil : MTLBlitOptionNone;
-    [b copyFromTexture:t sourceSlice:0 sourceLevel:0 sourceOrigin:MTLOriginMake(0, 0, 0) sourceSize:MTLSizeMake(w, h, 1) toBuffer:buf destinationOffset:0 destinationBytesPerRow:row destinationBytesPerImage:sz options:bo];
+    for (NSUInteger s = 0; s < ns; s++)
+        [b copyFromTexture:t sourceSlice:s sourceLevel:0 sourceOrigin:MTLOriginMake(0, 0, 0) sourceSize:MTLSizeMake(w, h, 1) toBuffer:buf destinationOffset:sz * s destinationBytesPerRow:row destinationBytesPerImage:sz options:bo];
     [b endEncoding]; [cb commit]; [cb waitUntilCompleted];
-    FILE *f = fopen(path, "wb"); if (f) { fprintf(f, "%lu %lu %lu %lu\n", (unsigned long)w, (unsigned long)h, (unsigned long)t.pixelFormat, (unsigned long)row); fwrite(buf.contents, 1, sz, f); fclose(f); }
+    FILE *f = fopen(path, "wb"); if (f) { fprintf(f, "%lu %lu %lu %lu", (unsigned long)w, (unsigned long)h, (unsigned long)t.pixelFormat, (unsigned long)row); if (ns > 1) fprintf(f, " %lu", (unsigned long)ns); fputc('\n', f); fwrite(buf.contents, 1, sz * ns, f); fclose(f); }
     const uint8_t *p = buf.contents;
     MLOG("[texraw] ser=%llu %lux%lu format %lu type %lu → %s; first bytes %02x %02x %02x %02x %02x %02x %02x %02x", (unsigned long long)serial, (unsigned long)w, (unsigned long)h, (unsigned long)t.pixelFormat, (unsigned long)t.textureType, path, p[0], p[1], p[2], p[3], p[4], p[5], p[6], p[7]);
 }
diff --git a/dm/host/hle_hid.c b/dm/host/hle_hid.c
index db67a3ac9a..768a35701a 100644
--- a/dm/host/hle_hid.c
+++ b/dm/host/hle_hid.c
@@ -204,7 +204,7 @@ void hid_keys_init(void) {
 //   (hle_fpslock.c dm_ctl_cvar_f32; "cvari" an int one), "peek <address> <count>" logs that many floats of guest memory, "memdump <address> <bytes> <path>" saves guest memory
 //   to a file (a buffer texture's storage, which the pass dump's tbuf lines print, holds what the GPU wrote: buffer textures are views of the pool), "texlist <NVN target>" logs the
 //   registered textures of that target (2 = 3D) with storage address and block-linear layout (nvn_mtl.m dm_gfx_texlist), "texraw <serial> <path>"
-//   saves a host texture's level 0 raw (nvn_mtl.m dm_gfx_texraw), "drag <x0> <y0> <x1> <y1> [seconds=0.3]" moves one finger in a straight line between the two normalized picture
+//   saves a host texture's level 0 raw, every slice (a cube's six faces) (nvn_mtl.m dm_gfx_texraw), "drag <x0> <y0> <x1> <y1> [seconds=0.3]" moves one finger in a straight line between the two normalized picture
 //   points over that time and lifts it (the touch screen's pans and swipes, hle_touch.c gesture_sample), "dump" logs what each guest thread waits on and the graphics wait points
 //   (crash_dump_now, as the iOS app's DM_LOG_PORT dump; scripts/regress.py asks for it before stopping a hung game), "#…" is ignored.
 //   Look at a screen, decide, press, look again: menus whose timing moves from run to run (loading) need no blind timed script
diff --git a/docs/agents/05-debugging.md b/docs/agents/05-debugging.md
index 20dc66ebbe..c18a46f718 100644
--- a/docs/agents/05-debugging.md
+++ b/docs/agents/05-debugging.md
@@ -102,7 +102,7 @@ Patterns that worked: print every call of one function with its arguments; stop
 
 - `DM_KEYS="<seconds>:<button>[+button][~hold],…"` presses buttons from host start (`hle_hid.c`). `<seconds>:<button>*<count>/<interval>` repeats a press, e.g. `42:A*170/2` presses A every 2 s from 42 s on, 170 times; at most 1,048,576 steps after expansion. Commas, spaces and newlines all separate steps. Steps run in time order, so repeated groups interleave (`f17400:Left~0.3*120/500,f17480:A*120/500,f17560:Left~0.3*120/500,f17640:A*120/500` = Left, A, Left, A every 500 frames: Fire Emblem: Three Houses' confirm dialogs default to No, and this cycle confirms Yes whether a dialog is open or not when it starts; A, Left, A loops forever once it starts on an open dialog); a list that mixes seconds and frame numbers keeps its listed order. A long run through a game's story is then a single switch, such as Metroid Dread's title, new game and story recap. `LLeft` / `LUp` / `LRight` / `LDown` push the left stick fully (Super Mario 3D World moves on its map by stick only); `Shake` shakes the controller for the hold time, at least one whole shake (its six-axis sensor); combos such as `L+R~0.5` press buttons together. Scripted presses are player 1's, as is the keyboard, on a path of their own that is ORed with the keyboard and player 1's controller (`script_set`): a connected controller (a DualShock 4 publishes its sticks all the time) no longer overwrites them. An `f` before the time counts presented frames instead of seconds (`f2500:A`, repeat intervals in frames too): with another heavy job running, seconds drift away from the game's progress and a route stops lining up; frame numbers do not. Breath of the Wild from its title menu into the autosave: `DM_KEYS=f2500:A,f2800:A,f3100:A,f3400:A` (control at frame ~3900). `~f<frames>` holds for that many presented frames from the step's frame instead of seconds, and a step that begins where such a hold ends follows it without a release (a held touch moves instead of lifting); a gap is a release. A list of only such steps, as `DM_REC` writes, is applied at the game's own input reads, frame for frame ([Recording input](../development.md#recording-input-dm_rec)). `DM_KEYS=@<file>` reads the steps from a file. `L<x>/<y>` / `R<x>/<y>` tilt a stick part way and `T<x>x<y>` touches the screen (normalized, origin top left) for the hold.
 - `DM_REC=<file>` records player 1's physical input (keyboard, mouse touches, controllers; never `DM_KEYS` or `DM_CTL`) as `DM_KEYS` steps in presented frames, one per line: with the same build, a copy of the same save and the same `DM_DETCLOCK`, `DM_KEYS=@<file>` plays the run again, and joined to one line it is a smoke or bench route. Format, limits and the replay recipe: [Recording input](../development.md#recording-input-dm_rec).
-- `DM_CTL=<file>` (Mac) drives a running game step by step instead: the host polls the file every 100 ms and acts on each line appended to it (`hle_hid.c` `ctl_main`). A line is a press as in `DM_KEYS` (`A`, `LDown~0.2`, `L+R~0.5`), or `shot <path>` (the next presented frame as PNG), `passdump <n>` (the next n frames as `DM_NVN_PASSDUMP`), `texdump <path with %d>` (the next frame's colour targets as `DM_NVN_TEXDUMP`), `texraw <serial> <path>` (level 0 of the host texture behind a serial, raw, with a `width height format row` header), `texlist <NVN target>` (registered textures of that target, `2` = 3D, with storage address, size and block-linear layout), `memdump <address> <bytes> <path>` (guest memory to a file: a buffer texture's storage from its `B` line holds what the GPU wrote), `peek <address> <count>` (floats to the log), `cvarf` / `cvari <main offset> <value>` (an Unreal console variable's game- and render-thread copies, for a `TAutoConsoleVariable` found as for `hle_fpslock.c`), or `env KEY=VALUE` (for switches read at use). Look, press, look again: menus and loads whose timing moves between runs need no blind timed script. A shell helper that appends a line and waits for a shot to be written keeps the loop short (DRAGON QUEST VII Reimagined's work folder: `run/ctl.sh` with `wait S` / `snap NAME`, and route scripts on top of it into the opening cutscene).
+- `DM_CTL=<file>` (Mac) drives a running game step by step instead: the host polls the file every 100 ms and acts on each line appended to it (`hle_hid.c` `ctl_main`). A line is a press as in `DM_KEYS` (`A`, `LDown~0.2`, `L+R~0.5`), or `shot <path>` (the next presented frame as PNG), `passdump <n>` (the next n frames as `DM_NVN_PASSDUMP`), `texdump <path with %d>` (the next frame's colour targets as `DM_NVN_TEXDUMP`), `texraw <serial> <path>` (level 0 of every slice of the host texture behind a serial, raw, with a `width height format row [slices]` header), `texlist <NVN target>` (registered textures of that target, `2` = 3D, with storage address, size and block-linear layout), `memdump <address> <bytes> <path>` (guest memory to a file: a buffer texture's storage from its `B` line holds what the GPU wrote), `peek <address> <count>` (floats to the log), `cvarf` / `cvari <main offset> <value>` (an Unreal console variable's game- and render-thread copies, for a `TAutoConsoleVariable` found as for `hle_fpslock.c`), or `env KEY=VALUE` (for switches read at use). Look, press, look again: menus and loads whose timing moves between runs need no blind timed script. A shell helper that appends a line and waits for a shot to be written keeps the loop short (DRAGON QUEST VII Reimagined's work folder: `run/ctl.sh` with `wait S` / `snap NAME`, and route scripts on top of it into the opening cutscene).
 - Frame numbers are a stable way to aim dumps (`DM_NVN_PASSDUMP=<frame>`, `DM_NVN_SHOT=…`) at the same scene in another run: the per-frame NVN call counts (`[nvn] frame N: … calls`) matched between runs of the same script. Times in seconds drift with load.
 - **A route through a 3D level** (Captain Toad: Treasure Tracker's opening course, where Toad has to find his way up a diorama to the star): screenshots alone took a dozen runs and still lost Toad behind the scenery, and turning the camera mid-route made the same input land differently each run. What worked: read the player's position every frame with a probe and plan from the stage's own data. The guest heap is laid out the same in every run, so the player actor is at the same address. `DM_PROBE=main:1fb2e0@*x0+48+8` (`PlayerActor::control`, the actor's pose at +0x48, the position 8 bytes into it, as `al::getTrans` reads it) prints x, y (height), z as three floats per frame. The stage map (`StageData/<stage>.szs`, a BYML) lists every actor with its `Translate`, including the goal and the rail the guide character walks. Stick directions are camera-relative: on the default camera two directions together (`LUp+LRight`) move along one world axis. Hold against walls where possible, since a wall stops the player at the same place in every run; the route then reproduced in 5 of 5 runs.
 - **Spin waits** (`patch_nso.py` "Spin waits", `dm_spin_wait` in `hle_thread.c`).

From abbfb627c33661dc2d298964df6756c96d2ece59 Mon Sep 17 00:00:00 2001
From: keanu-stitch8 <riski.aditia@gmail.com>
Date: Sat, 31 Oct 2026 22:57:34 +0700
Subject: [PATCH 2/2] nvn-mtl: a clear covers every layer of the bound render
 target view

NVN clears every layer of the render target view that is bound (the whole
texture when the view sets no layer range). A clear folded into a Metal
pass's load action clears only the layers the pass attaches, and a pass
that is not layered attaches one, so the other layers of an array, cube or
3D target kept their old or zero content.

Little Nightmares (01002FC00412C000, Unreal Engine 4) clears the 512x512
cube of each point light's one-pass shadow (geometry shader
ffc21034b958840b) in the pass that captures the vertex shader's output,
which is not layered. Only the +X face was cleared; faces 1-5 kept the zero
depth they were created with, every fragment the layered pass drew there
failed the depth test, and the comparison sampler read them as fully
shadowed: the lantern and the lighter lit only one side of the room, with
straight edges.

rp_begin_ex_ now clears such an attachment in a pass of its own with
renderTargetArrayLength set to the view's layers (att_layers), then loads
it in the real pass, as it already did for attachments larger than the
pass. A view limited to some layers clears only those; layered passes and
single-layer targets are unchanged. t_clear_layers runs the production
replay on a cube depth target and a 2D array colour target, with and
without layer ranges (4 of its 6 cases fail without the fix).

Checked on the Mac: Little Nightmares' shadow cube holds depth on all six
faces after the fix (texraw), and the lantern room is lit all around with
Six's shadow on the floor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dm/gfx/nvn/nvn_mtl.m          | 22 ++++++++--
 dm/gfx/tests/Makefile         |  3 ++
 dm/gfx/tests/t_clear_layers.m | 76 +++++++++++++++++++++++++++++++++++
 docs/agents/symptoms.md       |  1 +
 docs/reference/rendering.md   |  8 ++++
 5 files changed, 106 insertions(+), 4 deletions(-)
 create mode 100644 dm/gfx/tests/t_clear_layers.m

diff --git a/dm/gfx/nvn/nvn_mtl.m b/dm/gfx/nvn/nvn_mtl.m
index ac854ac30a..14075dd458 100644
--- a/dm/gfx/nvn/nvn_mtl.m
+++ b/dm/gfx/nvn/nvn_mtl.m
@@ -3338,6 +3338,14 @@ static int rt_dup_slot(const p_set_rt *r, int i) {
     }
     return 0;
 }
+// The layers an attached render target view covers from its attached slice (3D: depth plane) on: the view's layer count (0: the rest), else every layer the texture has from there
+static NSUInteger att_layers(MTLRenderPassAttachmentDescriptor *a, const view_t *v, int has_v) {
+    id<MTLTexture> t = a.texture; if (!t) return 1;
+    NSUInteger all = t.textureType == MTLTextureType3D ? MAX(t.depth >> a.level, 1u) : t.arrayLength * (t.textureType == MTLTextureTypeCube || t.textureType == MTLTextureTypeCubeArray ? 6 : 1);
+    NSUInteger from = t.textureType == MTLTextureType3D ? a.depthPlane : a.slice, n = all > from ? all - from : 1;
+    if (has_v && v->set_layers && v->nlayers) n = MIN(n, (NSUInteger)v->nlayers);
+    return MAX(n, 1u);
+}
 static void attach(MTLRenderPassAttachmentDescriptor *a, const tex_t *t, const view_t *v, int has_v) {
     id<MTLTexture> base = tex_mtl(t);
     // A texture made without render-target use (packaged or CPU-written, uploaded from its storage) drawn into: give it that use, as a clear of one does (clear_tex). Metal's validation
@@ -3468,13 +3476,19 @@ static void attach(MTLRenderPassAttachmentDescriptor *a, const tex_t *t, const v
     }
     // A pass covers only the smallest of its attachments, and so does a clear folded into its load action, while NVN clears the whole target. Bayonetta 2 (SDK 3.6) starts every frame with a
     // 32x32 or 256x256 colour target beside its 1280x720 depth buffer and clears the depth there: only that corner was cleared, the scene behind failed the depth test against the
-    // previous frames' depth everywhere else, and its story narration showed in the top-left corner of a black screen. A cleared attachment larger than the pass is cleared in a pass of its own first
+    // previous frames' depth everywhere else, and its story narration showed in the top-left corner of a black screen. A cleared attachment larger than the pass is cleared in a pass of its own first.
+    // The same holds for layers: NVN clears every layer of the target's view, a load action only the pass's layers (one, unless the pass is layered). Little Nightmares clears its point
+    // lights' 6-face shadow cube in the pass that captures the one-pass geometry shader's vertices: only face 0 was cleared, faces 1-5 kept zero depth, every fragment failed the depth test
+    // there and the light passed only through the +X face. A cleared attachment whose view has more layers than a pass that is not layered is cleared, every layer, in a pass of its own too
     {   NSUInteger pw, ph; pass_dims(pd, (NSUInteger)R.rt.n, &pw, &ph);
         for (NSUInteger i = 0; i < (NSUInteger)R.rt.n + 1; i++) {
             MTLRenderPassAttachmentDescriptor *a = i < (NSUInteger)R.rt.n ? pd.colorAttachments[i] : pd.depthAttachment.texture ? pd.depthAttachment : pd.stencilAttachment;
             int ds = i == (NSUInteger)R.rt.n, cd = ds && pd.depthAttachment.texture && pd.depthAttachment.loadAction == MTLLoadActionClear, cs = ds && pd.stencilAttachment.texture && pd.stencilAttachment.loadAction == MTLLoadActionClear;
-            if (!a.texture || (ds ? !cd && !cs : a.loadAction != MTLLoadActionClear) || (mip_extent(a.texture.width, a.level) <= pw && mip_extent(a.texture.height, a.level) <= ph)) continue;
+            if (!a.texture || (ds ? !cd && !cs : a.loadAction != MTLLoadActionClear)) continue;
+            NSUInteger nl = g_rp_layered ? 1 : att_layers(a, ds ? &R.rt.dview : &R.rt.cview[i], ds ? R.rt.has_dview : R.rt.has_cview[i]);
+            if (nl < 2 && mip_extent(a.texture.width, a.level) <= pw && mip_extent(a.texture.height, a.level) <= ph) continue;
             MTL4RenderPassDescriptor *cp = [MTL4RenderPassDescriptor new];
+            if (nl > 1) cp.renderTargetArrayLength = nl;
             if (!ds) { MTLRenderPassColorAttachmentDescriptor *c = cp.colorAttachments[0], *o = pd.colorAttachments[i];
                 c.texture = o.texture; c.level = o.level; c.slice = o.slice; c.depthPlane = o.depthPlane; c.clearColor = o.clearColor; c.loadAction = MTLLoadActionClear; c.storeAction = MTLStoreActionStore;
                 o.loadAction = MTLLoadActionLoad; }
@@ -3484,8 +3498,8 @@ static void attach(MTLRenderPassAttachmentDescriptor *a, const tex_t *t, const v
                 if (cs) { MTLRenderPassStencilAttachmentDescriptor *s = cp.stencilAttachment, *o = pd.stencilAttachment;
                     s.texture = o.texture; s.level = o.level; s.slice = o.slice; s.clearStencil = o.clearStencil; s.loadAction = MTLLoadActionClear; s.storeAction = MTLStoreActionStore; o.loadAction = MTLLoadActionLoad; }
             }
-            PD("C %llu %s%lu cleared in a pass of its own (%lux%lu, the pass covers %lux%lu)", g_stat_pass + 1, ds ? "d" : "c", (unsigned long)i, (unsigned long)mip_extent(a.texture.width, a.level),
-               (unsigned long)mip_extent(a.texture.height, a.level), (unsigned long)pw, (unsigned long)ph);
+            PD("C %llu %s%lu cleared in a pass of its own (%lux%lu, %lu layers; the pass covers %lux%lu)", g_stat_pass + 1, ds ? "d" : "c", (unsigned long)i, (unsigned long)mip_extent(a.texture.width, a.level),
+               (unsigned long)mip_extent(a.texture.height, a.level), (unsigned long)nl, (unsigned long)pw, (unsigned long)ph);
             ser_gate(); enc_r_end(enc_r_begin(cp));
         }
     }
diff --git a/dm/gfx/tests/Makefile b/dm/gfx/tests/Makefile
index 8b9c607f1c..81908cf413 100644
--- a/dm/gfx/tests/Makefile
+++ b/dm/gfx/tests/Makefile
@@ -351,6 +351,9 @@ check_t_depth16_clear: RUN_ENV = MTL_DEBUG_LAYER=1
 t_clear_ds: t_clear_ds.m $(MTL_T_DEP)
 	clang $(CFLAGS) -fobjc-arc -o $@ t_clear_ds.m $(MTL_T_SRC) $(FW)
 check_t_clear_ds: RUN_ENV = MTL_DEBUG_LAYER=1
+t_clear_layers: t_clear_layers.m $(MTL_T_DEP)
+	clang $(CFLAGS) -fobjc-arc -o $@ t_clear_layers.m $(MTL_T_SRC) $(FW)
+check_t_clear_layers: RUN_ENV = MTL_DEBUG_LAYER=1
 t_clear_tex: t_clear_tex.m $(MTL_T_DEP)
 	clang $(CFLAGS) -fobjc-arc -o $@ t_clear_tex.m $(MTL_T_SRC) $(FW)
 .PHONY: check_t_clear_tex
diff --git a/dm/gfx/tests/t_clear_layers.m b/dm/gfx/tests/t_clear_layers.m
new file mode 100644
index 0000000000..d341957fab
--- /dev/null
+++ b/dm/gfx/tests/t_clear_layers.m
@@ -0,0 +1,76 @@
+// A clear covers every layer of the bound render target view, as NVN's does, not only the layer a pass that is not layered attaches.
+#include "../nvn/nvn_mtl.m"
+void *front_metal_layer(void) { return NULL; }
+module_t *module_of(const void *p) { (void)p; return NULL; }
+module_t *g_mod; int g_nmod;
+void svc_thread_dump(void) {}
+uint64_t now_ns(void) { return bp_now(); }
+static int checks, failed;
+#define CHECK(c, label) do { checks++; if (!(c)) { failed++; fprintf(stderr, "FAIL: %s\n", label); } } while (0)
+
+enum { W = 4, OLD_D = 0x3f400000, NEW_D = 0x3e800000, OLD_C = 0x11223344, NEW_C = 0x80808080 };   // depth .75 → .25; RGBA8 → 0.5 in every channel
+
+int main(void) { @autoreleasepool {
+    mtl_init();
+    id<MTLCommandQueue> queue = [g_dev newCommandQueue];
+    // depth: a cube (6 faces) or a 2D array of colour; view: none, or min_layer / nlayers (0: the rest)
+    struct { int depth, target, layers, view, min_layer, nlayers; const char *label; } cases[] = {
+        {1, NVN_TEXTURE_TARGET_CUBEMAP, 6, 0, 0, 0, "depth clear of a cube without a view clears all six faces"},
+        {1, NVN_TEXTURE_TARGET_CUBEMAP, 6, 1, 2, 1, "depth clear through a one-face view clears that face only"},
+        {0, NVN_TEXTURE_TARGET_2D_ARRAY, 4, 0, 0, 0, "colour clear of a 2D array without a view clears every layer"},
+        {0, NVN_TEXTURE_TARGET_2D_ARRAY, 4, 1, 1, 0, "colour clear through a view from layer 1 on clears layers 1-3"},
+        {0, NVN_TEXTURE_TARGET_2D_ARRAY, 4, 1, 1, 2, "colour clear through a two-layer view clears layers 1-2"},
+        {0, NVN_TEXTURE_TARGET_2D, 1, 0, 0, 0, "colour clear of a 2D target stays one layer"},
+    };
+    for (unsigned i = 0; i < sizeof cases / sizeof *cases; i++) {
+        tex_t t = {.magic = MAGIC('T','E','X',0), .serial = 99501 + i};
+        t.d = (nvn_texdesc){.target = cases[i].target, .format = cases[i].depth ? NVN_FORMAT_DEPTH32F_STENCIL8 : NVN_FORMAT_RGBA8, .width = W, .height = W,
+                            .depth = cases[i].target == NVN_TEXTURE_TARGET_2D_ARRAY ? cases[i].layers : 1, .levels = 1, .samples = 1};
+        MTLTextureDescriptor *descriptor = tex_desc(&t, 0);
+        id<MTLTexture> base = [g_dev newTextureWithDescriptor:descriptor];
+        CHECK(base != nil && base.arrayLength == (NSUInteger)cases[i].layers, "synthetic layered target allocates");
+        if (!base) continue;
+        id<MTLCommandBuffer> cb = [queue commandBuffer];
+        for (int s = 0; s < cases[i].layers; s++) {   // every layer starts at the old value
+            MTLRenderPassDescriptor *init = [MTLRenderPassDescriptor renderPassDescriptor];
+            if (cases[i].depth) { init.depthAttachment.texture = base; init.depthAttachment.slice = s; init.depthAttachment.loadAction = MTLLoadActionClear;
+                init.depthAttachment.storeAction = MTLStoreActionStore; init.depthAttachment.clearDepth = .75; }
+            else { init.colorAttachments[0].texture = base; init.colorAttachments[0].slice = s; init.colorAttachments[0].loadAction = MTLLoadActionClear;
+                init.colorAttachments[0].storeAction = MTLStoreActionStore; init.colorAttachments[0].clearColor = MTLClearColorMake(0x44 / 255., 0x33 / 255., 0x22 / 255., 0x11 / 255.); }
+            [[cb renderCommandEncoderWithDescriptor:init] endEncoding];
+        }
+        [cb commit]; [cb waitUntilCompleted];
+        CHECK(cb.status == MTLCommandBufferStatusCompleted, "initial layers reach the GPU");
+        res_add(base); mtl_tex_init(&t); serial_put(t.serial, base);
+        state_reset(); memset(&R, 0, sizeof R); mtl_sub_begin();
+        view_t v = {0}; if (cases[i].view) { v.set_layers = 1; v.min_layer = (uint16_t)cases[i].min_layer; v.nlayers = (uint16_t)cases[i].nlayers; }
+        R.has_rt = 1;
+        if (cases[i].depth) { R.rt.depth = &t; R.rt.dview = v; R.rt.has_dview = (uint8_t)cases[i].view; }
+        else { R.rt.n = 1; R.rt.color[0] = &t; R.rt.cview[0] = v; R.rt.has_cview[0] = (uint8_t)cases[i].view; }
+        struct { op_hdr head; union { p_clear_ds ds; p_clear_color c; } clear; op_hdr end; } ops = {0};
+        if (cases[i].depth) { ops.head = (op_hdr){OP_CLEAR_DS, sizeof(op_hdr) + sizeof(p_clear_ds)}; ops.clear.ds = (p_clear_ds){.depth = .25, .depth_mask = 1}; }
+        else { ops.head = (op_hdr){OP_CLEAR_COLOR, sizeof(op_hdr) + sizeof(p_clear_color)}; ops.clear.c = (p_clear_color){.index = 0, .mask = 0xf, .rgba = {.5f, .5f, .5f, .5f}}; }
+        ((op_hdr *)((uint8_t *)&ops + ops.head.size))->op = OP_END; ((op_hdr *)((uint8_t *)&ops + ops.head.size))->size = sizeof(op_hdr);
+        mtl_exec((const uint8_t *)&ops);
+        mtl_sub_commit(); mtl_drain();
+        CHECK(!mtl_last_commit_error(), "production clear completes without GPU error");
+        id<MTLBuffer> result = [g_dev newBufferWithLength:W * W * 4 * cases[i].layers options:MTLResourceStorageModeShared];
+        cb = [queue commandBuffer]; id<MTLBlitCommandEncoder> b = [cb blitCommandEncoder];
+        for (int s = 0; s < cases[i].layers; s++)
+            [b copyFromTexture:base sourceSlice:s sourceLevel:0 sourceOrigin:MTLOriginMake(0, 0, 0) sourceSize:MTLSizeMake(W, W, 1) toBuffer:result destinationOffset:(NSUInteger)(W * W * 4 * s)
+                destinationBytesPerRow:W * 4 destinationBytesPerImage:W * W * 4 options:cases[i].depth ? MTLBlitOptionDepthFromDepthStencil : MTLBlitOptionNone];
+        [b endEncoding]; [cb commit]; [cb waitUntilCompleted];
+        CHECK(cb.status == MTLCommandBufferStatusCompleted, "every layer is read back");
+        const uint32_t *px = result.contents; int valid = 1;
+        int lo = cases[i].view ? cases[i].min_layer : 0, hi = cases[i].view && cases[i].nlayers ? lo + cases[i].nlayers : cases[i].layers;
+        for (int s = 0; s < cases[i].layers; s++) {
+            uint32_t want = s >= lo && s < hi ? (cases[i].depth ? NEW_D : NEW_C) : (cases[i].depth ? OLD_D : OLD_C);
+            for (int k = 0; k < W * W; k++) if (px[s * W * W + k] != want) { valid = 0; fprintf(stderr, "case %u layer %d texel %d: %#x, want %#x\n", i, s, k, px[s * W * W + k], want); break; }
+        }
+        CHECK(valid, cases[i].label);
+        printf("case %u: %s %s\n", i, cases[i].label, valid ? "PASS" : "FAIL");
+        mtl_tex_release(&t);
+    }
+    printf("layered clears: %d checks, %d failed\n", checks, failed);
+    return failed != 0;
+} }
diff --git a/docs/agents/symptoms.md b/docs/agents/symptoms.md
index 84313c92a7..96c1b3039a 100644
--- a/docs/agents/symptoms.md
+++ b/docs/agents/symptoms.md
@@ -456,6 +456,7 @@ One line per symptom in the [subsystem references](../reference/): what you see
 - a frame-time spike every few frames (the Metal HUD's frame-time line jumps by several ms at a regular interval) while the scene stands still; `DM_NVN_GPUPROF` over consecutive frames shows the slow frame with about 130 more render passes, each one draw into a 64x64 to 8x8 face of a cube or array level, and the next pass starting late. → [Passes into other layers of one texture level run as one layered pass](../reference/rendering.md#passes-into-other-layers-of-one-texture-level-run-as-one-layered-pass)
 - a GPU-bound frame with many passes on the same targets, one after the other, each preceded by a compute encoder of one dispatch (`DM_NVN_GPUPROF`: `compute / copy after pass … dispatches 1` between render passes of the same size); about 4 ms of GPU idle a frame inside command buffers in Metal System Trace. → [Compute dispatches between the draws of a pass run ahead of it](../reference/rendering.md#compute-dispatches-between-the-draws-of-a-pass-run-ahead-of-it)
 - a scene drawn only in a small square in the top-left corner of a black screen; speckled and blocky patches; a full-screen overlay showing one tile; the texture dump right after the scene pass shows the picture only in the corner, and `DM_NVN_HILITE` on the scene's shaders lights only the corner. → [Clears of attachments larger than the render pass](../reference/rendering.md#clears-of-attachments-larger-than-the-render-pass)
+- a point light (a lantern, a lighter) lights only one side of the room with straight, sharp edges, and everything else around it is dark as if in shadow; a dump of the shadow cube (DM_CTL `texraw`, every face) shows face 0 drawn and faces 1-5 all zero; more generally, layers above the first of an array, cube or 3D target keep their old or zero content after a clear. → [Clears of layered render targets in a pass that is not layered](../reference/rendering.md#clears-of-layered-render-targets-in-a-pass-that-is-not-layered)
 - `texture clear case not implemented … mask 0x1`. → [A channel mask that covers every channel is a whole clear](../reference/rendering.md#a-channel-mask-that-covers-every-channel-is-a-whole-clear)
 - `texture clear case not implemented … mask 0x8` while entering a rendered scene. → [Texture clears with partial channel masks or regions](../reference/rendering.md#texture-clears-with-partial-channel-masks-or-regions)
 - red lines for unimplemented mid-pass, partial-mask and partial-scissor clears (the clears were dropped); `depth-stencil clear with a scissor or partial stencil mask, cleared whole` (logged once). → [Clears inside a pass, with a partial mask or a partial scissor](../reference/rendering.md#clears-inside-a-pass-with-a-partial-mask-or-a-partial-scissor)
diff --git a/docs/reference/rendering.md b/docs/reference/rendering.md
index 7f0eebece1..0764a40411 100644
--- a/docs/reference/rendering.md
+++ b/docs/reference/rendering.md
@@ -367,6 +367,14 @@ The replay on Metal (`dm/gfx/nvn/nvn_mtl.m`) and the Vulkan and OpenGL layers. E
 - **Found on:** [Bayonetta 2](../../dm/games/01007960049A0000/README.md): every frame starts with a pass whose colour target is 32x32 (then 256x256 ones) beside the 1280x720 depth buffer, and the game clears the depth there; the story's opening narration showed its scene in a 32x32 or 256x256 square of a black screen. [Bayonetta](../../dm/games/010076F0049A2000/README.md) needed nothing more.
 - **Not checked:** the fix in other games beyond the unit tests.
 
+### Clears of layered render targets in a pass that is not layered
+
+- **Symptom:** a point light (a lantern, a lighter) lights only one side of the room with straight, sharp edges, and everything else around it is dark as if in shadow; a dump of the shadow cube (DM_CTL `texraw`, every face) shows face 0 drawn and faces 1-5 all zero; more generally, layers above the first of an array, cube or 3D target keep their old or zero content after a clear.
+- **Cause:** NVN clears every layer of the render target view that is bound (the whole texture without a layer range). A clear folded into a Metal pass's load action clears only the layers the pass attaches, and a pass that is not layered (`renderTargetArrayLength` unset) attaches one. When the clear lands in such a pass (the vertex capture pass of a geometry shader draw, a lazy clear landed on its own), the other layers kept zero depth from creation, every fragment the later layered pass drew there failed the depth test, and the comparison sampler read them as fully shadowed.
+- **Fix:** `rp_begin_ex_` (`nvn_mtl.m`, `att_layers`) clears a cleared attachment whose view covers more layers than a pass that is not layered in a pass of its own, with `renderTargetArrayLength` set to the view's layers, and loads it in the real one, as it does for attachments larger than the pass ([Clears of attachments larger than the render pass](#clears-of-attachments-larger-than-the-render-pass)). A view limited to some layers clears only those. The pass dump prints `C … cleared in a pass of its own (… N layers …)`. `t_clear_layers` runs the production replay on a cube depth target and a 2D array colour target, with and without layer ranges.
+- **Found on:** Little Nightmares (`01002FC00412C000`, Unreal Engine 4, a provisional profile): its point lights' one-pass cube shadows (geometry shader `ffc21034b958840b`, which emits each triangle into the six faces) clear the 512x512 cube in the pass that captures the vertex shader's output; only the +X face was cleared, so the lantern's and the lighter's light passed only through that face.
+- **Not checked:** other games beyond the unit tests and Little Nightmares.
+
 ### Lazy clears folded into the next pass
 
 - **Fix:** lazy clears (`DM_NVN_LAZY_CLEAR`) fold clear-only passes into the pass that follows.