---
description: "Per-game audit of Oblivion (TES4) compatibility — NIF v20.0.0.5 + the v10.x NetImmerse family, BSA v103, live ESM path"
argument-hint: "--focus <dimensions>"
---

# Oblivion Compatibility Audit

Deep audit of ByroRedux readiness for **The Elder Scrolls IV: Oblivion** content.

**Architecture**: Orchestrator. Each dimension runs as a Task agent (max 3 concurrent).

See `.claude/commands/_audit-common.md` for project layout, game-data locations,
key reference docs, methodology, the path-reference convention, deduplication
rules, and the base finding format. See `.claude/commands/_audit-severity.md`
for the severity scale. Do not restate any of it here.

## What Makes Oblivion Different (the audit surface)

Oblivion is the **oldest** title in the lineage and exercises code paths no
other game reaches. Two NIF eras coexist in vanilla `Oblivion - Meshes.bsa`:

1. **The retail body** — NIF **v20.0.0.5** (`bsver=11`): inline strings, u16
   flags, **no per-block size table**. This is what most clutter / architecture
   / creature meshes are.
2. **The NetImmerse tail** — a long tail of **v10.x** sub-versions (down to
   pre-Gamebryo v3.3.0.13) authored years earlier. These have subtly different
   field layouts gated by tight version bands in nif.xml, and — like v20.0.0.5 —
   **no block_size table**, so a single N-byte under-read truncates the entire
   downstream subtree.

