LZ11 / LZS wrapper

A .lzs file is an outer 16-byte LZS wrapper followed by a standard Nintendo LZ11 compressed stream. Decompressing it usually yields a RESO container.

Outer LZS wrapper (16 bytes)

LZ11 stream header (4 bytes)

Stream body

Repeating blocks of 1 flag byte + up to 8 chunks. The flag byte's MSB-first bits select chunk kind: 0 = literal byte, 1 = back-reference.

Literal chunk (1 byte)

Emit the byte directly to the output buffer.

Back-reference chunk

The first byte's top nibble (n = b1 >> 4) selects one of three encodings:

After decoding, copy length bytes from output[len(output) − disp − 1 .. +length] into the output. The copy can read bytes it just wrote (RLE-like overlapping copies).

Decoder reference

# src/archive/lzs.py::decompress_lz11
def decompress_lz11(payload: bytes) -> bytes:
    decompressed_size = payload[1] | (payload[2] << 8) | (payload[3] << 16)
    out = bytearray()
    i = 4
    while len(out) < decompressed_size:
        flag = payload[i]; i += 1
        for bit in range(7, -1, -1):
            if len(out) >= decompressed_size: break
            if (flag & (1 << bit)) == 0:                       # literal
                out.append(payload[i]); i += 1
            else:                                              # back-ref
                b1 = payload[i]; b2 = payload[i+1]; i += 2
                top = b1 >> 4
                if top > 1:
                    length = top + 1
                    disp   = ((b1 & 0xF) << 8) | b2
                elif top == 0:
                    b3 = payload[i]; i += 1
                    length = (((b1 & 0xF) << 4) | (b2 >> 4)) + 0x11
                    disp   = ((b2 & 0xF) << 8) | b3
                else:                                          # top == 1
                    b3 = payload[i]; b4 = payload[i+1]; i += 2
                    length = (((b1 & 0xF) << 12) | (b2 << 4) | (b3 >> 4)) + 0x111
                    disp   = ((b3 & 0xF) << 8) | b4
                copy_from = len(out) - disp - 1
                for j in range(length):
                    out.append(out[copy_from + j])
    return bytes(out)

Encoder

src/archive/lzs.py::compress_lz11() implements a greedy encoder with one-byte lookahead. Limits (per spec):

Output is padded to a multiple of 4 bytes (standard). The encoder is not byte-identical to the Nintendo SDK — different valid LZ11 streams can decompress to the same bytes. Round-trip decompress(compress(x)) == x is the validation test (passes on every blob tested, 2 KB NCGRs up to 110 KB inner RESOs).

Worked example

First 32 bytes of 2d/buyitem.lzs:

offs  bytes                                              meaning
----  -------------------------------------------------- ----------------------------------
0000  31 2E 30 30  00 00 00 00  00 00 00 00 00  73 66 6F   wrapper magic, zeros, "sfo" tag
0010  11 80 BF 01                                          LZ11: magic=0x11, size=0x01BF80
0014  FF                                                   flag byte (0b11111111 = 8 back-refs)
0015  20 00                                                back-ref #1: n=2, length=3,
                                                                       disp=((0x0<<8)|0x00)=0
                                                                       copy 3 from out[-1]
0017  ... 7 more 2-byte refs ...

Compression ratios (sampled)

Source

• src/archive/lzs.py — decoder + encoder + CLI