Cockpit: the authentic punch STENCIL-CUT -- all 8 cockpits real (task #55)

The user caught the inversion (blocked viewports, see-through frames); the
answer came from the rasterizer board itself: an i860 disassembly of the
VREND.MNG firmware decoded the damageize handler (@0xf040f6f8) -- cmd 0x20
(vr_damage_action) writes the dpl_Punchize token triple onto the punch
geogroup's first three geometry chunks IN FILE ORDER:

  chunk1 = the detailed window-aperture shapes -> an invisible per-pixel MASK
  chunk2 = the coarse hull -> the ONLY colour-drawn geometry (where not masked)
  chunk3 = byte-identical hull twin -> the damage-reset record, never visible

Visible canopy = hull-minus-apertures.  Both earlier readings were wrong ways
around the same three chunks: dropping all punch left floating fragments (no
hull); hiding the duplicate pair hid the HULL and drew the MASK -- the exact
inversion observed.

Port: bgfload tags per punch patch {non-paired pmesh = mask (role 1),
first twin = hull (role 2), second twin = skip}; L4D3D DrawMesh runs
mask->stencil-1 (no colour/z-write, z-tested), hull->stencil-NOTEQUAL,
mask->stencil-0; device D24X8 -> D24S8 + stencil clear.  The cut never
touches z, so later-drawn entities show through the apertures.
BT_COP_PLATES=1 disables (diag).

In-game, all 8 mechs on pure defaults: connected dark frames with clear
viewports -- thor (the footage mech) shows the central viewport + surrounding
frame exactly as filmed.  Combat regression clean (kill + no NaN).

Arena textured punch uses the same firmware kit; the black-texel alpha path
there is a working approximation, flagged in the KB.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

context/bgf-format.md

@@ -48,15 +48,15 @@ LOD whose band contains the camera distance.
   sibling `dpl_Damagize` FUN_004902b0 uses the same cmd with a different triple). Two cases: [T1]
   - **Textured** punch (arena walls/catwalks): black texels = HOLES (alpha-test in the opaque
     pass). Coplanar shells inside one LOD z-fight → depth-bias by submission ordinal. [T2]
-  - **Texture-less** punch (the `*_cop` cockpit canopies: blakskn + `softer` ramp, NO texture tag
-    in the BMF — byte-verified, 238-byte BLXSKIN.BMF): **the PUNCH-tagged patches ARE the
-    transparent WINDOWS** (the whole tagged geogroup renders as holes); the visible frame is only
-    the NON-punch geometry, itself an open strut lattice rendered single-sided with per-face
-    INWARD winding (the l/r torso patches are MIRRORED, so no single global winding works).
-    Verified by rendering every shell from its mech's AUTHORED eye (SKL [jointeye]) — the punch
-    panes sit exactly over the window apertures in all 8 mechs; all-punch canopies
-    (bhk1/loki/vulture/avatar) are authentically FRAMELESS. The old "canopy windows are punch
-    texels" claim was WRONG — there is no texel to key. See [[cockpit-view]]. [T2 in-game, all 8]
+  - **FINAL mechanism (i860 VREND.MNG firmware, decoded 2026-07-11): a punch geogroup is a
+    THREE-CHUNK STENCIL-CUT KIT** -- in file order: aperture MASK (invisible per-pixel cutout),
+    visible HULL (the only colour-drawn chunk, drawn where not masked), byte-identical hull TWIN
+    (the damage-reset record, never visible).  Visible result = hull-minus-apertures.  Applies
+    to cockpit canopies, arena punch (AR02 etc.) and outside-torso punch (VUX_TOR) alike -- the
+    port's arena "black texels = holes" alpha-test path is a visual approximation that predates
+    this decode (works; revisit for exactness).  Port: bgfload punch-kit roles + the L4D3D
+    stencil cut (D24S8).  See [[cockpit-view]] + [[decomp-reference]] for firmware addresses.
+    [T1 mechanism / T2 render-verified all 8 cockpits]
 
 ## Shading model (from libDPL DPLTYPES.H)
 Shading is selected PER-GEOMETRY by vertex type:

context/cockpit-view.md

@@ -88,17 +88,21 @@ inverse(eyeWorld)`. No LookAt anywhere.
   (pos=(0.1,0.15,0.1), neg=(−0.1,−0.15,−0.1) — same for madcat AND bhk1) → the eye equilibrium
   is (0,0,0) and the clamps limit gyro motion to ±0.1..0.15u. The gyro is a BOUNCE/sway
   mechanism, NOT a large steady offset. The authentic resting eye = raw baseOffset for every mech.
-- **RESOLVED (2026-07-11): the PUNCH patches are the transparent WINDOWS.** Rendering every
-  shell OFFLINE from its mech's AUTHORED eye (scratchpad/cop_eyeview.py, faces coloured by punch
-  flag) showed the punch panes sitting exactly over the window apertures in all 8 mechs, with the
-  visible frame = ONLY the non-punch geometry.  The loader now DROPS the punch batches of `_cop`
-  meshes (bgfload finish(), `BT_COP_KEEPPUNCH=1` keeps them for diag).  In-game sweep on pure
-  defaults, all 8 mechs [T2]: **madcat** = the dark dome frame (matches footage); **thor** =
-  floating brace remnants (authentic; its frame bits are the small non-punch patches); **owens** =
-  dash strip; **sunder** = two side pillars; **bhk1/loki/vulture/avatar** = authentically
-  FRAMELESS (all-punch canopies — the pod showed no frame for those mechs).  NOTE: an
-  early-session in-game test "disproving" drop-punch ran with the broken pre-inverse eye — its
-  conclusion was wrong and cost a detour; with the authentic eye the drop is plainly right.
+- **FINAL (2026-07-11, i860-firmware-decoded): PUNCH is a three-chunk STENCIL-CUT KIT.** The
+  VREND.MNG board firmware's 'damageize' handler (@0xf040f6f8, disassembled with a custom i860
+  tool) writes the dpl_Punchize token triple {dmg_set, undmg2enbl|texture, dmg_clear} onto the
+  punch geogroup's first three geometry chunks IN FILE ORDER: chunk1 = the detailed
+  window-aperture shapes = an invisible per-pixel MASK; chunk2 = the coarse HULL = the ONLY
+  colour-drawn geometry, drawn where NOT masked; chunk3 = a byte-identical hull twin = the
+  damage-reset record, never visible.  The visible canopy = hull-minus-apertures.  Port:
+  bgfload identifies the within-patch twin pair (hull + skip) and tags the non-paired pmeshes as
+  masks; L4D3D draws mask (stencil 1, no colour/z-write), hull (stencil-reject), mask (stencil 0)
+  on a D24S8 device; the cut never touches z, so later-drawn entities show through apertures.
+  BT_COP_PLATES=1 disables the kit (diag).  In-game, all 8 mechs on pure defaults [T2]:
+  connected dark frames with clear viewports; thor (the footage mech) shows the big central
+  viewport + surrounding frame exactly as filmed.  TWO earlier readings are superseded and were
+  WRONG: "punch patches = windows, drop them" (left floating frame fragments) and "duplicate
+  pairs = plates, hide both" (hid the HULL and drew the MASK = the inversion the user caught).
 - **Hit-bounce: LIVE and verified [T2] (2026-07-11).** The damage→gyro fan-out **FUN_004b2980**
   was re-disassembled byte-exact from the raw image (capstone; scratchpad/dis_4b2980.py) and
   reconstructed as `Gyroscope::ApplyDamageResponse` (gyro.cpp): zero-damage + Collision(0) no-op;

context/decomp-reference.md

@@ -56,7 +56,7 @@ reconciled via `CLASSMAP.md`, not the case label. [T1]
 | 0xBC1 | **Generator** | @4b… | power bus |
 | 0xBC2 | **PoweredSubsystem** | @004b0f74 | sizeof 0x31C |
 | 0xBC3 | **Sensor** | — | `case`=MyomersClassID |
-| 0xBC4 | **Gyroscope** | @004b3778 | DEFERRED (NaN integrator; reverted to stub) |
+| 0xBC4 | **Gyroscope** | @004b3778 | LIVE (task #56: byte-exact ctor/integrators/writers; hit-bounce fan-out wired) |
 | 0xBC5 | **Torso** | @004b6b0c | sizeof 0x280; `case`=SinkSource |
 | 0xBC6 | **Myomers** | @4b8fec | `case`=Actuator; INERT un-stub |
 | 0xBC8 | **Emitter** | @004b1d18 | sizeof 0x478; energy weapon |
@@ -188,6 +188,14 @@ recoil @4bc136-4bc19c (damage>3 → (0,0.6,−1.5) × damage/16; `gyroRumbleTime
 ex-"clipLoadGuard").  Byte tooling: `scratchpad/dis_4b2980.py` / `dis_range.py` over
 `reference/decomp/section_dump.txt`.
 
+**PUNCH firmware decode** [T1] (the definitive mechanism, 2026-07-11): cmd 0x20 =
+vr_damage_action (VR_PROT.H enum); the i860 firmware content/VREND.MNG (code @0xf0400000)
+handler 'damageize' @0xf040f6f8 writes the token triple onto the geogroup's first THREE
+geometry-list nodes' geometry_type@+8 IN FILE ORDER (superlist appends at tail @0xf040c620);
+DPL_PRIV.H names the roles: f_t_dam(0x92)/sca(0x05)/undamage(0x04)/f_t_undam(0x17)/
+damage_set(0x03).  Punchize triple = mask, hull, reset-twin -- the visible surface is the HULL
+with the MASK shapes stencil-cut through it.  Disassembler: scratchpad/i860dis.py.
+
 **Cockpit-eye / punch addresses** [T1] (full story: [[cockpit-view]]): eye ctor
 **`FUN_004579a8`** (part_007.c:9274 = DPLEyeRenderable; offset = segment `GetBaseOffset`
 segment+0x74, parent = parent-segment DCS; caller part_014.c:5525-66 gates on `"siteeyepoint"`);