Skip to content

Add EQG resource identification and raw zone and mesh readers - #56

Draft
djhenry wants to merge 3 commits into
cjab:mainfrom
djhenry:codex/eqg-format-identification
Draft

djhenry wants to merge 3 commits into
cjab:mainfrom
djhenry:codex/eqg-format-identification

Conversation

@djhenry

@djhenry djhenry commented Sep 9, 2026

Copy link
Copy Markdown

Summary

Add an optional libeq_eqg crate and libeq::eqg facade feature for EQG resource identification, raw binary zone parsing, and terrain/model geometry parsing. Consumers can recognize a resource before dispatch and read EQGZ v1/v2 records without embedding format readers in a renderer. Existing default facade features remain unchanged.

identify(&[u8]) recognizes EQGZ, EQGT, EQGM, EQTZP, and EQOBG. It preserves raw little-endian binary versions, distinguishes unknown signatures from matching truncated headers, and does not imply complete parsing support.

zone::parse(&[u8]) reads EQGZ v1/v2 string tables, nullable model references, placements, variable-length v2 extension data, regions, and lights. It validates byte/count bounds, string termination, and model indices. Extensions borrow the input bytes rather than allocating a second word array. Strings remain bytes, floating-point values retain their bits, and unknown region/light fields remain raw words. Extra bytes after the counted records are exposed as trailing_data.

mesh::parse(&[u8]) reads EQGT/EQGM versions 1–3 with checked materials, raw properties, vertex attributes, triangles, and version-2 secondary UV data. It preserves colors, flags, unknown material values, and suffix bytes. Model bone counts are exposed, but skeletal records are not decoded.

The readers do not select resource providers, load referenced models, convert coordinates, reconstruct actor naming, or interpret collision/water semantics. Text terrain-project readers remain follow-up work. PFS retains archive extraction responsibility. This supports the downstream EQG zone project.

Validation

  • cargo test --workspace: 148 passed, three ignored.
  • Fifteen synthetic integration tests across identification, zone parsing, and mesh parsing, plus an identification doctest. Fixtures cover both zone versions and all three mesh versions, nullable references, non-UTF-8 names, float bits, truncation at every prefix, oversized counts, invalid references, unequal region/light counts, trailing data, and variable v2 records.
  • Explicit opt-in native corpus test: 200 descriptors parsed (34 v1, 166 v2), all counted sections consuming their files exactly. No native assets are included in this PR; requesting the corpus test without its input fails explicitly.
  • Explicit mesh corpus test: 803 meshes parsed, including all 206 terrain members (one v1, 33 v2, 172 v3) and 597 models from six fixture archives (eight v1, 213 v2, 376 v3). Includes 16 version-2 secondary-UV files and one opaque skeletal suffix. Independent fixture counts and vertex bit patterns validate boundaries and attribute offsets.
  • cargo fmt --all -- --check: passed.
  • Strict Clippy for libeq_eqg and strict rustdoc build: passed.
  • Independent review reran synthetic/native tests and mutation-checked v2 extension stride. The mesh review independently reran the 803-file corpus and mutation-checked the terrain-only marker-2 rule. Separate count-swap and byte-order mutations also made their regressions fail before restoration.

Strict workspace Clippy on Rust 1.98 reports three existing errors in libeq_wld, reproduced on unchanged upstream main. The optional WLD gamedata test feature requires fixtures absent from the checkout and is excluded from the passing default workspace result.

The contribution is split into header-identification, binary-zone-parser, and mesh-parser commits for review. Acceptance covers raw records and the supplied corpus, not rendered scenes or gameplay.

@djhenry djhenry changed the title Add optional EQG resource header identification Add EQG resource identification and raw binary zone parsing Sep 9, 2026
@djhenry djhenry changed the title Add EQG resource identification and raw binary zone parsing Add EQG resource identification and raw zone and mesh readers Sep 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant