GitHub Copilot Skill

dayz-p3d-inspector

Use when: inspect model, show me the p3d, view memory points, move points, recipe json, build p3d, round-trip p3d. Visual Recipe editor. Not structural/collision audits: dayz-p3d-audit; not textured PAA preview: dayz-3d-viewer.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download willy92wins-dayz-modding-knowledge-pack-skills_dayz-p3d-inspector-22c35fd.zip · 38 KB

Install

skills CLI npx skills add https://github.com/willy92wins/DayZ-Modding-Knowledge-Pack/tree/main/skills/dayz-p3d-inspector
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install willy92wins-dayz-modding-knowledge-pack@llmmart
Git git clone https://github.com/willy92wins/DayZ-Modding-Knowledge-Pack.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole willy92wins/dayz-modding-knowledge-pack collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

DayZ P3D Inspector — Interactive 3D Model Viewer, Editor & Builder

Full round-trip pipeline for DayZ .p3d files:

.p3d  --extract-->  Recipe JSON  --viewer-->  Edit visually  --build-->  new .p3d

Extract model data, visualize everything in Three.js, drag memory points interactively, export the edited Recipe, and rebuild a fresh .p3d from it.

Scope (and what this skill delegates)

This skill owns three things:

  1. The Recipe JSON as a single, complete data contract over a .p3d file (all LODs + memory points + axes + selections + properties + referenced paths
    • bounding box).
  2. The interactive editor (Three.js, drag&drop memory points and axis endpoints, snap-to-grid, modal Recipe export).
  3. The Recipe -> .p3d builder (the inverse of the extractor; closes the round-trip loop).

Anything else is delegated to a sibling skill — do not duplicate it here:

Task Use this skill instead
ODOL (binarized) .p3d -> MLOD (editable) external ODOL->MLOD converter (pre-step)
Visual viewer with PAA textures / glTF dayz-3d-viewer (or invoke before)
PAA <-> PNG conversion dayz-3d-viewer (paa_to_png.py)
Deep config / path / structure validation dayz-p3d-audit (post-step)
Generating a .p3d from scratch (Blender) dayz-model-pipeline
Editing / aligning proxies on a host model dayz-proxy-align

The viewer in this skill renders untextured flat-shaded geometry on purpose: its job is to make memory points, axes, selections, collision LODs, and bounds inspectable and editable. For texture-rich previews, generate the Recipe here and feed the source .p3d through dayz-3d-viewer separately.

Install Dependencies

# py3d DayZ fork >= 1.6.0. Pick ONE route; both end in the same assert below.
# NEVER `pip install py3d` (PyPI = point-cloud lib) NOR git+upstream (no guards).
#
# Route A - this pack is checked out:
pip install -e tools/py3d
# Route B - a vendored wheel is present in this skill's wheels/ directory. That wheel
# is placed by the local py3d rollout and is NOT shipped in this pack; the installer
# fails closed when it is missing, and refuses to guess when legacy wheels sit beside it.
#   python3 scripts/install_py3d.py
python3 -c "import py3d; assert getattr(py3d,'IS_DAYZ_FORK',False) and tuple(map(int,py3d.__version__.split('.')))>=(1,6,0), (py3d.__version__, py3d.__file__)"
pip install numpy --break-system-packages

Only the extractor and builder need py3d — the viewer is pure Python that emits a self-contained HTML file.

Scripts

All in this skill's scripts/ directory:

Script Purpose
p3d_inspector_extract.py P3D -> Recipe JSON extractor (all LODs, memory, axes, selections)
p3d_inspector_viewer.py Recipe JSON -> Interactive HTML viewer generator (Phase 2 — drag & drop)
p3d_inspector_build.py Recipe JSON -> .p3d builder (MLOD) with mass policy + auto-fix

Quick Start

From a real .p3d file

import sys
sys.path.insert(0, '/path/to/skill/scripts')
from p3d_inspector_extract import extract_recipe
from p3d_inspector_viewer import generate_inspector_html

recipe = extract_recipe('model.p3d', verbose=True)
generate_inspector_html(recipe, output_path='inspector.html', model_name='My Model')

Demo mode (no p3d needed)

python scripts/p3d_inspector_viewer.py --demo inspector_demo.html

CLI

# Extract recipe from p3d
python scripts/p3d_inspector_extract.py model.p3d -v -o recipe.json

# Generate viewer from recipe
python scripts/p3d_inspector_viewer.py recipe.json inspector.html

# Build .p3d from an edited Recipe
python scripts/p3d_inspector_build.py recipe.json output.p3d -v

Build Recipe -> .p3d (Python)

import json
from p3d_inspector_build import build_p3d

with open('recipe_edited.json') as f:
    recipe = json.load(f)

result = build_p3d(recipe, 'model_rebuilt.p3d', auto_fix_enabled=True, verbose=True)
# result = { "output_path", "lods_written", "fixes_applied", "warnings" }

Recipe JSON Format

The Recipe JSON is the central data contract between all pipeline stages:

{
  "meta": {
    "source": "model.p3d",
    "version": 1,
    "mode": "audit|propose|demo"
  },
  "lods": [
    {
      "type": "visual_0|visual_1|visual_2|visual_3|geometry|fire_geometry|view_geometry|landcontact|roadway|paths|hitpoints|memory|shadow",
      "resolution": 0.0,
      "num_points": 328,
      "num_faces": 640,
      "geometry": { "positions": [], "normals": [], "uvs": [], "material_groups": {} },
      "wireframe": { "positions": [], "edges": [], "faces": [] },
      "selections": { "name": { "vertices": [], "faces": [], "vertex_count": 0, "face_count": 0 } },
      "properties": { "autocenter": "0" }
    }
  ],
  "memory_points": [
    { "index": 0, "position": [x,y,z], "selections": ["name"], "category": "center|interaction|axis|placing|port|proxy|other", "label": "name" }
  ],
  "axes": {
    "axis_name": { "points": [[x1,y1,z1],[x2,y2,z2]], "direction": [dx,dy,dz], "length": 0.015 }
  },
  "bounding_box": { "min": [], "max": [], "size": [], "center": [] },
  "referenced_paths": { "textures": [], "materials": [] }
}

material_groups keys use the format "texture|material" (pipe-separated; either side may be empty). UVs are stored in glTF V-flipped convention so they render correctly in the viewer; the builder un-flips them before writing back to the .p3d.

LOD Types & Resolution Constants (BIS MLOD)

The classifier maps lod.resolution to a logical type:

Resolution Type Has geometry/wireframe? Notes
0.0..10 visual_0..3 full geometry rendered LODs
1.0e3..1.5e4 shadow wireframe shadow volumes
1.0e13 geometry wireframe physical collision; needs Component01.. + mass
1.0e15 memory points only memory points + animation axes
2.0e15 landcontact wireframe per-vertex ground contact points
3.0e15 roadway wireframe walkable surfaces
4.0e15 paths wireframe AI navigation paths
5.0e15 hitpoints wireframe named-selection destruction points
6.0e15 view_geometry wireframe line-of-sight occlusion
7.0e15 fire_geometry wireframe bullet/projectile collision