The v10.x tail is the Oblivion-unique risk. Retail FO3/FNV/Skyrim are all
BS202 / 20.x and never touch these bands; a regression here is **silent and
Oblivion-only**. The v10.x stride-drift family (#1506 NiInterpController /
NiQuatTransform, #1507 NiPSysData + emitter, #1508 NiBlendInterpolator +
ControlledBlock, #1509 NiGeomMorpherController `bsver > 9` gate) is **resolved**
as of 2026-06-13; Oblivion-Meshes went from 56 truncated → 6 (further reduced by
`#1543`/`#1544`, regenerated baseline #1611). This audit treats that family as a
**regression-guard set**, not open work.

| Aspect            | Current state (verify, don't trust this table blindly)              |
|-------------------|--------------------------------------------------------------------|
| NIF format        | v20.0.0.5 retail + v10.x NetImmerse tail (both sizeless)            |
| BSA format        | v103 — opens AND extracts cleanly across all vanilla archives (regression guard, #699) |
| ESM parser        | **Live** — `crates/plugin/src/esm/` with `parse_esm_cells` walker + ~25 record types, several with Oblivion-specific decode branches. NOT a stub (the per-game *legacy/tes4.rs* stub was removed under #390). |
| Parse rate        | See ROADMAP.md Oblivion compat-matrix row (drifts after each sweep; do NOT hardcode a number here). Post-v10.x-family + `#1543`/`#1544`: 6 residual NetImmerse truncations (checked-in `oblivion_truncations.tsv` baseline, `#1611`) + 1 corrupt-by-design hard-fail (`#698` closed). |
| Cell loading      | Interior renders end-to-end (Anvil Heinrich Oaken Halls). Exterior blocked on TES4 worldspace + LAND wiring (same shape FO3 was — *not* BSA v103) |
| Reference data    | `/mnt/data/SteamLibrary/steamapps/common/Oblivion/Data/`           |

### Known Quirks (do NOT re-derive — verify still hold)

- **`user_version` only exists for files ≥ v10.0.1.8.** Older NetImmerse files
  have `num_blocks` where `user_version` would be. Confirm the
  `version >= NifVersion::V10_0_1_8` guard in `crates/nif/src/header.rs`.
- **BSStreamHeader presence is the nif.xml dual-band condition** (post-#170),
  NOT the old `version == 10.0.1.2 || user_version >= 3`. The live guard is
  `version == V10_0_1_2 || (user_version >= 3 && (version ∈ {V20_2_0_7,
  V20_0_0_5} || (V10_1_0_0 <= version <= V20_0_0_4 && user_version <= 11)))`.
  A v20.0.0.5 Oblivion file with `user_version >= 3` reads the header; a
  non-Bethesda file outside the band must NOT (regression of #170).
- **`NiTexturingProperty` reads a `uint` count directly** — do NOT add a
  leading `Has Shader Textures: bool`. nif.xml is wrong here; the Gamebryo 2.3
  source is authoritative. Regressing this breaks every Oblivion clutter / book
  / furniture mesh. Test lives in `crates/nif/src/blocks/properties_tests.rs`.
- **Oblivion has no per-block size table.** A single mis-aligned read poisons
  every subsequent block — there is no `block_size`-advance recovery path
  (unlike 20.2.0.7+). This is why every v10.x stride-drift bug truncated whole
  subtrees rather than one field.
- **Pre-Gamebryo v3.3.0.13 files** (e.g. `meshes/marker_*.nif`) inline type
  names as sized strings instead of a global type table. Parser returns an
  empty `NifScene` with a debug log rather than failing.
- **NetImmerse v10.x leading group_id.** For versions in [10.0.0.0,
  10.1.0.114), each block is preceded by a 4-byte group_id (`00 00 00 00`);
  block content starts AFTER it. Mixing stream-relative vs file offsets is the
  classic false-trail when chasing stride drift (see memory note
  `nif_v10x_stride_drift_resolved`).
- **`as_ni_node` walker must unwrap every NiNode subclass** (`BSOrderedNode`,
  `NiBillboardNode`, `NiSwitchNode`, `NiLODNode`, …) so scene-graph walks
  descend correctly.

## Parameters (from $ARGUMENTS)

- `--focus <dimensions>`: Comma-separated dimension numbers (e.g., `1,3`). Default: all 7.

## Phase 1: Setup

1. Parse `$ARGUMENTS`.
2. `mkdir -p /tmp/audit/oblivion`.
3. Fetch dedup baseline: `gh issue list --repo matiaszanolli/ByroRedux --limit 200 --json number,title,state,labels > /tmp/audit/issues.json`.
4. Confirm `Oblivion/Data/` exists; if not, note which dimensions lose real-data validation.
5. Read the current Oblivion row in `ROADMAP.md` (compat matrix) and
   `docs/feature-matrix.md` so every status claim cites live numbers, not this file.

## Phase 2: Launch Dimension Agents (parallel)

Dimensions are ordered by Oblivion-specific risk: NIF version handling first
(the v10.x tail is the unique surface), then archive, ESM, render, real-data.

### Dimension 1: NIF Version Handling — v20.0.0.5 + the v10.x NetImmerse Tail
**Subagent**: `legacy-specialist`
**Entry points**: `crates/nif/src/header.rs`, `crates/nif/src/version.rs`, `crates/nif/src/stream.rs`, `crates/nif/src/blocks/`, `docs/legacy/`
**Checklist**:
- `user_version` threshold (`V10_0_1_8`) and the BSStreamHeader dual-band guard
  in `header.rs` match nif.xml (see Known Quirks). The #170 regression test in
  `crates/nif/src/header.rs` (tests module) must still assert a non-Bethesda
  out-of-band file does NOT read the header.
- The v10.x sub-version constants exist and are used as gate boundaries:
  `V10_0_1_2`, `V10_1_0_0`..`V10_1_0_114`, `V10_2_0_0`, `V20_0_0_4`,
  `V20_0_0_5` in `crates/nif/src/version.rs`.
- **#1509 regression guard** (`crates/nif/src/blocks/controller/morph.rs`):
  `NiGeomMorpherController` gates its trailing field on `bsver > 9` (NOT the old
  `bsver != 0 && bsver <= 11`). `doghead.nif` is v10.2.0.0 **bsver 9** and must
  **skip** the trailing field; Oblivion's bsver-**11** morph rigs (e.g.
  `obgatemini01.nif`) must **keep** it — an off-by-band gate either direction
  truncates/misaligns `NiMorphData`. Tests:
  `crates/nif/src/blocks/controller/path_lookat_tests.rs`.
- **#1506/#1507/#1508 regression guards** — the resolved stride-drift family.
  Each was a `since`/`until` field gated on the wrong comparator dropping N
  bytes. Confirm `NiInterpController`/`NiQuatTransform`, `NiPSysData` + emitter,
  and `NiBlendInterpolator` + ControlledBlock all still land exactly on the next
  block boundary in the v10.x bands. Any new truncation growth on Oblivion-Meshes
  is a regression of this family — escalate, don't re-derive.
- `NiTexturingProperty` reads u32 count raw, no bool gate (regression guard).
- Inline-string block-type handling for pre-v3.3.0.13.
- u16 vs u32 flag width per block in the v20.0.0.5 vs v10.x layouts.
- Oblivion-only / legacy block types dispatched in `crates/nif/src/blocks/mod.rs`:
  NiKeyframeController, NiSequenceStreamHelper, NiBillboardNode + NiNode
  subclasses, NiLight hierarchy, NiUVController, NiCamera, NiTextureEffect, the
  legacy particle stack, the BSShader*Property aliases.
- **Collision import** (`crates/nif/src/import/collision/mod.rs`): `BhkMultiSphereShape`
  and `BhkConvexListShape` translate into `CollisionShape` (the former to
  `Ball`/`Compound`, the latter to `ConvexHull`/`Compound`) via
  `resolve_shape_inner` in the `extract_collision` chain — they must not fall
  out silently. Verify against the `BhkMultiSphereShape` / `BhkConvexListShape`
  downcast arms.
- **bhk motion_type via the canonical Havok enum (#1652, `dc33ec7d`)**:
  `collision.rs::havok_motion_type` maps the raw `hkMotionType` byte per the full
  nif.xml enum (1–5/8 → Dynamic, 6 KEYFRAMED → Keyframed, 7 FIXED → Static, 9
  CHARACTER → CharacterKinematic, 0/other → Static); the pre-fix
  `4 => Keyframed` / `_ => Static` collapse froze BOX_INERTIA (4) clutter.
  Shared with FNV/FO3 — re-introducing the collapse is the regression.
**Output**: `/tmp/audit/oblivion/dim_1.md`

### Dimension 2: BSA v103 Archive
**Subagent**: `general-purpose`
**Entry points**: `crates/bsa/src/archive/` (`mod.rs`, `open.rs`, `extract.rs`, `hash.rs`)
**Checklist**: This is a **regression guard** — v103 decompression has worked
end-to-end since 2026-04-17 (#699); the "v103 is broken" premise is dead, do not
regenerate it.
- `BSA_V_OBLIVION = 103` recognised in `open.rs`; rejection only outside {103,104,105}.
- **Folder-record size**: v103 AND v104 are **16 bytes**; only v105 (Skyrim SE)
  is 24. The live code is `if version == BSA_V_SKYRIM_SE { 24 } else { 16 }` in
  `open.rs`. (The older skill text claiming "v104 = 24 B" was wrong — verify
  against the constant, do not perpetuate it.)
- v103 archive-flag semantics (e.g. the "Xbox archive" bit several vanilla v103
  archives set, ignored for embedded names — `embed_file_names` gates on
  `>= BSA_V_FO3_SKYRIM`).
- Folder/file hash function in `hash.rs` still produces correct hashes.
- Full-archive sweep stays at 100% extraction. Only escalate to an open finding
  if `meshes/*.nif` extraction starts failing on a previously-clean archive.
**Output**: `/tmp/audit/oblivion/dim_2.md`

### Dimension 3: ESM Record Coverage (live path, not a stub)
**Subagent**: `general-purpose`
**Entry points**: `crates/plugin/src/esm/` (`mod.rs`, `reader.rs`, `cell/`, `records/`)
**Checklist**: TES4 records share the live ESM path with FNV/FO3 — there is no
per-game stub (removed under #390). The parser already carries Oblivion-specific
decode branches; the audit's job is correctness + coverage gaps, not "does it
exist".
- TES4 header (`HEDR` version 1.0 vs 0.94) and GRUP structure handled by the
  walker (`crates/plugin/src/esm/records/grup_walker.rs`).
- Oblivion-specific branches already present — verify they're correct, not
  regressed: `flags_oblivion` + `is_oblivion` in
  `crates/plugin/src/esm/records/actor/mod.rs` (split from `actor.rs`, #2055); MGEF-by-code map (Oblivion 4-char
  effect codes) and the CONT 4-byte-payload guard in
  `crates/plugin/src/esm/records/tests.rs` / `container.rs`; CLMT three-entry
  WLST in `crates/plugin/src/esm/records/climate.rs`.
- **16-byte ACBS guard (#1650, `3d5d0d68`)**: Oblivion `NPC_`/`CREA` ship a
  **16-byte** ACBS (flags u32 @0, level i16 @10) — distinct from the ≥24-byte
  FNV/FO3/Skyrim layout, so `parse_npc` (`actor.rs`) needs a `GameKind::Oblivion`
  arm gated on `len >= 16` *before* the FNV arm. Pre-fix the ≥24 arm never fired
  on Oblivion: `record.level` defaulted to 1 (high-level NPCs resolved
  lowest-tier inventory) and `acbs_flags` defaulted to 0 (every actor read Male
  via `Gender::from_acbs_flags`). Tests: `oblivion_16byte_acbs_parses_level_and_gender`
  + `fnv_ignores_16byte_acbs` in `actor.rs`/`tests.rs`. Per-game layout must stay
  gated at the parser→record boundary, never re-derived at spawn/equip time.
- The two ignored Oblivion real-data parity tests
  (`clas_oblivion_knight_against_vanilla`, `race_oblivion_data_and_subs_against_vanilla`)
  still pass against vanilla `Oblivion.esm` when un-ignored.
- CELL walker: does `parse_esm_cells` (`crates/plugin/src/esm/cell/mod.rs`)
  handle Oblivion's CELL group layout (XCLL lighting, RCLR, interior vs
  exterior block grouping)?
- DIAL/INFO format differs between Oblivion and later titles — does the
  conversation-tree decode (M24.2) account for it, or silently mis-read?
- What is the minimum record set the cell loader needs to place an Oblivion
  exterior REFR? (Feeds the Blocker Chain.)
**Output**: `/tmp/audit/oblivion/dim_3.md`

### Dimension 4: Rendering Path for Oblivion Shaders
**Subagent**: `renderer-specialist`
**Entry points**: `crates/nif/src/import/material/` (`mod.rs`, `walker.rs`, `shader_data.rs`), `crates/nif/src/import/walk/`, `byroredux/src/systems/particle.rs`, `crates/renderer/shaders/triangle.frag`
**Checklist**:
- `NiTexturingProperty` → `MaterialInfo` pipeline (base slot 0, dark slot 1,
  normal-from-bump per #131, detail, glow, gloss).
- `NiMaterialProperty` color mapping is raw monitor-space (per 0e8efc6 — do NOT
  `srgb_to_linear` legacy colors).
- `NiAlphaProperty` blend-factor extraction routes every Gamebryo AlphaFunction
  enum value.
- `NiStencilProperty` / `NiZBufferProperty` / `NiVertexColorProperty` /
  `NiSpecularProperty` / `NiWireframeProperty` / `NiDitherProperty` /
  `NiShadeProperty` — honored or dropped silently? **#869 guards**:
  `NiWireframeProperty` wires to the LINE pipeline variant;
  `NiShadeProperty.flat_shading` is consumed in the fragment shader.
- Vertex-color interaction with material color.
- **#1239 Oblivion `NiPSysEmitter` version gating**: Oblivion's pre-Skyrim
  emitter field layout is routed via nif.xml's version gate — a regression
  silently misparses emitter authoring.
- **Typed particle-emitter import → runtime path**: `NiPSysEmitter` /
  `NiPSysEmitterCtlr` / `NiPSysEmitterCtlrData` / `NiPSysGrowFadeModifier` are
  TYPED blocks (`crates/nif/src/blocks/particle.rs`) decoded by
  `extract_emitter_params` + `extract_emitter_rate`
  (`crates/nif/src/import/walk/mod.rs`) and fed into
  `apply_emitter_params` (`byroredux/src/systems/particle.rs`). Verify an
  Oblivion emitter that parses (per the #1239 gate) actually reaches the ECS
  authoring path and animates — not just parses-then-drops.
- **Disney BSDF gating regression guard (#1248-#1252)**: zero Oblivion materials
  author BGSM/`.mat`, so `MAT_FLAG_PBR_BSDF` (`crates/renderer/shaders/include/shader_constants.glsl`)
  must be 0 across the entire Oblivion material universe — the Disney lobe
  (`crates/renderer/shaders/include/pbr.glsl`) is
  unreachable for Oblivion. Any Oblivion scene activating Burley / anisotropic
  GGX is a gate regression.
**Output**: `/tmp/audit/oblivion/dim_4.md`

### Dimension 5: NIFAL Canonical Material Translation for Oblivion
**Subagent**: `renderer-specialist`
**Entry points**: `byroredux/src/material_translate.rs`, `crates/nif/src/import/material/walker.rs`, `crates/core/src/ecs/components/material.rs`, `byroredux/src/render/static_meshes.rs`, `docs/engine/nifal.md`
**Checklist**: Trace an Oblivion `NiTexturingProperty`/`NiMaterialProperty`
`MaterialInfo` through the single canonical boundary `translate_material`
(`byroredux/src/material_translate.rs`) into the ECS `Material`.
- Metalness/roughness arrive as plain `f32` carrying the `f32::NAN` sentinel
  (`mesh.metalness_override`/`roughness_override` `.unwrap_or(f32::NAN)`) and are
  resolved exactly once by `Material::resolve_pbr`
  (`crates/core/src/ecs/components/material.rs`). Confirm no per-draw
  `classify_pbr` reappears and that `static_meshes.rs` still reads
  `m.roughness`/`m.metalness` directly with no render-time keyword scan.
- `emissive_source` is tagged `EmissiveSource::Material` for Oblivion legacy
  meshes via the `NiMaterialProperty` arm in
  `crates/nif/src/import/material/walker.rs` (distinct from the Skyrim/FO4
  `BSLightingShaderProperty` arm). Test:
  `crates/nif/src/import/material/emissive_source_tests.rs`.
- `MAT_FLAG_PBR_BSDF` stays 0 across the all-legacy Oblivion universe (shared
  with Dim 4's Disney-gate guard; flag this once, cross-reference).
See `/audit-nifal` for the cross-game canonical-tier audit; this is the
Oblivion-specific slice.
**Output**: `/tmp/audit/oblivion/dim_5.md`

### Dimension 6: Real-Data Validation
**Subagent**: `general-purpose`
**Entry points**: `crates/nif/examples/nif_stats.rs`, `crates/nif/examples/recovery_trace.rs`, `crates/nif/tests/parse_real_nifs.rs`, `crates/nif/tests/per_block_baselines.rs`
**Checklist**:
- Run `nif_stats` (and `nif_stats --tsv` for the per-type histogram) over
  `Oblivion - Meshes.bsa`; compare clean/recovered/truncated counts against the
  current ROADMAP Oblivion row AND the checked-in Oblivion baseline in
  `per_block_baselines.rs`. Any `unknown` growth or `parsed` shrinkage is a
  regression.
- Run `recovery_trace` to enumerate the residual truncated files (6 NetImmerse
  v10.x markers — `marker_arrow`/`divine`/`map`/`radius`/`temple`/`travel` —
  per the checked-in `oblivion_truncations.tsv` baseline, `#1611`, post-`#1543`/
  `#1544`). Confirm they're the expected NetImmerse tail and the single
  corrupt-by-design hard-fail, not new drift.
- Cross-check the block-type histogram for any new types appearing since the last
  sweep.
- Pick 3 representative interior meshes (Anvil Heinrich Oaken Halls chandelier, a
  book, a creature head) and trace them through `import_nif_scene` → verify
  expected mesh count + material chain.
**Output**: `/tmp/audit/oblivion/dim_6.md`

### Dimension 7: Exterior Blocker Chain & Game-Specific Quirks
**Subagent**: `general-purpose`
**Entry points**: `ROADMAP.md` (Known Issues + compat matrix), `docs/feature-matrix.md`, `byroredux/src/cell_loader/`, `docs/audits/`
**Checklist**:
- The real exterior blocker is **TES4 worldspace + LAND wiring** (same shape FO3
  was pre-cell-loader) — *not* BSA v103 decompression, which has worked
  end-to-end since 2026-04-17 (#699). Do not regenerate the dead "v103 is
  broken" framing.
- Does the `--bsa` CLI path open + list + extract Oblivion archives end-to-end?
- Are there Oblivion-specific record types the cell loader
  (`byroredux/src/cell_loader/`) needs beyond the FNV-aligned set to place
  exterior REFRs?
- Animation blocks that parse but can't play because scene-graph name resolution
  is missing?
- Does the pre-v3.3.0.13 fallback log at `warn` or `debug` (spam risk on
  full-archive sweeps)?
- Any 100%-parse NIFs that would still render wrong (legacy particle emitters
  that parse but don't route to the renderer — cross-check Dim 4)?
- `_far.nif` distant-object LOD (#1726/#1745, Session 52) — verify the
  Oblivion/FO3/FNV placement scheme + real LOD textures still resolve on
  Oblivion exteriors; entry points `cell_loader/object_lod.rs`,
  `cell_loader/placement_lod.rs`.
**Output**: `/tmp/audit/oblivion/dim_7.md`

## Phase 3: Merge

1. Read all `/tmp/audit/oblivion/dim_*.md` files.
2. Combine into `docs/audits/AUDIT_OBLIVION_<TODAY>.md` with structure:
   - **Executive Summary** — Current compatibility level (NIF parse incl. v10.x
     tail, archive extract, ESM parse, render end-to-end), top blockers in
     priority order. Cite ROADMAP/feature-matrix numbers, not this skill.
   - **Dimension Findings** — Grouped by severity per dimension.
   - **Blocker Chain** — Sequential list to reach "exterior cell renders".
     Interiors already work end-to-end (Anvil Heinrich Oaken Halls). Real chain:
     TES4 worldspace + LAND wiring → CELL exterior REFR placement → exterior
     bench. Do NOT regenerate the stale BSA-v103 framing.
   - **Regression Guard List** — Previously-fixed items this audit verified still
     hold: the v10.x stride-drift family (#1506/#1507/#1508/#1509),
     `NiTexturingProperty` u32 count, BSStreamHeader dual-band (#170),
     `user_version` threshold, BSA v103 extraction (#699), Disney-gate stays 0.
3. Remove cross-dimension duplicates.

Suggest: `/audit-publish docs/audits/AUDIT_OBLIVION_<TODAY>.md`