Skip to main content

Module codec

Module codec 

Source
Expand description

Block codecs with UnityPy’s semantics (helpers/CompressionHelper.py:238-244).

  • None returns the stored bytes as they are, whatever blocks-info says.
  • LZMA (:17-44) is a raw LZMA1 decoder over the 5 property bytes and the rest, run to the end of the input: the declared size is ignored, a truncated stream yields what decoded, an over-long one yields all of it. Output is capped at crate::limits::Limits::max_block_output (a PARITY.md safety divergence). Fewer than 5 input bytes raise (struct.unpack("<BI", ...)). liblzma static, as docs/spikes/lzma.md decided.
  • LZ4/LZ4HC (:83-94) is lz4.block.decompress(data, uncompressed_size): the declared size is the maximum output. A shorter output is accepted; a longer one raises (python-lz4: LZ4BlockError), and so does an empty input, whatever the declared size (LZ4_decompress_safe returns -1).
  • LZHAM raises (:234-235), and so does an unknown type (files/BundleFile.py:515-521; CompressionFlags is an IntFlag, so the map lookup is what raises).

A block’s decoded length can differ from blocks-info; the bundle always lays entries out by the actual lengths, as UnityPy’s join does (plan section 3.6), so a codec returns what it decoded and never pads or cuts.

LZ4 acceptance is liblz4’s. UnityPy’s python-lz4 4.4.4 runs liblz4 1.9.4’s LZ4_decompress_safe, which refuses some blocks lz4_flex decodes: its end-of-block conditions (a literal run that ends within the last 12 bytes of the declared size or the last 8 bytes of input must be the last sequence and end exactly at the end of input; a match must end at least 5 bytes before the declared size; the length-extension guards). Lz4 is a port of liblz4’s decoder (lz4.rs), so it refuses what liblz4 refuses and decodes what it decodes, and the oracle fixture tests/fixtures/scaffold/lz4_blocks.json (python-lz4’s verdict and output for a grid of blocks around each boundary) is the acceptance test.

Output. A codec writes into a DecodeBuf, which checks the block’s cap and charges the input’s meter before it grows (plan section 3.6), or names a range of its input (the stored codec: Decoded::Input), which the caller slices. It cannot hand back bytes of its own: a buffer a registered codec allocated (a Python decompressor’s bytes) would be input-sized memory no meter charged (round 5), so its output goes through out like any other. Every block is decoded through decode_block, which starts the block’s segment and checks what the codec returned. A codec is caller code when a user registers it: the core calls it with no lock held.

Owner: package C. The registry type and decode_block are implemented by the scaffold.

Modules§

encode
Bundle packers following helpers/CompressionHelper.py:158-231. LZ4 and LZ4HC both use pristine liblz4 1.9.4 HC at level 9.
unitycn
UnityCN’s AES vectors and in-place LZ4-token walk.

Structs§

Codecs
Codecs by compression type number (0-63).
Lz4
Compression types 2 and 3: an LZ4 block, uncompressed as the maximum.
Lzma
Compression type 1: liblzma’s raw LZMA1 decoder, to the end of the input.
Stored
Compression type 0: the stored bytes.

Enums§

Codec
A block’s compression, flags & 0x3F.
Decoded
Where a codec put a block’s output (BlockCodec::decode).

Traits§

BlockCodec
Decodes one block.
BlockDecryptor
Decrypts one block in place before it is decoded (UnityCN: P3). UnityPy decrypts a block whose flags carry 0x100 and whose codec is not None, of a bundle whose header’s encryption flag built a decryptor (files/BundleFile.py:123-124, files/BundleFile.py:512-513); a bundle whose flag is clear is never decrypted, whatever the context holds.

Functions§

decode_block
Decodes one block of a bundle with codec (the codec of which), as every caller does (package C’s bundle; implemented by the scaffold).