Syplheed-Reborn/docs/re/structures/xbg7-mesh.md

XBG7 — mesh geometry (inside XPR2 model containers)

• Confidence: 🟡 PROBABLE for the single-stream layout (below); ❔ HYPOTHESIS / undecoded for the complex multi-stream body layout.
• Parser in: sylpheed-formats/src/mesh.rs (Xbg7Model::from_xpr2), tests tests/mesh_disc.rs. Container parsing reused from src/texture.rs (Xpr2Header / Xpr2ResourceEntry).
• Applies to: ship / weapon / prop models in hidden/resource3d/*.xpr (166 files).
• Method: clean-room — static hex inspection of the retail disc + geometric validation of the recovered triangles (non-degenerate area, indices in range, bbox matches the descriptor's stored size). No game code decompiled or copied.

Where XBG7 lives

Models are ordinary XPR2 containers (see the XPR2 texture doc / texture.rs). The 16-byte resource-directory entries (from file offset 0x10) carry TX2D texture resources and one or more XBG7 geometry resources:

entry = [ tag:4 ][ data_offset:u32 ][ descriptor_size:u32 ][ name_offset:u32 ]   (big-endian)

Offsets are relative to the directory base 0x10. The XBG7 descriptor (at data_offset+0x10, descriptor_size bytes) is a scene / material / node graph — it holds node names (rou_f001_mnt1_root, Light, …), a bounding value (0x41F00000 = 30.0 ≈ the ship's ~30-unit length), material names matching the TX2D channels (_col albedo, _spc specular, _gls gloss, _lum luminance), and per-sub-mesh records. The vertex / index buffers live in the container's shared data section (from header_size).

Sub-mesh records (in the descriptor)

Read in file order by a sliding 4-byte scan; each is a big-endian tuple:

[ vtx_count:u32 ][ 0:u32 ][ idx_count:u32 ][ tail:u32 ]
   3..=65535        ==0     mult. of 3        1..=64

(For rou_f001_wep_00: vtx_count=215, idx_count=1092 — matches the recovered geometry exactly.)

The single-stream data layout — 🟡 PROBABLE (decoded)

For ~25 of the 166 models (weapons rou_f001_wep_00/02/03/04/09/…) the data section is a straight sequence of sub-meshes, carved from header_size in record order:

per sub-mesh:
  [ index buffer  : idx_count × u16 BE ]        triangle list
  [ 12-byte vertex-buffer header  (contents undecoded) ]
  [ vertex buffer : vtx_count × 24 bytes ]  ← declaration below
  (pad to 16 bytes → next sub-mesh)

Vertex declaration (from the descriptor; usage codes 0x00 POSITION, 0x03 NORMAL, 0x05 TEXCOORD — identical across decoded models):

  +0x00  POSITION  f32 × 3 BE     model units
  +0x0C  NORMAL    f16 × 4 BE     (x, y, z, w); use xyz — unit length
  +0x14  TEXCOORD  f16 × 2 BE     (u, v)

Alignment is pinned by the normals. The vertex buffer starts at index_end + 12 (a fixed 12-byte header — NOT align16, which lands 4 bytes early on most models and silently corrupts every field). The correct offset is the unique one where the recovered normals are exactly unit-length; an align-based guess produced the small stray-triangle artefacts seen in the first viewer pass.

Safety gate: every index is validated < vtx_count, and the mean recovered |normal| must be ≈1 (in [0.5, 2.0]). A model failing either is rejected (MeshError::UnsupportedLayout) rather than emitting garbage — this correctly declines Stage_S* placeholders and models using a different vertex layout.

Not yet decoded — ❔ the complex body layout

The hero-ship body meshes (DeltaSaber_A/_T/_W.xpr resource f004, and ~100 other models) use a multi-stream layout: the data section does not start with an index buffer; the real geometry sits at descriptor-addressed offsets deep in a multi-MB data section, as separate position / attribute streams (a plain f32×3 position stream at stride 12 was located at a high offset, with attributes in other streams), and positions appear partly quantized. DeltaSaber_A's 5 XBG7 blocks are f004 (body) + _rou_f004_mnv01_L/_R, _mnv02, _turn180 (maneuver / pose variants). Decoding this requires parsing the descriptor's vertex-declaration + stream table (offsets 0x0C/0x14 with format codes were seen but not resolved). These models are cleanly declined today.

Evidence log

• 2026-07-12 — rou_f001_wep_00.xpr: XPR2 dir = 1×XBG7 (f001_wep_00) + 3×TX2D (_col/_gls/_spc). Data section starts with a u16-BE index run (max 214), then stride-24 vertices. Descriptor record [215,0,1092,4] at desc +0x2B0; index-buffer byte size 0x888 (=2184=1092×2) at desc +0x1A0. Recovered mesh = 215 v / 364 t, 362 non-degenerate, median tri area 0.015 — coherent. → single-stream layout PROBABLE.
• 2026-07-12 — descriptor-driven sequential carving over all 166 models: 42 carve under the index-only check. Real 3D extent confirmed on rou_f001_wep_04 (bbox 3.7×1.2×3.5).
• 2026-07-12 (refine) — attribute ranges differed per model (wep_00 UV≈attr0/2, wep_04 attr4/5, wep_03 attr1≈±60000 = garbage) → refuted the fixed "6 half attrs, UV=attr0/2" reading. Found the descriptor vertex declaration (offsets 0x0C/0x14, usages 0x03 NORMAL / 0x05 TEXCOORD). Solved the vertex-base offset with a unit-normal validator: index_end + 12 gives median |normal| = 1.000 on every weapon model (wep_00/02/03/04), vs align16 landing 4 bytes early. UVs then land in [0,1]. Adding the normal gate: 25 models decode clean + normal-valid (the rest — incl. Stage_S* degenerate blobs — correctly declined).
• 2026-07-12 — DeltaSaber_A.xpr body: data does not begin with indices; plain-f32×3 runs with ship-scale extent (span ≈27–34, matching bbox 30.0) found only at high offsets (data+0x28634C, …) → multi-stream, undecoded.