Containers: how a game file is put together

Source

docs/formats/containers.md

SHA-256

1200789c…6b6acac7

How a game file is built, from the .dat on disk down to its entries, and how it is rebuilt. A .dat is obfuscated with RotXor; inside is a ZIP holding one member, usually a pakd archive of numbered entries. What's inside an entry (tables, text, …) has its own format doc: xlce for data tables, txte for text. Terms are as in the glossary.

Structure

A game file is a box inside a box: obfuscated, then zipped, around an archive of numbered entries. Each entry is one piece of data.

<name>.dat                      game file
└── RotXor obfuscation          (Layers, 1)
    └── ZIP, one member "pack"  (Layers, 2–3)
        └── pakd archive        (pakd archives)
            ├── #0   an entry
            ├── #1   an entry
            └── …

The tree is an illustration of the nesting, not of any one file. Not every file is built this way: some are wrapped otherwise, or not at all (Files that are not RotXor + ZIP), and some ZIP members are a single file of another format, not a pakd (Layers). An entry's first 4 bytes say what kind it is:

• likely: a table (xlce): rows and columns, like a spreadsheet. Source: Gibbed ExportSheet reads the xlc magic.
• likely: a text table (txte): rows of key → text. Source: Gibbed EventTextFile.
• likely: another archive: a nested pack, holding more entries. Source: Gibbed PackFileTable writes nested packs.
• likely: graphics and animations: btx textures, ashg compressed sprites and textures, SAS3 animations; and others not yet understood, kept as bytes. Source: those docs.
• confirmed: the top-level entry magics in all of Data/ are xlce, txte, pakd, btx, ashg, ARC, SAS3, sabf, IDX0, BMAR, PGRS, INVK and TASK, and entries with no known magic. Source: the survey (R28).

Layers

RotXor

The obfuscation works on the whole file in place. All three steps, and the two keys, are confirmed (source: the round trip, through RotXor.FromDoc, which reads the keys from this doc; the game's 0x1401a2cf0, below; Gibbed DataBogoCrypt.Decrypt and Encrypt, BaseBogoCrypt, whose "BogoCrypt" this is, agree).

Deobfuscating, in order:

1. Rotate left by 3 bits. The whole file is treated as one string of bits, most significant bit of byte 0 first, and rotated left by 3: byte i becomes (b[i] << 3) | (b[i+1] >> 5), and the last byte takes its low bits from the first byte (0x1401a2b70; Gibbed Deshift).
2. XOR with key 1, start word 8. From byte 0, each whole word g (0, 1, 2, …; 4 bytes) is XORed with word (8 + g) mod 15 of key 1. Bytes after the last whole word are left alone.
3. XOR with key 2 from byte 16. From byte 16 on, each whole word g is XORed with word (start + g) mod 17 of key 2, where the start word is byte[15] & 0x7F, read after step 2. Step 3 doesn't touch byte 15, so the start word comes from byte 15 of the plain file.

Obfuscating runs the steps in reverse (Gibbed Encrypt): step 3 with the start word from plain byte 15, then step 2, then rotate the whole file right by 3 bits (byte i becomes (b[i-1] << 5) | (b[i] >> 3), and byte 0 takes its high bits from the last byte; Gibbed Enshift).

Word g of the file is XORed with key word k = bytes 4k to 4k + 3 of the key, in order (Gibbed XorWithTable).

Key 1 (60 bytes, 15 words):

B0 BC 6D 19 E5 14 B6 EA F4 CB 16 B1 7D E5 7F B5
0B 7C 5E C4 2D 4F 31 99 67 98 19 E8 28 58 DE C9
C1 9B C9 83 34 C4 64 85 36 FA 0E DE FB E7 68 99
71 32 34 36 E5 01 7D 63 5C 81 77 7C

Key 2 (68 bytes, 17 words):

C6 53 98 ED D0 AA E0 1B 43 31 16 32 CE 0D 52 57
7B 72 0F FB B7 A9 C6 F1 F1 72 2C 89 5F B2 1B FA
A8 DB E3 E2 41 B5 BE C9 5D AE C6 21 E4 D2 88 74
97 26 4F 87 7A F0 69 7A B7 7E 15 09 BA 55 AD CA
B1 60 34 76

ZIP layout

The ZIP holds nothing beyond the one member: a local file header, the compressed data, one central directory record and the end of central directory record, in that order. The record layouts are the standard ones (APPNOTE.TXT, checked 2026-10-04). The values in Meaning are the ones in the game's files: the scan found each in all 551, and the round trip rebuilds every record byte for byte (it keeps the original's values, so the values come from the scan). confirmed: across all of Data/, every RotXor + ZIP file but one has exactly these values (the ZIP tally, R28). The one that doesn't, Shaders/Shader.dat (member sh_tacos.pac), was made by another tool: mod_time and mod_date set (0x644C, 0x54A9, 2022-05-09), version_made_by 0x003F (6.3), central flags 0x0000; its DEFLATE stream isn't zlib's (Rebuilding). n is the length of the member's name (4 for pack); csize is the compressed size.

