From 1a800d7aa4577b135e3c15f0a6e4455bd7c51761 Mon Sep 17 00:00:00 2001 From: RetroGameDeveloper <40120498+RetroGameDeveloper@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:41:27 +0000 Subject: [PATCH] decomp-assets 0.2.0: texture banks with a fourth block, their source file name, are found and named A later version of the indexed-bank engine (a 16 MB Turok-engine shooter) appends a fourth block to each texture bank: the texture's source file name ("BUSH01.GIF"), NUL-terminated and padded to eight bytes. The recogniser required exactly three blocks, so all 990 of that game's banks were rejected and its texture browser was empty. The fourth block must be printable text, one NUL and zero padding, and it becomes the bank's label. Raw (uncompressed) four-block banks are found too. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- pyproject.toml | 2 +- src/decompassets/__init__.py | 2 +- src/decompassets/n64/textures.py | 26 ++++++++++++++++++++------ tests/test_native_textures.py | 23 +++++++++++++++++++++++ uv.lock | 2 +- 6 files changed, 47 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 4092900..3ef1fca 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ the RNC unpacker work for any console. The interface may change before 1.0. ## Use ```bash -uv add "decompassets @ https://github.com/RetroReversing/decomp-assets/archive/refs/tags/v0.1.0.tar.gz" +uv add "decompassets @ https://github.com/RetroReversing/decomp-assets/archive/refs/tags/v0.2.0.tar.gz" ``` ```python diff --git a/pyproject.toml b/pyproject.toml index 28b92a8..8f356ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "decompassets" -version = "0.1.0" +version = "0.2.0" description = "Find and preview game assets (textures, audio banks, models, fonts) inside cartridge and disc images by their structure, with no per-game offsets." readme = "README.md" license = "AGPL-3.0-only" diff --git a/src/decompassets/__init__.py b/src/decompassets/__init__.py index 3ebe316..1d49ec4 100644 --- a/src/decompassets/__init__.py +++ b/src/decompassets/__init__.py @@ -10,4 +10,4 @@ Everything here reads bytes and returns plain dicts. It never writes a game file, runs a tool or downloads. """ -__version__ = "0.1.0" +__version__ = "0.2.0" diff --git a/src/decompassets/n64/textures.py b/src/decompassets/n64/textures.py index 2470a19..dc2515c 100644 --- a/src/decompassets/n64/textures.py +++ b/src/decompassets/n64/textures.py @@ -2,6 +2,8 @@ The source-assisted layout is three indexed blocks: an eight-byte format record, bitmap frames and palettes. No title, release address or source file is needed at runtime. +A later version of the engine adds a fourth block holding the texture's source file name +("BUSH01.GIF"), NUL-terminated and zero-padded; that name becomes the bank's label. CI4/CI8, RGBA32 and the fixed six-level RGBA16 mipmap layout are checked separately. """ from __future__ import annotations @@ -14,7 +16,8 @@ MAX_BANK = 4 * 1024 * 1024 MAX_EXPANDED = 64 * 1024 * 1024 MAX_BLOCKS = 16384 -RAW_HEADER = re.compile(rb'\x00\x00\x00\x03\x00\x00\x00\x18') +RAW_HEADER = re.compile(rb'\x00\x00\x00[\x03\x04]\x00\x00\x00\x18') +MAX_NAME = 64 def _blocks(data, start, end, *, empty=False): @@ -34,10 +37,19 @@ def _blocks(data, start, end, *, empty=False): MIP_BYTES = 2744 +def _name(data, start, end): + """The fourth block: printable text, one NUL, then only padding to the eight-byte block size.""" + text, nul, rest = data[start:end].partition(b'\0') + if not nul or not 0 < len(text) <= MAX_NAME or any(not 32 <= c < 127 for c in text) or rest.strip(b'\0'):return None + return text.decode('ascii') + + def bank_layout(data): """Require all independently indexed frames/palettes to fit the format record.""" outer = _blocks(data, 0, len(data)) - if not outer or len(outer) != 3 or outer[0] != (24,32):return None + if not outer or len(outer) not in (3,4) or outer[0] != (24,32):return None + name = _name(data, *outer[3]) if len(outer) == 4 else '' + if name is None:return None fmt, speed, width_shift, height_shift, effect, mode, pad1, pad2 = data[24:32] if fmt not in (0,1,2,3,4) or not 0 <= width_shift <= 10 or not 0 <= height_shift <= 10:return None if pad1 or pad2 or mode > 3:return None @@ -66,7 +78,7 @@ def bank_layout(data): for i,(start,end) in enumerate(frames)):return None settings = dict(format=pixel_format,width=width,height=height,offset=frames[0][0]) if palettes:settings.update(palette_offset=palettes[0][0],palette_format='ia16' if fmt == 3 else 'rgba5551-be') - return dict(preview_settings=settings,frames=len(frames),palettes=len(palettes), + return dict(preview_settings=settings,frames=len(frames),name=name,palettes=len(palettes), palette_entries=palette_entries,frame_offsets=[start for start,end in frames],palette_offsets=[start for start,end in palettes], levels=levels,layout='mipmap-rgba16' if fmt == 4 else 'row-major',playback_speed=speed) @@ -148,8 +160,10 @@ def regions(image, *, check=lambda: None, progress=lambda _: None): extent = 18+packed contained_end = offset+extent else: - if offset+20 > len(image):continue - extent = int.from_bytes(image[offset+16:offset+20],'big') + if offset+24 > len(image):continue + # The last offset of the outer index is the bank's length. + at = 4+4*int.from_bytes(image[offset:offset+4],'big') + extent = int.from_bytes(image[offset+at:offset+at+4],'big') if not 32 <= extent <= MAX_BANK or offset+extent > len(image):continue data = image[offset:offset+extent] found = bank_layout(data) @@ -161,7 +175,7 @@ def regions(image, *, check=lambda: None, progress=lambda _: None): if 'palette_offset' in settings:settings['palette_offset']+=offset found['frame_offsets']=[offset+at for at in found['frame_offsets']] found['palette_offsets']=[offset+at for at in found['palette_offsets']] - results.append(dict(offset=offset,size=extent,kind='image',label='Texture bank',confidence='validated', + results.append(dict(offset=offset,size=extent,kind='image',label=found['name'] or 'Texture bank',confidence='validated', reason='Source-assisted indexed-set structure: all frame extents match dimensions and all palette extents match the format.'+ (' Both RNC checksums passed.' if compressed else '')+ ' Runtime use is not established.', diff --git a/tests/test_native_textures.py b/tests/test_native_textures.py index dd5ebac..609ef55 100644 --- a/tests/test_native_textures.py +++ b/tests/test_native_textures.py @@ -116,3 +116,26 @@ def test_ci8_rejects_missing_colours_and_unsupported_palette_extents(): broken=bytearray(raw);broken[offset]=16;assert textures.bank_layout(broken) is None bad=indexed_set([bytes([0,1,3,3,255,0,0,0]),indexed_set([bytes(64)]),indexed_set([bytes(64)])]) assert textures.bank_layout(bad) is None + + +def named_bank(name=b'BUSH01.GIF'): + """A later engine version appends the texture's source file name as a fourth block.""" + raw=bank();inner=textures._blocks(raw,0,len(raw)) + return indexed_set([raw[a:b] for a,b in inner]+[(name+b'\0').ljust((len(name)+8)//8*8,b'\0')]) + + +@pytest.mark.parametrize('pack',[lambda x:x,literal_block,literal2]) +def test_fourth_block_names_the_bank(pack): + payload=pack(named_bank());found=textures.regions(bytes(16)+payload) + assert [asset['label'] for asset in found]==['BUSH01.GIF'] + assert found[0]['name']=='BUSH01.GIF' and found[0]['preview_settings']['format']=='ci4' + data=textures.decode(payload)[0] if payload[:3]==b'RNC' else bytes(16)+payload + assert textures.preview(data,found[0],{})['details']['frame']==0 + # Three-block banks keep the generic label. + assert [asset['label'] for asset in textures.regions(bank())]==['Texture bank'] + + +@pytest.mark.parametrize('block',[b'\0'*8,b'BUSH\x01.GIF\0\0\0\0\0\0',b'BUSH01.GIF\0\0\0\0\0X',b'NOTERMIN',b'A'*72+b'\0'*8]) +def test_fourth_block_that_is_not_a_name_is_not_a_bank(block): + raw=bank();inner=textures._blocks(raw,0,len(raw)) + assert textures.bank_layout(indexed_set([raw[a:b] for a,b in inner]+[block])) is None diff --git a/uv.lock b/uv.lock index e25bacf..0e3886c 100644 --- a/uv.lock +++ b/uv.lock @@ -51,7 +51,7 @@ wheels = [ [[package]] name = "decompassets" -version = "0.1.0" +version = "0.2.0" source = { editable = "." } [package.dev-dependencies]