btx: textures

Source

docs/formats/btx.md

SHA-256

0abe1b08…66fb779f

A texture: a 0x34-byte header, the texture's name, then its pixel data, ready to hand to Direct3D 11. Every texture in the game is one: the gallery and ending pictures, backgrounds, map names, Warren Report portraits, menu and font textures, and the textures of models and event sprites. A btx is a whole file's payload, a pakd entry, or sits inside another container (ARC\0, BMAR, the background archives, the fonts); it has no wrapping of its own. The engine's one texture loader reads it (How the game reads it). It's named after its magic, btx\0; Gibbed's TextureFile reads the same layout.

Where they are

confirmed (C# scan, all 10,016 .dat files): 28,518 btx, every one with a whole header as laid out below (version 0x103, name_offset 0x34, a known format). The pakd entry paths are as in containers.md.

• confirmed: a whole-payload btx ends exactly where its pixel data ends (all 7,200), and a pakd entry holding one is its data end plus 1–16 zero bytes, the usual pakd padding (all 12,022). Source: C# scan.
• confirmed: the name in a whole-payload btx is the file's name without its extension, ignoring case (all 7,200). Source: C# scan.
• likely: more textures are stored compressed inside ashg sprites in event/, object/ and battle/: the scan finds 393 broken btx\0 headers there, mixed with what look like compression flag bytes. They aren't counted above. Source: C# scan; hex inspection of event/scene/C1_ST_010.dat entry #19/1.

Header

0x34 bytes. Offsets are from the start of the btx (its magic), and every _offset field is an offset from there. "Not read" means the loader (0x140079db0, 0x140079de0) never reads it.

• confirmed: every btx passes Gibbed's header checks except its mip count: Gibbed accepts 1 or 3 levels, and the 4 two-level textures in worldmap/Worldmap.dat have 2. Source: C# scan.

Name and padding

• confirmed: data_offset is unk_0x2C_offset + 4 rounded up to 16 in every file, and unk_0x2C_offset is 0 to 21 bytes past the name's NUL, a multiple of 8 plus 4. The rule that places it isn't known; a rebuild keeps it. Source: C# scan.

Pixel data

The levels follow data_offset back to back, largest first, with no padding between them. Level m is width >> m by height >> m pixels.

• likely: a level of an uncompressed format is its row pitch × its height, where the row pitch is width × bits per pixel / 8 rounded up to 16 bytes. Source: 0x1401035e0 (row alignment from the format table at 0x1406b0670).
• likely: a level of a block format (BC1–BC7) is ceil(width / 4) × ceil(height / 4) blocks of 8 bytes (BC1, BC4) or 16 (the rest), stored row by row. Source: 0x1401035e0.
• confirmed: with these sizes and mip_count_minus_1 + 1 levels, the data fits each texture's space exactly as Where they are says, and row_pitch is level 0's pitch, in all 28,518. Source: C# scan.
• confirmed: every BC texture's width and height are multiples of 4 (23,220), and every R8G8B8A8 row is already a multiple of 16 bytes (5,298), so no file has row or block padding. 21,783 textures have a power-of-two height and 24,129 a power-of-two width; the rest don't. Source: C# scan.

unk_0x20_offset points past the data, at the next 64-byte boundary; in a whole-payload btx that is past the end of the payload, since the payload ends with the data.

Pixel formats

The format codes are indexes into the engine's table of 41 formats at 0x1406b0670 (0x18 bytes each: a name pointer, bits per pixel, row alignment or block width, block height, alpha bits, a clut flag, a block-compression flag). The names below are the table's own. A format is created on the GPU as the DXGI format from the table at 0x140b9a2f0, or, when the texture is sRGB, from the one at 0x140b9a3a0 (How the game reads it). All likely (static analysis), except the file counts, confirmed by the C# scan.

Source: the format table (0x1406b0670) and the two DXGI tables (0x140b9a2f0, 0x140b9a3a0) read from the executable by address; the conversion list and the rounding in 0x1400a6050; the converter 0x140104dc0 ("pixelconv"). Gibbed's TextureFormat has the same 41 names in the same order. Codes 41 and up are past the end of the table; the game doesn't check for them.

Names

• likely: the menu image path caches textures by a key made from the name and level 0's byte size: the FNV-1a 64 hash of the name followed by the size in decimal. A second btx with the same name and size gets the first one's texture. Source: 0x140168180 (BladeGraphicsManager::vfunction5), 0x140168680 (the key).
• likely: the texture database looks the name up before it creates a texture, and returns the loaded texture of that name when it's shared or in one of the requested groups. Source: 0x140063760; it files each new texture under its name with any extension cut off (0x140063cb0).
• confirmed: the files hold 11,265 distinct names for 28,518 textures: most repeats are copies of the same texture in several files, and 34 names have more than one size, used by different languages. Source: C# scan.

How the game reads it

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: every texture goes through the texture database's create (0x140063760). It walks a list of registered texture loaders (head at 0x140fd4ca0), calls each one's check and, on the first that accepts, its create. Only one loader is registered, the btx one (the record at 0x140caa758: create 0x140079de0, check 0x140079db0; registered at startup in 0x140051b40), so btx is the only texture format the game reads. Source: the list is used only by 0x140063760 and 0x140051b40.
• likely: the check (0x140079db0, not in Ghidra's function list; read from its bytes) passes when the data starts with btx\0 and the u16 at 0x04 is at most 0x103. Otherwise no loader takes it and the request returns texture −1: the image doesn't appear.
• likely: the create (0x140079de0) reads width, height, format, tiling, mip_count_minus_1 (capped at the caller's maximum, 255 on the menu path), the sampler bytes 0x13–0x16, flags, data_offset, unk_0x1C, unk_0x1E, unk_0x20_offset, name_offset, depth and linear. It checks none of them, and never compares the data's size with the buffer's: a short file is read past its end. It doesn't read row_pitch, unk_0x07, unk_0x1D, unk_0x2A, unk_0x2C_offset or unk_0x30.
• likely: the texture is then made on the GPU (TextureCore::vfunction12, 0x1400a6050) with D3D11's CreateTexture2D (CreateTexture3D for a volume), one subresource per level, each level's pitch worked out as in Pixel data. It's created sRGB when the device has sRGB on (bit 2 at +0x18 of the render device) and the texture's flag 8 is set: linear 0, flags bit 3 clear, and the caller not passing 0x40000 (0x1400a5d10).
• likely: before any of this, a buffer starting cmp\0 would be unpacked by the registered zlib or lzma decompressor (0x14007a0a0, bl::archive::CompressibleData). No game file uses it: the scan finds no cmp\0. Source: 0x14007a0a0; C# scan.
• likely: game screens load a texture file through one routine, 0x14026f4b0: given a btx it creates the texture through 0x140168180, given a pakd it reads it as a sprite pack (0x1402702a0), anything else as a sprite. About 40 functions call it, among them the gallery (0x140513e60, which opens group 0x2f8) and functions next to the openers of bg/back/ (0x1402ddda0), the Warren Report (0x140489eb0) and SaveThumb/ (0x14041e4e0). Source: exe.calls.
• likely: the gallery scales its picture to the screen from the texture's own size (fills 1920 × 1080, 0x140513e60), so a gallery picture can be any size.
• likely: textures inside ARC\0 archives are found by entry type tex and the hash of a file name (0x1400640b0), and handed to the same create. The archive formats are not part of this doc.

Replacing a texture

What the code above says a replacement btx has to be (all likely: static analysis, no in-game test yet):

• Valid, not identical. Nothing in a btx is checked but the magic and the version, so a replacement has to be a correct btx, not a byte-identical one. Its header has to describe its data exactly, because the game trusts it: a wrong data_offset, size or format reads the wrong bytes or past the end.
• Any size. Width and height can be anything up to D3D11's limit of 16,384 (resource limits, checked 2026-10-11); powers of two aren't needed, and over 6,700 of the shipped textures aren't. For BC formats keep both a multiple of 4, as every shipped one is. Data elsewhere that points into a texture by pixel position (sprite sheets, layouts, models) may expect the old size.
• A working format. BC7 (13), BC1 (7) or R8G8B8A8 (0), the three the game ships, are safe. BC2, BC3, BC6H, B8G8R8A8 and the other formats with a DXGI format load too; BC4, BC5 and the ones without a DXGI format don't.
• Mips are optional. One level is the norm (28,498 of 28,518). With more, keep each level at least 1 pixel on both sides.
• Keep the name when replacing a texture, and give a new texture a name no other texture uses (Names).
• Keep linear 0 for colour images, so they keep the original's sRGB handling.
• Mind the container. A whole-payload btx changes the file's size, so FileTable.bin has to match (filetable.md); a pakd entry is padded as in containers.md.

Rebuilding

To rebuild a btx byte for byte from its decoded form: write the header fields as read, the name, zeros to data_offset (the u32 at unk_0x2C_offset is 0), then the pixel data. row_pitch and unk_0x20_offset follow from the other fields (Pixel data), but are kept as read. For a new texture, place unk_0x2C_offset at data_offset − 4, as about half the files do. likely: no toolchain round trip yet.

Leads

• Decode and round-trip every btx in the toolchain (R30), and test a replaced texture in the game (R7): a new size, a new format, and whether the sRGB handling is on.
• What sampler values 0x13–0x15 select, from the code that builds D3D11 samplers from a texture's settings (the 16-byte block at TextureBtx +0x58 into CreateSamplerState); a trace would give them names.
• The textures compressed inside ashg sprites, and the 0x8003-version headers among them, belong to the ashg format.
• The containers that hold btx: entry #0 of each bg/*.dat and entry #n/0/0 of the event and object packs (an untagged resource archive starting 00000000, then its size), ARC\0, BMAR and the Font/ payloads.
• The sprite-pack reader 0x1402702a0 reads the u32 after a pakd's pack_size and expects 0x1FF10000 or 0x1FF10001 there; with 0x1FF10001 it loads entries #1 and #2 as the sprite's _aura and _mask textures. Which files have it.
• Where unk_0x1C, unk_0x1E and unk_0x20_offset would go: nothing reads them after the create, and no file has a clut.
• "Gfx" prefix: Gfx_BtxCacheKey (0x140168680) and Gfx_CreateBtxTexture (0x14016d960) are Mx::Graphics code, while "Gfx" elsewhere means bl::gfx; a BladeGraphics_ prefix, or TextureBlade_ for 0x14016d960 (it builds a Mx::Graphics::blGraphics::TextureBlade), would keep one term per concept.