The file in order:

Local file header

Every value here is the one in all 551 files checked (the scan), and every record rebuilds byte for byte (the round trip).

Central directory record

End of central directory record

Files that are not RotXor + ZIP

Every other file in Data/ is RotXor + ZIP. The toolchain reads each file's wrapping from the Files and Wrapping columns of this table (Wrapping.FromDoc; globs matched case-insensitively against the path under Data/, * also matching /): MLZ0 → LZ4, XOR with key 1, or none, where the file is the payload.

confirmed: this table covers every file in Data/ that isn't RotXor + ZIP, and each wrapping is removed and put back byte for byte: every file below (the .sab and .efz files, the movies and the single files) rebuilds identically through the toolchain's Wrapping (MLZ0 packed again with LZ4's default compressor, our copy (../../toolchain/src/LZ4/UPSTREAM.md) of K4os.Compression.LZ4 1.3.8), and no file in Data/ fails to unwrap. Source: the full round trip and the survey (R28, 2026-10-11).

pakd archives

Offsets are from the start of the pakd (its magic). Checked in all 582 packs of the files checked (the scan), and rebuilt from these rules byte for byte in all 551 top-level packs (the round trip, through Pakd.Build); Gibbed's PackFile agrees throughout.

How entries are stored:

• confirmed: entries follow back to back, each from its offset to the next one (the last to pack_size), each at a 16-byte boundary. Source: the scan (all 1,841 entries); the round trip. Gibbed PackFileTable agrees (writes entries back to back after the header).
• confirmed: an entry's stored bytes are its own data, then zeros to a 16-byte boundary: at least 1 and at most 16 (align16(size + 1)) in every xlce and txte entry checked. confirmed: an entry_unit_1 entry whose rows end 8 bytes past a boundary has 24 instead, so which layer adds the zeros, the table's writer or the pack's, isn't one rule; the rebuild keeps such bytes as they are. Source: the round trip and r22/tables.cs (the decoded entries); the scan: all 1,810 entries that aren't packs are a multiple of 16 long and end with a zero byte.
• confirmed: a nested pack's own size is a multiple of 16, and it is followed by exactly 16 zero bytes. Source: the scan (31/31). Gibbed PackFileTable agrees (writes 16 zero bytes after each nested pack and records its entry size as TotalSize + 16).

How the game reads it

How the executable unwraps a file after reading it (filetable.md covers the read itself). Every fact here is static analysis of the unpacked executable (Ghidra 12.1.4, the decompiled code in local/exe/decomp/), so at most likely; the functions are in the names list.

• likely: almost every load asks for unwrap kind 1, RotXor and ZIP; two effect loads ask for kind 2, MLZ0. Source: the last argument of every call to 0x140295bc0 and 0x140295c90 (kind 2 only in 0x140311b20, effect/effectmanager.cpp, and 0x140414930, the effect slot pool).
• likely: for kind 1 the game deobfuscates the whole buffer in place with the three RotXor steps, over the length from the file table: rotate left by 3 bits, XOR with key 1 from start word 8, XOR from byte 16 with key 2 from start word byte[15] & 0x7F. It does so for any length above zero; Gibbed's 16-byte minimum isn't the game's. Source: 0x140295670 → 0x1401a2cf0 → 0x1401a2b70 (rotate), 0x1401a2bf0 (key 1, at 0x140ba5300), 0x1401a2c70 (key 2, at 0x140ba5290).
• confirmed: the two keys in the executable are byte for byte the keys in RotXor. Source: rea read_bytes at 0x140ba5300 (60 bytes) and 0x140ba5290 (68 bytes), unpacked executable SHA-256 7b0230a1….
• likely: key 1 isn't only for .dat files: the movie read callback (0x1402b0970, pmf.md), the shader loader (0x1401646f0, inlined) and the save I/O (0x140193ac0, 0x140193c60, region saveio/bladesaveio.cpp) XOR with it too. Source: those functions.
• likely: the game reads only the ZIP's local file header. It allocates the output from uncompressed_size (0x16), finds the data at 0x1E + name_length + extra_length, and, when method isn't 0, inflates compressed_size (0x12) bytes as raw DEFLATE with zlib 1.2.11 (window bits −15); with method 0 it copies them, but then reports failure. It succeeds when inflate returns Z_STREAM_END or Z_OK. Source: 0x1401a29e0 (size), 0x1401a2a00 (inflate: inflateInit2_ 0x140198ef0 with −15 and "1.2.11", inflate 0x140199170; the copy returns false), called from the FileSystem::Decomp worker via 0x140295550 → 0x1402c16c0.
• likely: it never reads the signature, version_needed, flags, the times, crc32 or the name, nor the central directory or the end record. So no CRC is checked, and a rebuilt ZIP has to be valid only in its local header's method, compressed_size, uncompressed_size, name_length and extra_length, and in its DEFLATE stream; it doesn't have to be byte-identical. Source: 0x1401a2a00 reads no other field.
• likely: for kind 2 the game reads the uncompressed size from byte 4, and decompresses size − 8 bytes from byte 8 with LZ4_decompress_safe; it doesn't check the MLZ0 magic, and ignores the result. Source: 0x1401a29e0, 0x1401a2a00.

Reading a pakd

• likely: the game reads a pakd in place, with no reader of its own: entry i starts at the offsets[i] value from the start of the pack, and a loader that needs every entry loops count times. Source: 0x1402d4a30 (battle_data_release.dat: fixed entries, each as pack + u32 at 0x8 + 4i, never reading count); 0x1402b9cd0 (the text tables: every entry, up to count).
• likely: it doesn't check the pakd magic, nor read pack_size, unk_header_end or the padding, and doesn't check that an offset is in range. The one exception is the sprite register routine 0x14026f4b0, which compares the first three bytes with p, a, k, one at a time, to tell a sprite pack from an image (ashg.md). Source: the two loaders above read nothing else from the header; 0x14026f4b0.
• likely: the ids table is read in four places, each its own way. object/ bundles: high 16 bits a resource kind (0 a unit sprite file, 1 a face), low 16 bits the ID the entry is cached under (0x1402efac0, 0x14031eeb0, 0x1402eef20, and 0x140320ad0 for battle/entry/entry_unit_pack00.dat and pack01.dat). Sprite packs: only ids[0], 0x1FF10000 (one texture) or 0x1FF10001 (sheet, aura and mask) (0x1402702a0). Event scenes: an ID is a base per kind plus a number (0x11000 faces, 0x12000 actors, 0x50000 unit sprite files, 0x13000 sound banks, …), searched by 0x140350380. menu/menu_classface.dat: an entry is found by its ID (0x1402bbcd0). Details in ashg.md. Other loaders read so far ignore ids.
• likely: an entry is found by its index alone, and what kind it is comes from the loader that asks for it: 0x1402b9cd0 takes an entry as text only when it starts with txt. Source: 0x1402b9cd0 (strncmp(entry, "txt", 3)).
• likely: bl::archive is not the pakd reader: it reads the engine's ARC archives (named, typed records, found by type, ID, index or name; content optionally cmp-compressed with zlib or LZMA), which sit inside pakd entries in menu/ and as the ZIP member of Shaders/Shader.dat. 0x140037f40 belongs to a third format, the chunk chains inside BMAR models. Source: arc.md.

So a rebuilt pakd needs correct count, offsets and, where it has them, ids; the rest of the header is kept for a byte-identical rebuild, not because the game needs it.

Rebuilding

How a payload is wrapped back into a .dat. Each layer is rebuilt as laid out above; the table gives what the rebuild has to work out. Every rule is proven by the round trip over the 551 files checked (see Method); whether the game loads a rebuilt file is not (below).

Not yet tested: whether the game loads a rebuilt file, which also needs a matching FileTable.bin. Static analysis says it should, as long as the local header and the DEFLATE stream are valid (How the game reads it).

Leads

• What the pakd ids values mean in files whose loaders haven't been read yet (Reading a pakd lists the four readings known).
• Confirm in game (R14) that a rebuilt .dat with a different but valid ZIP (other times, a zero CRC) loads, as How the game reads it predicts.
• 0x1402b9cd0: these docs read it as the loader of the text tables, but the names list calls it Text_UnindexTables (txte.md says it undoes the loading on unload); settle which it is.
• regions.jsonl labels 0x1401a1940–0x1401a2d3f (the RotXor and unwrap functions) "Mx::Graphics", an inferred label that doesn't fit.
• legacy/formats/containers.md (../../legacy/formats/containers.md) has earlier observations to recheck (reference only).