suptex

suptex exports campaign-map supertextures from Total War .stpi / .stpd file pairs as PNGs. It supports Shogun 2 (including Rise of the Samurai and Fall of the Samurai), Empire: Total War, and Napoleon: Total War. Python 3 is the only requirement.

Quick Start

Try the included sample first:

python3 suptex.py example.stpi example.stpd --out map.png

For a game texture, pass the matching index and data files. They are usually together under campaign_maps/<campaign>/display/Supertexture/ in the game install.

python3 suptex.py supertexture.stpi supertexture.stpd --out map.png

By default, suptex exports the smallest stored level: a quick, low-resolution preview. Use info to see the available levels before choosing a larger export:

python3 suptex.py info supertexture.stpi supertexture.stpd

Choose What to Export

Each file pair contains a pyramid of stored levels. Level 1 is the largest; higher level numbers are progressively smaller. The smallest level is the default.

Goal	Command
Export a particular level	python3 suptex.py supertexture.stpi supertexture.stpd --level 4 --out map.png
Export a particular plane (layer)	python3 suptex.py supertexture.stpi supertexture.stpd --render rgb --out colour.png
Export every plane as separate files	python3 suptex.py supertexture.stpi supertexture.stpd --all --out planes.png
Export tiles for every level	python3 suptex.py pyramid supertexture.stpi supertexture.stpd --out tiles
Stop a pyramid at zoom 3	python3 suptex.py pyramid supertexture.stpi supertexture.stpd --zoom 3 --out tiles

--render selects which of the tile's four planes to write, so each sheet is one command (see below). --all writes each plane on its own, appending _r, _g, _b and _a to the output stem.

Sheets and Layers

Every tile is BC3 and holds four planes, r, g, b and a. --render takes any run of those letters, so one command extracts each sheet. Which planes hold which sheet differs by game, and a pair does not record the game, so suptex leaves the choice to --render and defaults to the layout's usual colour plane (g for the block layout, rgb for the DDS layout).

Game	Sheet	Command
Empire, Napoleon	Coloured map	python3 suptex.py supertexture.stpi supertexture.stpd --render rgb --out colour.png
Empire, Napoleon	Water and land mask	python3 suptex.py supertexture.stpi supertexture.stpd --render a --out mask.png
Shogun 2	Coloured map	python3 suptex.py supertexture.stpi supertexture.stpd --render g --palette Parchment_Colour_Mapping.tga --out colour.png
Shogun 2	Normal map	python3 suptex.py supertexture.stpi supertexture.stpd --render arb --out normal.png

Empire and Napoleon store colour in the pair (planes r, g, b) with the water and land mask in a (white water); they need no palette and have no normal sheet. Shogun 2 keeps the palette-indexed colour in g and the normal map in a, r and b; it has no mask sheet. Shogun 2's Parchment_Colour_Mapping.tga is a separate file beside the pair — without it, the coloured map is exported as greyscale indices. --palette applies to a single channel, so it is used only with Shogun 2's g.

To see everything at once, --all writes each of the four planes as a greyscale PNG, taking no --render or --palette.

Pyramid Tiles

pyramid writes one PNG per tile as <out>/<zoom>/<x>_<y>.png. Zoom 0 is the smallest level, usually one or two tiles; zoom increases toward the full-resolution base. Rows count down from the top, as in common XYZ map tile schemes. Add --all to write every plane, or --fast for quicker, larger PNGs.

Size and Runtime

Use pyramid for the full-resolution base level rather than exporting it as one image. A base can exceed two billion pixels; although suptex streams its work, image viewers and editors may not be able to open the resulting PNG. Pyramid mode keeps output split into 512 px tiles.

The decoder processes one band of rows at a time for a single-image export and one tile at a time in pyramid mode. A measured run took about 68 seconds for 682 tiles in pure Python, so a complete large pyramid can take a few minutes. --fast lowers PNG compression effort, trading smaller output files for speed.

Sample Files

example.stpi and example.stpd are a small, synthetic Empire-format pair (128 x 128 pixels, two levels, 64 px tiles). Its colour sheet contains white glyphs on black, and its mask is a greyscale ladder.

python3 suptex.py info example.stpi example.stpd
python3 suptex.py example.stpi example.stpd --all --out sheets.png

The first command lists the dimensions and estimated memory for each level. The second writes the default level's colour and mask sheets.

Scope and Format Notes

suptex is a reader and exporter, not a viewer or modding toolchain. pyramid writes tile files; it does not serve them from the original pair. Editing textures or rebuilding pairs would require a writer.

For measured file layouts, decoding details, validation notes, and known format traps, see AGENTS.md. The format was measured against Crux3D's stupid.exe; the implementation is independently written and includes no code from it. The reader and format notes were developed with AI assistance, so verify results against a real game pair before relying on them.

License

Public domain under the Unlicense; see LICENSE.