Anything else falls back to unknown_<resolution> and the builder skips it with a warning.

Builder Behaviour

  • Visual LODs — rebuilds tri faces from geometry.material_groups, re-inverts UVs back to DayZ convention (Recipe stores glTF V-flip), deduplicates per-vertex normals into a shared face-normal pool.
  • Wireframe LODs (geometry, fire_geometry, view_geometry, landcontact, roadway, paths, hitpoints, shadow) — rebuilds faces from wireframe.faces (tris / quads; N-gons are fan-triangulated), preserves properties, auto-adds autocenter=0 and class=house to the Geometry LOD only if absent.
  • Mass is applied only to geometry and fire_geometry. ViewGeo, Shadow, LandContact, Roadway, Paths, HitPoints get no per-point mass.
  • Memory LOD — ignores any lod entry of type memory in the Recipe and rebuilds from memory_points + axes, creating one Selection per unique selection name referenced in memory_points[].selections[].
  • Mass policy for Geometry/Fire LOD points (priority):
    1. lod.properties["_point_mass"] override (per-LOD float)
    2. recipe.meta.point_mass_default override (global float)
    3. Heuristic: scan referenced_paths for density keywords (metal/steel/iron=7800, wood=600, plastic=1200, default=2000 kg/m^3), then per_point = (bbox_volume * density) / num_points.
  • Auto-fix (on by default; disable with auto_fix_enabled=False or --no-autofix):
    • Detects inverted face winding in Visual LOD 0 (>50% faces with normal pointing opposite to geometric cross-product) and reverses winding on all LODs.
    • Reports every fix applied in result["fixes_applied"].
  • Deeper validation (path existence, BB anchor, action targets, Component01 coverage, etc.) is intentionally not in scope here. Pipe the freshly built .p3d through the dayz-p3d-audit skill for that.

Viewer Features

Layer Toggles

  • Visual: Flat-shaded model mesh (no textures by design — see Scope above)
  • Geometry: Green wireframe overlay showing collision LOD
  • Fire Geo: Red wireframe showing ballistic geometry
  • View Geo: Blue wireframe showing view culling geometry
  • LandContact: Yellow-green wireframe showing ground contact points
  • Roadway: Cyan wireframe showing walkable surfaces
  • Paths: Magenta wireframe showing AI navigation paths
  • HitPoints: Orange wireframe showing destruction hit points
  • Memory Pts: Colored spheres at memory point positions
  • Axes: Purple arrows showing animation axes
  • Bounds: Bounding box (cyan) + box_placing bounds (orange)
  • Labels: Floating text labels on memory points and axes
  • Grid: Reference grid
  • Wireframe: Visual mesh wireframe overlay
  • Export Recipe: Opens modal with edited Recipe JSON for copy

The 7 wireframe LOD layers are off by default; enable them as needed.

Memory Point Categories (Color-Coded)

  • Center (cyan): pos center, ce_center
  • Interaction (red): actionPos, action-related points
  • Axis (purple): Animation axis endpoints (2 points per axis)
  • Placing (orange): box_placing_min, box_placing_max
  • Port (deep orange): port_*, cable_* (LFPG electrical)
  • Proxy (gray): Proxy attachment points
  • Other (light gray): Unclassified points

Sidebar Panels

  • Points: List of all memory points with live coordinates, click to focus
  • LODs: Summary of all LODs with point/face counts and selections
  • Selections: All named selections across all LODs
  • Paths: Referenced texture/material paths with P:\ drive warnings (UX hint; for full path/structure validation use dayz-p3d-audit)

Interaction

  • Orbit: Left mouse drag on empty space
  • Pan: Right mouse button drag
  • Zoom: Scroll wheel
  • Select point: Click on a sphere -> shows info panel with coordinates
  • Drag point: Click sphere + drag -> moves it in camera-perpendicular plane
  • Snap to grid: Hold Shift while dragging to snap to grid
  • Grid size: Press 1 for 0.01m (1cm), 2 for 0.05m (5cm)
  • Focus: Click point in sidebar list -> camera flies to it
  • Export: Click "Export Recipe" -> modal with JSON, use Select All + Ctrl+C

Drag & Drop Details (Phase 2)

The drag system uses hover-based orbit disabling: when the cursor hovers over a memory point sphere, OrbitControls is pre-emptively disabled so that pointerdown on the sphere starts a drag instead of orbiting. Moving away from spheres re-enables orbit.

When dragging a memory point, the following are updated in real-time:

  • Sphere position in 3D scene
  • HTML overlay label position
  • Axis line + arrow geometry (if the point is an axis endpoint)
  • Placing bounding box (if the point is box_placing_min / box_placing_max)
  • Sidebar coordinates text
  • Recipe JSON data (R object in memory)
  • Selection info panel coordinates

A floating coordinate display shows X/Y/Z during drag. The coordinate display also shows the current snap grid size when Shift is held.

Technical Notes

Three.js Setup

  • Three.js r0.147.0 via classic UMD <script> from CDN (NOT ESM/importmap). This is intentional: when the HTML is opened from file:// on Windows Chrome, ESM <script type="module"> + import map + cross-origin CDN imports break with net::ERR_BLOCKED_BY_ORB. UMD works from file:// without any flags.
  • OrbitControls from examples/js/controls/OrbitControls.js. r0.147 is the last version that still ships UMD examples; r0.148+ removed examples/js/ in favor of ESM-only. Don't bump above r0.147 without re-introducing an ESM module wrapper or a local OrbitControls fork.
  • No CSS2DRenderer — labels use pure HTML overlay divs with Vector3.project()
  • No Box3Helper — bounding boxes use manual LineSegments
  • All materials are MeshStandardMaterial (not Basic) to support emissive on selection
  • BufferAttribute with explicit Float32Array (not Float32BufferAttribute)

Event Handling

  • Hover detection via mousemove sets ctrl.enabled=false when over a sphere
  • This prevents OrbitControls from capturing pointerdown on spheres
  • pointerdown on sphere: selects + prepares drag state
  • pointermove with >5px threshold: activates drag, creates camera-perpendicular plane
  • pointerup: ends drag, re-enables orbit
  • Drag plane created perpendicular to camera view direction through point position

Recipe Export

  • Export opens a modal with textarea containing the modified Recipe JSON
  • User clicks "Select All" then Ctrl+C to copy
  • Clipboard API is blocked on local file:// URLs, so textarea copy is the reliable path

Pipeline Integration

+-------------+     +--------------+     +--------------+     +-------------+
| OBJ/FBX/GLB | --> | Claude       | --> | Inspector    | --> | p3d_inspect |
| (raw model) |     | proposes     |     | user adjusts |     | _build.py   |
|             |     | recipe       |     | via drag&drop|     |             |
+-------------+     +--------------+     +--------------+     +-------------+
       ^                [TODO]               ^                       |
       |                                     |                       v
       |            +--------------+         | Export Recipe   +-------------+
       |            | Existing     | ------> | (audit mode)    | model.p3d   |
       +------------| .p3d file    | -- extract --> Recipe     | (MLOD)      |
                    +--------------+                            +-------------+

Round-trip edit workflow (fully working):
   p3d ---> extract ---> Recipe ---> viewer (drag&drop) ---> export ---> build ---> p3d

If the input .p3d is binarized (ODOL), convert it with an external ODOL->MLOD converter first to get an MLOD copy. After building, optionally run dayz-p3d-audit over the result for a deep structural review.

Components status:

  • Extractor (p3d_inspector_extract.py) — done (selection iteration fix applied)
  • Viewer + drag&drop (p3d_inspector_viewer.py) — done (Phase 2)
  • Builder Recipe->p3d (p3d_inspector_build.py) — done (round-trip verified)
  • Smart proposal (raw mesh -> Recipe with inferred memory points/selections) — TODO

Planned Features

Phase 3: Selection Painting

  • Color faces by selection membership
  • Click faces to assign to selections
  • Face winding validation (red=inverted, green=correct)
  • Component01 coverage check

Existing tooling: the selection painter in dayz-animation-pipeline (references/selection-painter-for-actions.md, used on A6_SR2M to repaint the bolt/trigger selections with py3d write-back) already covers interactive face painting — start from there instead of implementing this phase from scratch.

Phase 4: Animation Preview

  • Parse model.cfg animations
  • Interactive sliders for animation phases
  • Material state toggles (LED on/off/color)
  • Live preview of animated selections

Known Limitations

  • Only MLOD .p3d files supported (not ODOL/binarized — pre-process via an external ODOL->MLOD converter).
  • Viewer renders untextured flat-shaded geometry by design — for textured previews use dayz-3d-viewer separately.
  • Clipboard API blocked on file:// URLs — use textarea Select All + Ctrl+C.
  • Drag works on the camera-perpendicular plane (no axis-lock yet).
  • Extractor does not capture per-point mass (Geometry/Fire LODs); the builder fills it via the material-density heuristic. To preserve exact masses from an existing .p3d, add them to the Recipe manually (via lod.properties["_point_mass"]) or pass a global recipe.meta.point_mass_default.
  • Builder does not yet write proxies, sharp edges, or #UVSet# tags beyond what py3d emits automatically. For placing/orienting proxies on a host model use dayz-proxy-align.

Changelog

v4.1 — Viewer fix for file:// (Windows Chrome ORB)

  • FIX Viewer used <script type="module"> + import map + ESM imports from cdn.jsdelivr.net/npm/three@0.160.0. When the HTML was opened from file:// (typical case: user double-clicks the file on Windows), Chrome's Opaque Resource Blocking refused the OrbitControls cross-origin module fetch with net::ERR_BLOCKED_BY_ORB. The whole script tag failed silently — window.TL was undefined, no canvas appeared, no toolbar buttons worked.
  • NEW Switched to Three.js r0.147.0 UMD via classic <script src> loaders, which load from file:// without any browser flags. Same scene, same drag&drop, same APIs (T = THREE alias keeps the rest of the code unchanged). r0.147 is the last version with UMD examples/js/ shipped.

v4 — Correct LOD classifier (BIS 1e15 family)

  • FIX classify_lod() and the builder's LOD_RESOLUTION map were using the wrong constants for FireGeometry (was 2.0e13, should be 7.0e15) and ViewGeometry (was 3.0e13, should be 6.0e15), and a resolution > 1.0e14 catch-all bucketed every special LOD as memory. On real .p3d files this collapsed Memory + LandContact + Roadway + Paths + HitPoints + ViewGeo + FireGeo into a single memory type, then sequentially overwrote recipe.memory_points from each — so the genuine memory points were lost.
  • NEW Full BIS MLOD 1e15-family support: memory (1e15), landcontact (2e15), roadway (3e15), paths (4e15), hitpoints (5e15), view_geometry (6e15), fire_geometry (7e15). The extractor stores wireframe data for all of them; the builder rebuilds them with the correct resolution.
  • NEW Mass policy clarified: only geometry and fire_geometry receive per-point mass; LandContact, Roadway, Paths, HitPoints, ViewGeo and Shadow do not.
  • NEW Viewer toolbar: 4 new toggles (LandContact yellow-green, Roadway cyan, Paths magenta, HitPoints orange), off by default.
  • DOCS New "LOD Types & Resolution Constants (BIS MLOD)" reference table.

v3 — Scope realignment

  • NEW "Scope" section — explicit list of what this skill owns vs. what it delegates to dayz-3d-viewer, dayz-p3d-audit, and dayz-model-pipeline. Removes documentation drift / overlap with sibling skills.
  • NEW Pipeline integration note pointing at the external ODOL->MLOD converter (pre) and dayz-p3d-audit (post).
  • DOCS "Texture rendering in viewer — TODO" reframed as a deliberate scope decision (delegated to dayz-3d-viewer).
  • DOCS Builder validation policy explicitly delegates deep structural checks to dayz-p3d-audit.
  • DOCS Aligned all documented signatures with the real code (build_p3d(..., auto_fix_enabled=True, ...)).

v2 — Builder + Extractor fix

  • NEW p3d_inspector_build.py — Recipe JSON -> .p3d (MLOD) builder. Supports all Recipe LOD types, mass-by-density, auto-fix winding. Round-trip verified against demo recipe (memory points, axes, selections, properties all preserved bit-for-bit — demo recipe only; real models: Memory-selection loss documented in SP-002).
  • FIX p3d_inspector_extract.py — extract_selections() and extract_memory_data() iterated lod.selections as if the values were Selection objects with a .name attribute. In the current py3d API lod.selections is an OrderedDict that yields string keys on iteration, and each Selection.points / .faces is a {Point|Face: weight} dict (not indexable). The old code crashed with AttributeError: 'str' object has no attribute 'name' on any real .p3d file. Fixed by iterating .items() and mapping Point / Face object identities back to LOD-local indices via id() lookup tables.

Memory selection round-trip + collision winding (added 2026-05-23)

Round-trip is NOT lossless for Memory selections (SP-002)

The build path can lose/mis-write Memory-LOD selection membership: build_memory_lod() reconstructs the Memory LOD from recipe.memory_points[].selections + recipe.axes, but the extractor leaves those empty on real models — the real membership lives in recipe.lods[memory].selections, which the builder IGNORES → a rebuild can wipe memory selections (axes, dmgzones, crew, proxies) while names/geometry still look fine. Before any irreversible rebuild, do a round-trip test (extract→build→re-extract) and compare selection COUNTS, not just names. Mitigation for a .p3d with critical memory selections: edit the MLOD with py3d directly and write with py3d, bypassing the recipe→build round-trip. (The inspector remains fine for inspection/visualization.)

