PAL / ALP / LHT / SHD — Palettes and Colour Lookup Tables

Total Annihilation shipped its entire world in 256 colours. The .pal file holds that palette; the .alp, .shd and .lht files are lookup tables built from it that the engine uses to blend, shade and light pixels without leaving the indexed colour space.

None of the four has a header, version field or compression. A .pal is 1,024 bytes (256 × RGBx); .alp is 65,536 bytes (256 rows of 256 palette indices) and .shd / .lht are 8,192 bytes each (32 rows of 256 palette indices).

palettes/palette.pal — rendered by kbot pal swatch

kbot pal info     palettes/palette.pal              # one-liner
kbot pal describe palettes/palette.pal              # full RGB dump
kbot pal swatch   palettes/palette.pal -o pal.png --cell 24

# Render a lookup table, coloured by the palette:
# .alp as 256×256 cells, .shd / .lht as 256×32 cells
kbot pal lookup   palettes/palette.alp --palette palettes/palette.pal --target alp.png
kbot pal lookup   palettes/palette.shd --target shd.png
# TA: Kingdoms: the palette is usually a PCX next to its tables
kbot pal lookup   palettes/aramon.alp --palette palettes/aramon.pcx --target aramon.png

# Round-trip to editor-friendly formats
kbot pal convert  palettes/palette.pal -o palette.gpl                  # GIMP
kbot pal convert  palettes/palette.pal -o palette.txt --format jasc    # JASC

import "github.com/coreprime/kbot/formats/pal"

p, _ := pal.LoadFromFile("palettes/palette.pal")
fmt.Printf("RGB[0] = %v (black; sprites key it per frame)\n", p.Colors[0])
for i, c := range p.Colors {
    fmt.Printf("%3d  #%02x%02x%02x\n", i, c.R, c.G, c.B)
}

On-disk layout (.pal)#

typedef struct {
    uint8 R;
    uint8 G;
    uint8 B;
    uint8 A;     // Unused. Cavedog files have this as 0 throughout.
} PALEntry;

PALEntry entries[256];   // 256 × 4 = 1024 bytes

There is no signature and no version. The game loads palettes/<name>.pal like this (kbot-io's pal.LoadNamed does the same, and the studio and asset explorer load palette.pal through it for every TA render: tile pool, minimaps, sandbox terrain, features, textures and model colours):

• 1,024 bytes or more: the first 1,024 bytes are the palette; the rest is ignored.
• Empty or missing: the palette comes from palettes/<name>.pcx instead — the last 768 bytes of that file, whether or not a 0x0C marker precedes them. TA 3.1c then rebuilds the .alp, .shd and .lht tables for those colours.
• 1 to 1,023 bytes: not usable; the game reads 1,024 bytes past the end of the file. kbot reports an error (and the studio falls back to the built-in TA palette).

.pal — the canonical TA palette#

The bytes R, G, B, A per entry literally mean red, green, blue, unused. Index 0 is ordinary black. Terrain tiles, minimaps and backdrops draw it opaque (62 of the 275 retail maps use it in their tiles). Transparency is decided per image, not by the palette: a GAF frame's key byte (often 9, sometimes 0) and its skipped pixels are transparent, and model textures are sampled without a key.

.alp / .shd / .lht — colour lookup tables#

These three files are not RGB data: every byte is a palette index. Each table has one 256-entry row per blend partner or level, and its columns are the 256 source colours:

uint8 alp[256][256];   // blend = alp[a][b]
uint8 shd[32][256];    // shaded = shd[level][c]
uint8 lht[32][256];    // lit    = lht[level][c]

Practically: the engine never blends colours arithmetically — it does a table lookup, so the resulting pixel is always a real palette index that can be drawn through the existing 8bpp pipeline. This is why all the shadows in TA look like a darker version of the same colour ramp, not "50% black overlaid": each shaded result is the palette index closest to that mathematical mix.

The game uses a table file only when its size is exact; a missing table or one of any other size is rebuilt from the palette. kbot pal lookup therefore rejects files of any other size. TA: Kingdoms ships tables of the same sizes for nearly every palette in its palettes/ folder; most of those palettes are PCX files, and kbot pal lookup --palette takes a .pcx as well as a .pal.

Worked example — palette.pal#

The first 16 entries of the stock TA palette:

kbot pal describe palettes/palette.pal prints the full table.

Worked example — palette.alp and palette.shd as lookups#

Rendering the tables with the palette as colour source (kbot pal lookup … --cell 2):

palette.alp: 256 × 256 cells. Row a, column b shows the blend of colours a and b;
the diagonal reproduces each colour.

palette.shd: 256 × 32 cells. Each column is a source colour;
rows run from black (row 0) through the colour itself to brighter shades.

Reading the shade table: column 80 (mid-grey) starts black in row 0, climbs through darker greys of its ramp, reaches itself around rows 14 and 15, and then brightens. The engine never needs to multiply RGB values — it just reads shd[level][c].

Converting palettes for editors#

kbot pal convert understands several editor-friendly output formats:

The reverse direction — importing a .gpl or .pal (JASC) back into a binary TA .pal — works as long as the source has 256 entries.

Gotchas#

• Index 0 is not transparent by itself. Terrain, minimaps and backdrops draw it as black; a sprite frame is transparent only where its own key (or skip run) says so. kbot's terrain and minimap renders use an opaque palette.
• No magic numbers means weak validation. The only way to sanity-check a .pal is to require at least 1024 bytes and (optionally) that the alpha byte is zero in every entry.
• A lookup table of the wrong size is ignored by the game and rebuilt from the palette.
• .alp / .lht / .shd are not interchangeable. They're tuned for different effects; swapping them will produce visibly wrong shadows or lighting.
• TA: Kingdoms uses per-side PCX-embedded palettes, not the global .pal workflow. See PCX for the carrier-PCX trick.

Typical sizes#

See also#

• PCX — files with embedded palettes (and TA:K's palette-carrier convention).
• GAF — animations that use a palette but don't include one.
• TNT, SCT — paletted tile data on disk.
• Glossary — paletted image, lookup table.