BT411/docs/BGF_FORMAT.md

BGF (DIV-BIZ2) Model Format — Parsing Spec

Reverse-engineered for the BattleTech pod port (replacing the closed libDPL/Division-IG renderer). Verified by parsing all 1275 .BGF files in CONTENT/ with a prototype parser — every file closes to the exact byte. Header authority cited inline; source headers under …/CODE/RP/MUNGA_L4/libDPL/.

1. Header & global encoding

• Magic: 8 bytes ASCII DIV-BIZ2 (__PFILE.H:60-61 dpfB2ZIDstr). Siblings: DIV-BMF2 (binary material), DIV-VIZ2/DIV-VMF2 (ascii).
• Endian: little-endian (FILELIB.H:55). All ints/tags + IEEE-754 float32 (not double, PFILE.H:127-130).
• No directory. After the magic, a flat-to-walk nested chunk (TLV) tree. First chunk is always HEADER (0x0003), last always BIZ_DONE (0x0005).
• Content written by format v2.8 (lib 2.07).

2. Chunk grammar (TLV tree)

Chunk { uint16 tagword;  (uint8|uint16) len;  byte payload[len]; }

• Tag id = tagword & 0x2fff. Namespaces: 0x00xx = structural/DEF, 0x20xx = attribute/CON (all leaves). Validity macro dpfValidTag (PFBIZTAG.H:134-137).
• Length width flag = tagword >> 14: 0 → 1-byte len; 1 (0x4000) → 2-byte LE len; 0x8000 (4-byte) reserved, unused in this content. (Census: 1-byte 38890, 2-byte 8525, 4-byte 0.)
• Containers (payload = child chunks): HEADER, BOUND, OBJECT, LOD, PATCH, PMESH, SPHERE_LIST (+ spec'd MATERIAL/TEXTURE/RAMP/POLYGON/TRISTRIP/POLYSTRIP/LINE/TEXT). Everything else is a leaf.

Tag IDs actually used by this game (full table in PFBIZTAG.H)

Structural 0x00xx: 0003 HEADER, 0005 BIZ_DONE, 0040 OBJECT, 0041 LOD, 0042 PATCH(=GEOGROUP), 0046 PMESH (only mesh type used), 0047 CONNECTION_LIST, 004d PCONN_LIST, 0048/0049 SPHERE_LIST/SPHERE, 0070/0071/0072 BOUND/BBOX/BSPHERE, vertex blocks 0080 XYZ, 0081 XYZ_N, 0082 XYZ_RGBA, 0088 XYZ_UV, 0089 XYZ_N_UV, 008A XYZ_RGBA_UV. Attribute 0x20xx: 2002 VERSION, 2003 DATE, 2004 TIME, 2005 SCALE, 2007 FILETYPE(0=geom/1=mtl), 2008 *_NAME, 2009 UNIT(1=metre), 2030/2031 SV_F/B_MATERIAL, 2034 SV_DECAL, 2035 SV_FACETED, 2036 SV_VERTEX, 2037 SV_SPECIAL (articulation/part names — see §6), 2046 LOD_DISTANCE(2×f32 in,out), 2048 LOD_TRANSITION.

3. Geometry

Vertex blocks — interleaved packed float32, count = len / stride:

tag	fields	stride
0080 XYZ	pos[3]	12
0081 XYZ_N	pos[3],n[3]	24
0082 XYZ_RGBA	pos[3],rgba[4]	28
0088 XYZ_UV	pos[3],uv[2]	20 ← dominant (2595 blocks)
0089 XYZ_N_UV	pos[3],n[3],uv[2]	32
008A XYZ_RGBA_UV	pos[3],rgba[4],uv[2]	36

Positions = 3 floats, units per UNIT (metres). Flags map 1:1 to dpl_VERTEX_TYPE (DPLTYPES.H:189-199).

Indices (inside a PMESH, after its vertex block):

• PCONN_LIST (0x004d) — uint8 pointsPerFace (4 = quads is typical; 6 = hexagons occur, e.g. CALPB) then int32 index[] (0-based into this geometry's vertex block). nFaces = ((len-1)/4)/ppf; fan-triangulate each face.
• CONNECTION_LIST (0x0047) — a flat triangle list (3 indices per face, no leading byte; corpus: all 3488 CONN chunks have n%3==0).
• ⚠ CONN and PCONN are NOT alternatives — a single PMESH can carry BOTH (quads/hexes in PCONN plus plain triangles in CONN): 370 of 841 pod GEO models mix them in one pmesh. A loader that prefers PCONN and skips CONN silently drops those triangles (found via the calliope turret base calpb: 78 PCONN tris + 24 CONN tris — the missing base panels). Process both, always.

D3D9 note: faces are quads → triangulate each quad [a b c d] → [a b c][a c d] at load.

4. Materials & textures (NOT in the BGF)

• Geometry refs material via parent PATCH's SV_F_MATERIAL/SV_B_MATERIAL leaf: uint8 mattype (PFILE.H:169-170; 1=named) + NUL-terminated "library:material" string, e.g. basev:shadow_mtl.
• The part before : = a .BMF material-library file (basev → BASEV.BMF). BMF uses the identical chunk grammar (magic DIV-BMF2/DIV-BIZ2, FILETYPE=1, MATERIAL/TEXTURE chunks) — so the same parser reads it.
• Texture pixels live in further files named by the BMF's TEXTURE_MAP (loaders dpl_vtxRead/sgiRead/tgaRead, DPLUTILS.H:210-223). Load chain: BGF → BMF → image. (Open: this archive has 2222 .BMF but few .vtx/.sgi/.tga — confirm where pixels actually live.)

5. Hierarchy → dpl model

HEADER
BOUND { BSPHERE, BBOX }
OBJECT                         → dpl_OBJECT
  SV_VERTEX
  LOD                          → dpl_LOD     (LOD_DISTANCE in/out; may be absent = 1 implicit LOD)
    PATCH                      → dpl_GEOGROUP (SV_F/B_MATERIAL, SV_FACETED, SV_DECAL, SV_SPECIAL)
      PMESH                    → dpl_GEOMETRY
        VERTEX_xxx
        PCONN_LIST / CONNECTION_LIST
BIZ_DONE

PATCH == GEOGROUP (VCELTYPE.H:481-492). Multi-LOD objects (1947 LODs/1275 files) are distance-switched; blend per LOD_TRANSITION/runtime dpl_MORPH_MODE.

6. Articulation / damage — name-driven, not geometric

No morph-target/joint chunk exists. Articulation & damage key off SV_SPECIAL (0x2037) string tokens on geogroups, e.g. dz_hip, dz_utorso, dz_larm, dz_rgun, dz_lfoot, dz_searchlight, and behaviour tokens PUNCH, BLINK, WIREFRAME, ADDITIVE_LODS, GEOMETRIZE 0x8000001a. dpl_FlushDCSArticulations/dpl_MorphObject/dpl_Damagize match these names to attach DCS joints / morph / hide-swap on damage. Loader must expose each geogroup's special string verbatim.

7. Open items (need a known-good render or more samples)

1. PCONN_LIST vs CONNECTION_LIST semantics RESOLVED (twice-corrected — see §"Indices"): PCONN_LIST = many faces with a leading points-per-face byte (4 or 6); CONNECTION_LIST = a FLAT TRIANGLE LIST (the earlier "ONE polygon per chunk" reading was wrong — task #20), and the two coexist in one PMESH (the earlier "prefer PCONN" reading dropped CONN's triangles — the turret-base missing-panels bug). The *_LP "light-point/FX" objects (materials btfx:*) carry only SPHERE_LIST/POINT_LIST geometry — no triangle mesh — and render as sprites later, not solids. Loader result on this corpus: 621/663 triangle meshes load; 42 are point/sphere FX.
2. Winding order (CW/CCW) + SV_FACETED ↔ backface culling — confirm visually.
3. Full SV_SPECIAL token grammar (multi-word commands).
4. SPHERE/SPHERE_LIST per-sphere radius source.
5. 4-byte length variant (0x8000) — unused here, handle defensively.