Format:aPLib
| On this wiki | Facts · Code · Notes · Topics |
|---|
Jorgen Ibsen's aPLib LZ compression, common in packers, demoscene and 8-bit game tools: a bit stream with a first literal byte, then 0/10/110/111 tokens, Elias-gamma coded lengths, and a 7-bit-offset end marker; it has no magic of its own (packers add an 'AP32' header).
aPLib (ibsensoftware.com) is a small LZ77 coder whose decompressors are a few dozen bytes of assembly, so it appears in executable packers, malware and retro-game data. The open apultra compressor (Zlib license; matchfinder CC0) produces the same format, and its decoder src/expand.c documents the token grammar. Source: https://github.com/emmanuel-marty/apultra at 8f340057d7, README says the output is fully compatible with the original aPLib.
Raw stream grammar (apultra src/expand.c, function apultra_get_max_decompressed_size, lines 82-190)
- The first byte is a literal, copied as is.
- Then tokens are read from a bit queue; a new bit byte is read from the stream when 8 bits are used, and bits are taken from the most significant end. Tag bytes for literals and offsets are interleaved with the data bytes in stream order.
- Token
0: literal, one byte follows. - Token
10: match with long offset. Read an Elias-gamma style numberhi(loop: shift in one bit, then a continuation bit; start value 1); subtract the state value (3 after a literal, 2 after a match); if the result is not negative, offset = (hi << 8) | next byte, then the length is a second gamma number, plus 2 if offset < 128 or >= 32000, plus 1 if offset >= 1280 (MINMATCH3_OFFSET 1280, MINMATCH4_OFFSET 32000 insrc/format.h); if negative it is a repeat of the previous offset and only the length gamma number follows. - Token
110: short match: one byte, bits 7-1 the offset and bit 0 the length minus 2 (length 2 or 3); the byte 0x00 is the end-of-data marker. - Token
111: a single byte copy from a 4-bit offset: four more bits follow (apultra's other decoder, around line 366 of expand.c, comments 'Short offset, 1-15'). Unverified: offset 0 stands for a literal zero byte.
Limits in apultra: offsets up to 0x1FFFFF, blocks of 0x100000 bytes (src/format.h lines 36-45).
Identification
The raw aPLib stream has no magic. The aPLib packer-side 'AP32' header (the bytes 41 50 33 32 followed by a header size, packed size, packed CRC32, original size and original CRC32, then the data) is used by some packers: Unverified, from general knowledge, not present in apultra, which writes raw streams only. To find a depacker in an executable, search for the gamma-number loop (shift in a bit, read a continuation bit). Unverified: the exact machine-code form varies by depacker.
Related
Format:LZ4, Technique:Identifying compression libraries in binaries.
Code & repositories
- https://github.com/emmanuel-marty/apultra @
8f340057d7402c10da3d9c76c599f9ab83b8a22d· license: Zlib (declared by the contributor; GitHub's detector did not recognize LICENSE)
apultra: open optimal compressor for the aPLib format; src/expand.c is a readable decoder of the token grammar, src/format.h has the offset thresholds.
Tested on: source read, not run · checked 2026-10-19; last activity 2023-05-16; Note: the latest release ships binaries; the wiki links only the source, never the binaries