Skip to content

decomp-assets 0.4.0: textures in a chunked-RNC filesystem and a deflated model asset table - #3

Merged
RetroGameDeveloper merged 1 commit into
mainfrom
feat/ffs-and-rare-model-textures
Nov 14, 2026
Merged

RetroGameDeveloper merged 1 commit into
mainfrom
feat/ffs-and-rare-model-textures

Conversation

@RetroGameDeveloper

Copy link
Copy Markdown
Contributor

What

  • rnc.chunked / rnc.unpack_chunked: RNC streams with method byte 0x81: a table of each 4 KB chunk's packed size, then the chunks, each a method-1 stream of its own starting on an even offset. Any output range is decoded from only the chunks holding it. The method-1 loop moved into _method1, shared with unpack (behaviour unchanged). This variant's checksum fields aren't the method-1 CRC, so streams are judged by structure: every chunk must decode to its full size.
  • n64/ffs.py: a chunked stream holding an FFS filesystem (count, then 24-byte records: id, size, offset); I64 images inside it (I64\0, width, height, format 0 CI4 / 1 CI8 / 4 I4 / 5 I8, palette first) are taken when header and size agree exactly. One region per chunk that starts an image (regions never overlap), holding those images as textures; previews unpack only that file.
  • n64/rare_models.py: a deflated asset table (count, 0xFFFFFFFF, words whose top 24 bits are word offsets from the table end; each asset a 2-byte header + raw deflate). Models (0x0000000B) have a texture list at the halfword at 8: size, count, 8-byte entries (offset, type, width, height), palette before pixels. Types 1 CI4, 2 CI8, 4 RGBA16, 8 RGBA32, 16 IA8; 0x8000 marks mip levels after the first, which is shown. Accepted only when the first texture starts the data, the rest follow and all fit (without that, half of the samples were noise).
  • Both are in n64.regions and n64.preview (layout ffs-i64, rare-model).

Why

An off-road RC racer and a platformer sequel had empty texture browsers.

Checked (the user's cartridges, read locally, nothing committed)

Cartridge Found Scan
off-road RC racer 220 images in 103 regions 1.3 s
platformer sequel 5,013 textures in 861 models 0.2 s
the other 49 N64 cartridges nothing (no false positives) ≤ 1.3 s

Random samples (40–48 each, all formats including IA8, I4/I8 and mip-flagged entries) rendered correctly.

Tests: chunked streams (any range, bounds, truncation), FFS grouping/rejection/preview, model tables (non-models, misplaced first texture, mip flag, changed data), table order. pytest: 153 passed; ruff clean.

Not covered: the sequel's ~2,000 sprite assets (0103…), and model textures' smaller mip levels.

🤖 Generated with Claude Code

…flated model asset table

Two N64 games had empty texture browsers because their assets sit in containers
nothing read:

- An off-road RC racer packs its whole filesystem as one RNC stream with method byte
  0x81: 4 KB chunks, each a method-1 stream of its own, listed in a size table.
  rnc.chunked/unpack_chunked read any range from only the chunks holding it. The
  stream unpacks to an FFS filesystem (id, size, offset records) whose I64 images
  (CI4, CI8, I4, I8) are taken when header and file size agree exactly: 220 images.
- A platformer sequel keeps its assets as raw deflate behind a table of word offsets.
  Models (0x0000000B) carry a texture list; a model is taken when its first texture
  starts the data, the others follow and all fit: 5,013 textures in 861 models.

Checked on the user's cartridges locally (nothing committed): samples of 40-48
rendered correctly, and the other 49 N64 cartridges gain nothing (no false positives).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@RetroGameDeveloper
RetroGameDeveloper merged commit 5885176 into main Nov 14, 2026
1 check passed
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