Collision LOD winding is read per component, never matched to Visual (SP-003)

When generating/editing a collision LOD, run dayz-model-pipeline Rule 18's per-component check before deploying: every non-proxy face must sit in a closed, convex ComponentNN and read INWARD (DayZ left-handed); a LOD short of those prerequisites, or with a degenerate face, is unresolved, not healthy. The relative check against the Visual LOD (py3d ERR_WINDING_INVERTED) only triggers it. Reverse only the faces that read outward, and set their stored normals as dayz-p3d-audit killer #1's Fix says (dayz-model-pipeline SP-003). (Aligned 2026-10-02 with dayz-p3d-audit killer #1: this section was titled "Collision LOD winding must match Visual (SP-003)" and read: "When generating/editing a collision LOD, compare its winding sign against the Visual LOD (centroid method) before deploying — they must match (~100% INWARD, DayZ left-handed).")

(added 2026-06-01) Stale recipe after external edits to .p3d (SP-022)

Recipe JSON can get out of sync with actual .p3d if .p3d was edited by another tool (Object Builder, direct py3d, external ODOL->MLOD converter) without re-extracting recipe. Before reporting a bug from inspector view:

  1. Re-extract recipe with extract_recipe.py and compare structurally with cached version.
  2. If they differ, source of truth is .p3d, not recipe.
  3. If recipe is identical but viewer shows something "strange", verify direct py3d round-trip before claiming bug.

Origin: introspection 2026-06-01 §B-6; kt_roadkill_armed session Sprint G' 2026-05-31.

py3d selections API gotcha (OrderedDict, non-subscriptable points/faces)

lod.selections is an OrderedDict keyed by selection name. Iterating it gives string keys, not Selection objects. Each Selection.points and .faces is a dict {Point | Face: weight} — NOT index-subscriptable. To find LOD-local indices you must build id() lookup tables.

The extractor handles this correctly. If you see AttributeError: 'str' object has no attribute 'name' or TypeError: 'Selection' object is not subscriptable, you're looking at old/stale code — use the version in this skill.

Recipe selection indexing - vertices = point-pool, NOT triangle-soup (SP-028, added 2026-07-14)

selections[].vertices in the Recipe indexes the LOD's UNIQUE POINT POOL (0..len(lod.points)-1). geometry.positions is TRIANGLE-SOUP (3 entries per face, len = num_faces*3). Indexing positions with selection vertices yields coherent-looking but WRONG coordinates (it lands on unrelated real geometry), producing false structural alarms ("selection points at the wrong mesh").

Before declaring any selection/structure bug from Recipe data, verify at the py3d object level: load the .p3d, take lod.selections[name].faces, read each face's vertices[].point_index coords, and bbox THOSE. That is engine truth. Origin: kt_roadkill_armed 2026-06-07 false P1 (turret_yaw "was" the car spikes; the model was correct all along). Cross-ref SP-002, LL-111.

Rules promoted from lessons corpus (added 2026-07-27)

Promoted from AI/20_Knowledge/lessons-learned.md to arrive via trigger instead of depending on someone remembering to look them up. Each rule cites source LL-NNN; complete entry (symptom, origin, evidence) lives there. Do not remove citation: the index lessons-index.md detects promotion by looking for that reference inside skills.

  • LL-109 — For round-trips that normalize, sort, or deduplicate, test f(f(x)) == f(x) and define separately which fields must be stable from first pass. Document any allowed renormalization.

Round-trip caveat

Memory selections may not survive the extract → edit → rebuild cycle (SP-002). Verify selection membership after a rebuild, not just selection names.

  • LL-010 — Before asserting a piece is missing, enumerate .p3d proxies, inspect their sizes, and open substantial candidates. Config only reveals what is rigged; debinarize and split connected components if geometry lives in a proxy.
  • LL-177 — Before extracting selections or corrected geometry, locate actual edited file —including backups marking intervention— and have pipeline read that copy. Do not validate provenance solely because bbox looks coherent.

Non-semantic MLOD face padding (SP-229, added 2026-08-31)

An MLOD face record always reserves four vertex slots. A triangular face leaves the fourth slot unused, and Object Builder can leave non-zero bytes there after face reordering or editing. Those bytes carry no face data and binarization discards them. Source: p3dtxt/README.md:11 and p3dtxt/src/main.rs:38-42.

A changed .p3d hash after a rewrite therefore does not by itself prove data loss. For an MLOD round-trip, compare parsed fields while ignoring the unused fourth slot of triangles, or binarize both versions and compare the resulting ODOL semantics. Keep byte identity only for producers that explicitly promise canonical zero padding. This caveat is separate from the Memory-selection loss described in SP-002.

Measure visibility by AREA sampling, not by a centroid ray (SP-446, added 2026-09-28)

[EXACT] To decide whether a selection is visible from outside, cast rays from random points across the whole face (order of 3000 per LOD) and report the free-area percentage; a single ray from the centroid lies. Measured on a heater model: centroid rays reported "48/48 blocked in all 6 directions" while area sampling showed 84-86 % free — every face was a long thin triangle whose centroid sat behind a 1-2 mm wire. The false diagnosis nearly triggered rebuilding the model (the emissive grid) instead of fixing the config.

Files (dayz-modding-knowledge-pack)
  • scripts
    • install_py3d.py 8.3 KB
      Loading…
    • p3d_inspector_build.py 19.5 KB
      Loading…
    • p3d_inspector_extract.py 20.5 KB
      Loading…
    • p3d_inspector_viewer.py 39.5 KB
      Loading…
  • tests
    • test_install_py3d.py 4.6 KB
      Loading…
  • SKILL.md 26.8 KB
    ---
    name: dayz-p3d-inspector
    description: "Use when: inspect model, show me the p3d, view memory points, move points, recipe json, build p3d, round-trip p3d. Visual Recipe editor. Not structural/collision audits: dayz-p3d-audit; not textured PAA preview: dayz-3d-viewer."
    ---
    
    # DayZ P3D Inspector — Interactive 3D Model Viewer, Editor & Builder
    
    Full round-trip pipeline for DayZ .p3d files:
    
    ```
    .p3d  --extract-->  Recipe JSON  --viewer-->  Edit visually  --build-->  new .p3d
    ```
    
    Extract model data, visualize everything in Three.js, drag memory points
    interactively, export the edited Recipe, and rebuild a fresh .p3d from it.
    
    ## Scope (and what this skill delegates)
    
    This skill **owns** three things:
    
    1. The **Recipe JSON** as a single, complete data contract over a .p3d file
       (all LODs + memory points + axes + selections + properties + referenced paths
       + bounding box).
    2. The **interactive editor** (Three.js, drag&drop memory points and axis
       endpoints, snap-to-grid, modal Recipe export).
    3. The **Recipe -> .p3d builder** (the inverse of the extractor; closes the
       round-trip loop).
    
    Anything else is delegated to a sibling skill — do **not** duplicate it here:
    
    | Task                                      | Use this skill instead                  |
    |-------------------------------------------|-----------------------------------------|
    | ODOL (binarized) .p3d -> MLOD (editable)  | external ODOL->MLOD converter (pre-step) |
    | Visual viewer with PAA textures / glTF    | `dayz-3d-viewer` (or invoke before)     |
    | PAA <-> PNG conversion                    | `dayz-3d-viewer` (`paa_to_png.py`)      |
    | Deep config / path / structure validation | `dayz-p3d-audit` (post-step)            |
    | Generating a .p3d from scratch (Blender)  | `dayz-model-pipeline`                   |
    | Editing / aligning proxies on a host model | `dayz-proxy-align`                     |
    
    The viewer in this skill renders untextured flat-shaded geometry on purpose:
    its job is to make memory points, axes, selections, collision LODs, and bounds
    inspectable and editable. For texture-rich previews, generate the Recipe here
    and feed the source .p3d through `dayz-3d-viewer` separately.
    
    ## Install Dependencies
    
    ```bash
    # py3d DayZ fork >= 1.6.0. Pick ONE route; both end in the same assert below.
    # NEVER `pip install py3d` (PyPI = point-cloud lib) NOR git+upstream (no guards).
    #
    # Route A - this pack is checked out:
    pip install -e tools/py3d
    # Route B - a vendored wheel is present in this skill's wheels/ directory. That wheel
    # is placed by the local py3d rollout and is NOT shipped in this pack; the installer
    # fails closed when it is missing, and refuses to guess when legacy wheels sit beside it.
    #   python3 scripts/install_py3d.py
    python3 -c "import py3d; assert getattr(py3d,'IS_DAYZ_FORK',False) and tuple(map(int,py3d.__version__.split('.')))>=(1,6,0), (py3d.__version__, py3d.__file__)"
    pip install numpy --break-system-packages
    ```
    
    Only the extractor and builder need py3d — the viewer is pure Python that
    emits a self-contained HTML file.
    
    ## Scripts
    
    All in this skill's `scripts/` directory:
    
    | Script | Purpose |
    |--------|---------|
    | `p3d_inspector_extract.py` | P3D -> Recipe JSON extractor (all LODs, memory, axes, selections) |
    | `p3d_inspector_viewer.py`  | Recipe JSON -> Interactive HTML viewer generator (Phase 2 — drag & drop) |
    | `p3d_inspector_build.py`   | Recipe JSON -> .p3d builder (MLOD) with mass policy + auto-fix |
    
    ## Quick Start
    
    ### From a real .p3d file
    
    ```python
    import sys
    sys.path.insert(0, '/path/to/skill/scripts')
    from p3d_inspector_extract import extract_recipe
    from p3d_inspector_viewer import generate_inspector_html
    
    recipe = extract_recipe('model.p3d', verbose=True)
    generate_inspector_html(recipe, output_path='inspector.html', model_name='My Model')
    ```
    
    ### Demo mode (no p3d needed)
    
    ```bash
    python scripts/p3d_inspector_viewer.py --demo inspector_demo.html
    ```
    
    ### CLI
    
    ```bash
    # Extract recipe from p3d
    python scripts/p3d_inspector_extract.py model.p3d -v -o recipe.json
    
    # Generate viewer from recipe
    python scripts/p3d_inspector_viewer.py recipe.json inspector.html
    
    # Build .p3d from an edited Recipe
    python scripts/p3d_inspector_build.py recipe.json output.p3d -v
    ```
    
    ### Build Recipe -> .p3d (Python)
    
    ```python
    import json
    from p3d_inspector_build import build_p3d
    
    with open('recipe_edited.json') as f:
        recipe = json.load(f)
    
    result = build_p3d(recipe, 'model_rebuilt.p3d', auto_fix_enabled=True, verbose=True)
    # result = { "output_path", "lods_written", "fixes_applied", "warnings" }
    ```
    
    ## Recipe JSON Format
    
    The Recipe JSON is the central data contract between all pipeline stages:
    
    ```json
    {
      "meta": {
        "source": "model.p3d",
        "version": 1,
        "mode": "audit|propose|demo"
      },
      "lods": [
        {
          "type": "visual_0|visual_1|visual_2|visual_3|geometry|fire_geometry|view_geometry|landcontact|roadway|paths|hitpoints|memory|shadow",
          "resolution": 0.0,
          "num_points": 328,
          "num_faces": 640,
          "geometry": { "positions": [], "normals": [], "uvs": [], "material_groups": {} },
          "wireframe": { "positions": [], "edges": [], "faces": [] },
          "selections": { "name": { "vertices": [], "faces": [], "vertex_count": 0, "face_count": 0 } },
          "properties": { "autocenter": "0" }
        }
      ],
      "memory_points": [
        { "index": 0, "position": [x,y,z], "selections": ["name"], "category": "center|interaction|axis|placing|port|proxy|other", "label": "name" }
      ],
      "axes": {
        "axis_name": { "points": [[x1,y1,z1],[x2,y2,z2]], "direction": [dx,dy,dz], "length": 0.015 }
      },
      "bounding_box": { "min": [], "max": [], "size": [], "center": [] },
      "referenced_paths": { "textures": [], "materials": [] }
    }
    ```
    
    `material_groups` keys use the format `"texture|material"` (pipe-separated; either side may
    be empty). UVs are stored in glTF V-flipped convention so they render correctly in the
    viewer; the builder un-flips them before writing back to the .p3d.
    
    ## LOD Types & Resolution Constants (BIS MLOD)
    
    The classifier maps `lod.resolution` to a logical type:
    
    | Resolution | Type | Has geometry/wireframe? | Notes |
    |------------|------|-------------------------|-------|
    | `0.0..10`        | `visual_0..3`     | full geometry  | rendered LODs |
    | `1.0e3..1.5e4`   | `shadow`          | wireframe      | shadow volumes |
    | `1.0e13`         | `geometry`        | wireframe      | physical collision; needs `Component01..` + mass |
    | `1.0e15`         | `memory`          | points only    | memory points + animation axes |
    | `2.0e15`         | `landcontact`     | wireframe      | per-vertex ground contact points |
    | `3.0e15`         | `roadway`         | wireframe      | walkable surfaces |
    | `4.0e15`         | `paths`           | wireframe      | AI navigation paths |
    | `5.0e15`         | `hitpoints`       | wireframe      | named-selection destruction points |
    | `6.0e15`         | `view_geometry`   | wireframe      | line-of-sight occlusion |
    | `7.0e15`         | `fire_geometry`   | wireframe      | bullet/projectile collision |
    
    Anything else falls back to `unknown_<resolution>` and the builder skips it
    with a warning.
    
    ## Builder Behaviour
    
    - **Visual LODs** — rebuilds tri faces from `geometry.material_groups`, re-inverts
      UVs back to DayZ convention (Recipe stores glTF V-flip), deduplicates per-vertex
      normals into a shared face-normal pool.
    - **Wireframe LODs** (`geometry`, `fire_geometry`, `view_geometry`, `landcontact`,
      `roadway`, `paths`, `hitpoints`, `shadow`) — rebuilds faces from `wireframe.faces`
      (tris / quads; N-gons are fan-triangulated), preserves `properties`, auto-adds
      `autocenter=0` and `class=house` to the Geometry LOD only if absent.
    - **Mass** is applied **only** to `geometry` and `fire_geometry`. ViewGeo,
      Shadow, LandContact, Roadway, Paths, HitPoints get no per-point mass.
    - **Memory LOD** — ignores any `lod` entry of type `memory` in the Recipe and
      rebuilds from `memory_points` + `axes`, creating one Selection per unique
      selection name referenced in `memory_points[].selections[]`.
    - **Mass policy** for Geometry/Fire LOD points (priority):
      1. `lod.properties["_point_mass"]` override (per-LOD float)
      2. `recipe.meta.point_mass_default` override (global float)
      3. Heuristic: scan `referenced_paths` for density keywords
         (metal/steel/iron=7800, wood=600, plastic=1200, default=2000 kg/m^3),
         then `per_point = (bbox_volume * density) / num_points`.
    - **Auto-fix** (on by default; disable with `auto_fix_enabled=False` or `--no-autofix`):
      - Detects inverted face winding in Visual LOD 0 (>50% faces with normal pointing
        opposite to geometric cross-product) and reverses winding on **all** LODs.
      - Reports every fix applied in `result["fixes_applied"]`.
    - **Deeper validation** (path existence, BB anchor, action targets, Component01
      coverage, etc.) is intentionally **not** in scope here. Pipe the freshly built
      .p3d through the `dayz-p3d-audit` skill for that.
    
    ## Viewer Features
    
    ### Layer Toggles
    - **Visual**: Flat-shaded model mesh (no textures by design — see Scope above)
    - **Geometry**: Green wireframe overlay showing collision LOD
    - **Fire Geo**: Red wireframe showing ballistic geometry
    - **View Geo**: Blue wireframe showing view culling geometry
    - **LandContact**: Yellow-green wireframe showing ground contact points
    - **Roadway**: Cyan wireframe showing walkable surfaces
    - **Paths**: Magenta wireframe showing AI navigation paths
    - **HitPoints**: Orange wireframe showing destruction hit points
    - **Memory Pts**: Colored spheres at memory point positions
    - **Axes**: Purple arrows showing animation axes
    - **Bounds**: Bounding box (cyan) + box_placing bounds (orange)
    - **Labels**: Floating text labels on memory points and axes
    - **Grid**: Reference grid
    - **Wireframe**: Visual mesh wireframe overlay
    - **Export Recipe**: Opens modal with edited Recipe JSON for copy
    
    The 7 wireframe LOD layers are off by default; enable them as needed.
    
    ### Memory Point Categories (Color-Coded)
    - **Center** (cyan): `pos center`, `ce_center`
    - **Interaction** (red): `actionPos`, action-related points
    - **Axis** (purple): Animation axis endpoints (2 points per axis)
    - **Placing** (orange): `box_placing_min`, `box_placing_max`
    - **Port** (deep orange): `port_*`, `cable_*` (LFPG electrical)
    - **Proxy** (gray): Proxy attachment points
    - **Other** (light gray): Unclassified points
    
    ### Sidebar Panels
    - **Points**: List of all memory points with live coordinates, click to focus
    - **LODs**: Summary of all LODs with point/face counts and selections
    - **Selections**: All named selections across all LODs
    - **Paths**: Referenced texture/material paths with `P:\` drive warnings (UX hint;
      for full path/structure validation use `dayz-p3d-audit`)
    
    ### Interaction
    - **Orbit**: Left mouse drag on empty space
    - **Pan**: Right mouse button drag
    - **Zoom**: Scroll wheel
    - **Select point**: Click on a sphere -> shows info panel with coordinates
    - **Drag point**: Click sphere + drag -> moves it in camera-perpendicular plane
    - **Snap to grid**: Hold **Shift** while dragging to snap to grid
    - **Grid size**: Press **1** for 0.01m (1cm), **2** for 0.05m (5cm)
    - **Focus**: Click point in sidebar list -> camera flies to it
    - **Export**: Click "Export Recipe" -> modal with JSON, use Select All + Ctrl+C
    
    ### Drag & Drop Details (Phase 2)
    
    The drag system uses hover-based orbit disabling: when the cursor hovers over a memory
    point sphere, OrbitControls is pre-emptively disabled so that pointerdown on the sphere
    starts a drag instead of orbiting. Moving away from spheres re-enables orbit.
    
    When dragging a memory point, the following are updated in real-time:
    - Sphere position in 3D scene
    - HTML overlay label position
    - Axis line + arrow geometry (if the point is an axis endpoint)
    - Placing bounding box (if the point is `box_placing_min` / `box_placing_max`)
    - Sidebar coordinates text
    - Recipe JSON data (R object in memory)
    - Selection info panel coordinates
    
    A floating coordinate display shows X/Y/Z during drag. The coordinate display also
    shows the current snap grid size when Shift is held.
    
    ## Technical Notes
    
    ### Three.js Setup
    - Three.js **r0.147.0** via classic UMD `<script>` from CDN (NOT ESM/importmap).
      This is intentional: when the HTML is opened from `file://` on Windows Chrome,
      ESM `<script type="module">` + import map + cross-origin CDN imports break
      with `net::ERR_BLOCKED_BY_ORB`. UMD works from `file://` without any flags.
    - OrbitControls from `examples/js/controls/OrbitControls.js`. r0.147 is the
      last version that still ships UMD examples; r0.148+ removed `examples/js/`
      in favor of ESM-only. Don't bump above r0.147 without re-introducing an ESM
      module wrapper or a local OrbitControls fork.
    - No CSS2DRenderer — labels use pure HTML overlay divs with `Vector3.project()`
    - No Box3Helper — bounding boxes use manual LineSegments
    - All materials are MeshStandardMaterial (not Basic) to support emissive on selection
    - BufferAttribute with explicit Float32Array (not Float32BufferAttribute)
    
    ### Event Handling
    - Hover detection via mousemove sets `ctrl.enabled=false` when over a sphere
    - This prevents OrbitControls from capturing pointerdown on spheres
    - pointerdown on sphere: selects + prepares drag state
    - pointermove with >5px threshold: activates drag, creates camera-perpendicular plane
    - pointerup: ends drag, re-enables orbit
    - Drag plane created perpendicular to camera view direction through point position
    
    ### Recipe Export
    - Export opens a modal with textarea containing the modified Recipe JSON
    - User clicks "Select All" then Ctrl+C to copy
    - Clipboard API is blocked on local file:// URLs, so textarea copy is the reliable path
    
    ## Pipeline Integration
    
    ```
    +-------------+     +--------------+     +--------------+     +-------------+
    | OBJ/FBX/GLB | --> | Claude       | --> | Inspector    | --> | p3d_inspect |
    | (raw model) |     | proposes     |     | user adjusts |     | _build.py   |
    |             |     | recipe       |     | via drag&drop|     |             |
    +-------------+     +--------------+     +--------------+     +-------------+
           ^                [TODO]               ^                       |
           |                                     |                       v
           |            +--------------+         | Export Recipe   +-------------+
           |            | Existing     | ------> | (audit mode)    | model.p3d   |
           +------------| .p3d file    | -- extract --> Recipe     | (MLOD)      |
                        +--------------+                            +-------------+
    
    Round-trip edit workflow (fully working):
       p3d ---> extract ---> Recipe ---> viewer (drag&drop) ---> export ---> build ---> p3d
    ```
    
    If the input .p3d is binarized (ODOL), convert it with an external ODOL->MLOD converter first to get an
    MLOD copy. After building, optionally run `dayz-p3d-audit` over the result for a
    deep structural review.
    
    Components status:
    - **Extractor** (`p3d_inspector_extract.py`) — done (selection iteration fix applied)
    - **Viewer + drag&drop** (`p3d_inspector_viewer.py`) — done (Phase 2)
    - **Builder Recipe->p3d** (`p3d_inspector_build.py`) — done (round-trip verified)
    - **Smart proposal** (raw mesh -> Recipe with inferred memory points/selections) — TODO
    
    ## Planned Features
    
    ### Phase 3: Selection Painting
    - Color faces by selection membership
    - Click faces to assign to selections
    - Face winding validation (red=inverted, green=correct)
    - Component01 coverage check
    
    Existing tooling: the selection painter in `dayz-animation-pipeline`
    (`references/selection-painter-for-actions.md`, used on A6_SR2M to repaint the
    `bolt`/`trigger` selections with py3d write-back) already covers interactive
    face painting — start from there instead of implementing this phase from scratch.
    
    ### Phase 4: Animation Preview
    - Parse `model.cfg` animations
    - Interactive sliders for animation phases
    - Material state toggles (LED on/off/color)
    - Live preview of animated selections
    
    ## Known Limitations
    
    - Only MLOD .p3d files supported (not ODOL/binarized — pre-process via an
      external ODOL->MLOD converter).
    - Viewer renders untextured flat-shaded geometry by design — for textured
      previews use `dayz-3d-viewer` separately.
    - Clipboard API blocked on file:// URLs — use textarea Select All + Ctrl+C.
    - Drag works on the camera-perpendicular plane (no axis-lock yet).
    - Extractor does not capture per-point `mass` (Geometry/Fire LODs); the builder
      fills it via the material-density heuristic. To preserve exact masses from an
      existing .p3d, add them to the Recipe manually (via `lod.properties["_point_mass"]`)
      or pass a global `recipe.meta.point_mass_default`.
    - Builder does not yet write proxies, sharp edges, or `#UVSet#` tags beyond
      what py3d emits automatically. For placing/orienting proxies on a host model
      use `dayz-proxy-align`.
    
    ## Changelog
    
    ### v4.1 — Viewer fix for `file://` (Windows Chrome ORB)
    
    - **FIX** Viewer used `<script type="module">` + import map + ESM imports from
      `cdn.jsdelivr.net/npm/three@0.160.0`. When the HTML was opened from `file://`
      (typical case: user double-clicks the file on Windows), Chrome's Opaque
      Resource Blocking refused the OrbitControls cross-origin module fetch with
      `net::ERR_BLOCKED_BY_ORB`. The whole script tag failed silently — `window.TL`
      was undefined, no canvas appeared, no toolbar buttons worked.
    - **NEW** Switched to Three.js **r0.147.0** UMD via classic `<script src>`
      loaders, which load from `file://` without any browser flags. Same scene,
      same drag&drop, same APIs (`T = THREE` alias keeps the rest of the code
      unchanged). r0.147 is the last version with UMD `examples/js/` shipped.
    
    ### v4 — Correct LOD classifier (BIS 1e15 family)
    
    - **FIX** `classify_lod()` and the builder's `LOD_RESOLUTION` map were using
      the wrong constants for FireGeometry (was `2.0e13`, should be `7.0e15`) and
      ViewGeometry (was `3.0e13`, should be `6.0e15`), and a `resolution > 1.0e14`
      catch-all bucketed every special LOD as `memory`. On real .p3d files this
      collapsed Memory + LandContact + Roadway + Paths + HitPoints + ViewGeo +
      FireGeo into a single `memory` type, then sequentially overwrote
      `recipe.memory_points` from each — so the genuine memory points were lost.
    - **NEW** Full BIS MLOD 1e15-family support: `memory` (1e15), `landcontact` (2e15),
      `roadway` (3e15), `paths` (4e15), `hitpoints` (5e15), `view_geometry` (6e15),
      `fire_geometry` (7e15). The extractor stores wireframe data for all of them;
      the builder rebuilds them with the correct resolution.
    - **NEW** Mass policy clarified: only `geometry` and `fire_geometry` receive
      per-point mass; LandContact, Roadway, Paths, HitPoints, ViewGeo and Shadow
      do not.
    - **NEW** Viewer toolbar: 4 new toggles (LandContact yellow-green, Roadway
      cyan, Paths magenta, HitPoints orange), off by default.
    - **DOCS** New "LOD Types & Resolution Constants (BIS MLOD)" reference table.
    
    ### v3 — Scope realignment
    
    - **NEW** "Scope" section — explicit list of what this skill owns vs. what it
      delegates to `dayz-3d-viewer`, `dayz-p3d-audit`, and
      `dayz-model-pipeline`. Removes documentation drift / overlap with sibling skills.
    - **NEW** Pipeline integration note pointing at the external ODOL->MLOD converter (pre)
      and `dayz-p3d-audit` (post).
    - **DOCS** "Texture rendering in viewer — TODO" reframed as a deliberate scope
      decision (delegated to `dayz-3d-viewer`).
    - **DOCS** Builder validation policy explicitly delegates deep structural checks
      to `dayz-p3d-audit`.
    - **DOCS** Aligned all documented signatures with the real code
      (`build_p3d(..., auto_fix_enabled=True, ...)`).
    
    ### v2 — Builder + Extractor fix
    
    - **NEW** `p3d_inspector_build.py` — Recipe JSON -> .p3d (MLOD) builder.
      Supports all Recipe LOD types, mass-by-density, auto-fix winding. Round-trip
      verified against demo recipe (memory points, axes, selections, properties
      all preserved bit-for-bit — demo recipe only; real models: Memory-selection
      loss documented in SP-002).
    - **FIX** `p3d_inspector_extract.py` — `extract_selections()` and
      `extract_memory_data()` iterated `lod.selections` as if the values were
      Selection objects with a `.name` attribute. In the current py3d API
      `lod.selections` is an `OrderedDict` that yields string keys on iteration,
      and each `Selection.points` / `.faces` is a `{Point|Face: weight}` dict
      (not indexable). The old code crashed with `AttributeError: 'str' object
      has no attribute 'name'` on any real .p3d file. Fixed by iterating
      `.items()` and mapping `Point` / `Face` object identities back to LOD-local
      indices via `id()` lookup tables.
    
    ## Memory selection round-trip + collision winding (added 2026-05-23)
    
    ### Round-trip is NOT lossless for Memory selections (SP-002)
    The build path can lose/mis-write Memory-LOD selection membership: `build_memory_lod()`
    reconstructs the Memory LOD from `recipe.memory_points[].selections` + `recipe.axes`, but the
    extractor leaves those empty on real models — the real membership lives in
    `recipe.lods[memory].selections`, which the builder IGNORES → a rebuild can wipe memory
    selections (axes, dmgzones, crew, proxies) while names/geometry still look fine. Before any
    irreversible rebuild, do a round-trip test (extract→build→re-extract) and compare selection
    COUNTS, not just names. Mitigation for a .p3d with critical memory selections: edit the MLOD
    with py3d directly and write with py3d, bypassing the recipe→build round-trip. (The inspector
    remains fine for inspection/visualization.)
    
    ### Collision LOD winding is read per component, never matched to Visual (SP-003)
    When generating/editing a collision LOD, run `dayz-model-pipeline` Rule 18's per-component check
    before deploying: every non-proxy face must sit in a closed, convex `ComponentNN` and read
    INWARD (DayZ left-handed); a LOD short of those prerequisites, or with a degenerate face, is
    unresolved, not healthy. The relative check against the Visual LOD (py3d `ERR_WINDING_INVERTED`)
    only triggers it. Reverse only the faces that read outward, and set their stored normals as
    `dayz-p3d-audit` killer #1's **Fix** says (`dayz-model-pipeline` SP-003).
    *(Aligned 2026-10-02 with `dayz-p3d-audit` killer #1: this section was titled "Collision LOD
    winding must match Visual (SP-003)" and read: "When generating/editing a collision LOD, compare
    its winding sign against the Visual LOD (centroid method) before deploying — they must match
    (~100% INWARD, DayZ left-handed).")*
    
    ## (added 2026-06-01) Stale recipe after external edits to .p3d (SP-022)
    
    Recipe JSON can get out of sync with actual `.p3d` if `.p3d` was edited
    by another tool (Object Builder, direct py3d, external ODOL->MLOD converter) without re-extracting
    recipe. Before reporting a bug from inspector view:
    
    1. Re-extract recipe with `extract_recipe.py` and compare structurally with
       cached version.
    2. If they differ, source of truth is `.p3d`, not recipe.
    3. If recipe is identical but viewer shows something "strange", verify
       direct py3d round-trip before claiming bug.
    
    Origin: introspection 2026-06-01 §B-6; kt_roadkill_armed session Sprint G' 2026-05-31.
    
    <!-- [merged 2026-06-05 from <claude-home>\skills user copy during plugin-canonical migration; almacen: .claude\skills] -->
    ## py3d `selections` API gotcha (OrderedDict, non-subscriptable points/faces)
    
    `lod.selections` is an **OrderedDict** keyed by selection name. Iterating it
    gives string keys, not Selection objects. Each `Selection.points` and
    `.faces` is a **dict** `{Point | Face: weight}` — NOT index-subscriptable.
    To find LOD-local indices you must build `id()` lookup tables.
    
    The extractor handles this correctly. If you see `AttributeError: 'str'
    object has no attribute 'name'` or `TypeError: 'Selection' object is not
    subscriptable`, you're looking at old/stale code — use the version in
    this skill.
    
    ## Recipe selection indexing - vertices = point-pool, NOT triangle-soup (SP-028, added 2026-07-14)
    
    `selections[].vertices` in the Recipe indexes the LOD's UNIQUE POINT POOL (0..len(lod.points)-1). `geometry.positions` is TRIANGLE-SOUP (3 entries per face, len = num_faces*3). Indexing `positions` with selection vertices yields coherent-looking but WRONG coordinates (it lands on unrelated real geometry), producing false structural alarms ("selection points at the wrong mesh").
    
    Before declaring any selection/structure bug from Recipe data, verify at the py3d object level: load the .p3d, take `lod.selections[name].faces`, read each face's `vertices[].point_index` coords, and bbox THOSE. That is engine truth. Origin: kt_roadkill_armed 2026-06-07 false P1 (turret_yaw "was" the car spikes; the model was correct all along). Cross-ref SP-002, LL-111.
    
    ## Rules promoted from lessons corpus (added 2026-07-27)
    
    Promoted from `AI/20_Knowledge/lessons-learned.md` to arrive via trigger instead
    of depending on someone remembering to look them up. Each rule cites source `LL-NNN`;
    complete entry (symptom, origin, evidence) lives there. Do not remove citation: the index
    `lessons-index.md` detects promotion by looking for that reference inside skills.
    
    - **LL-109** — For round-trips that normalize, sort, or deduplicate, test `f(f(x)) == f(x)` and define separately which fields must be stable from first pass. Document any allowed renormalization.
    
    ## Round-trip caveat
    
    Memory selections may not survive the extract → edit → rebuild cycle (SP-002). Verify selection
    membership after a rebuild, not just selection names.
    - **LL-010** — Before asserting a piece is missing, enumerate `.p3d` proxies, inspect their sizes, and open substantial candidates. Config only reveals what is rigged; debinarize and split connected components if geometry lives in a proxy.
    - **LL-177** — Before extracting selections or corrected geometry, locate actual edited file —including backups marking intervention— and have pipeline read that copy. Do not validate provenance solely because bbox looks coherent.
    
    
    ## Non-semantic MLOD face padding (SP-229, added 2026-08-31)
    
    An MLOD face record always reserves four vertex slots. A triangular face leaves the fourth
    slot unused, and Object Builder can leave non-zero bytes there after face reordering or
    editing. Those bytes carry no face data and binarization discards them. Source:
    `p3dtxt/README.md:11` and `p3dtxt/src/main.rs:38-42`.
    
    A changed `.p3d` hash after a rewrite therefore does not by itself prove data loss. For an
    MLOD round-trip, compare parsed fields while ignoring the unused fourth slot of triangles,
    or binarize both versions and compare the resulting ODOL semantics. Keep byte identity only
    for producers that explicitly promise canonical zero padding. This caveat is separate from
    the Memory-selection loss described in SP-002.
    
    ## Measure visibility by AREA sampling, not by a centroid ray (SP-446, added 2026-09-28)
    
    [EXACT] To decide whether a selection is visible from outside, cast rays from random points across the whole face (order of 3000 per LOD) and report the free-area percentage; a single ray from the centroid lies. Measured on a heater model: centroid rays reported "48/48 blocked in all 6 directions" while area sampling showed 84-86 % free — every face was a long thin triangle whose centroid sat behind a 1-2 mm wire. The false diagnosis nearly triggered rebuilding the model (the emissive grid) instead of fixing the config.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.