How Steel Panthers Stores a Battle

Overview — three games, one lineage

All three games describe the same kind of object — a tactical scenario: a hex map, two orders of battle, leaders, victory locations, and battlefield obstacles. What differs is how those records are physically laid out on disk, and that difference grew more sophisticated with each generation.

The toolchain's job is to read the two legacy formats, normalize them into a portable JSON intermediate, and then write that JSON into a live SPCAMO file — converting the map geometry and translating every nation, unit class, and weapon index between the games' incompatible numbering schemes along the way.

Common building blocks

SP2 (compressed) and SPCAMO share the same container DNA — an artifact of the SSI → CAMO engine lineage. Understanding these three primitives unlocks both formats at once.

The section container

A compressed file is a 20-byte file header followed by a stream of self-describing sections. There is no central directory; you parse sequentially until you run out of bytes.

Per-section header — 9 bytes

* The length field is stored signed and is sometimes negative; readers take the absolute value. After the payload, the next section header begins immediately.

The RLE codec

Section payloads marked compressed use a trivially simple run-length scheme. The single lead byte decides everything:

// decompress: lead byte selects run vs. literal
while (i < data.length) {
  lead = data[i++];
  if (lead > 0x80) {            // RUN
    run = lead - 0x80;
    val = data[i++];
    emit run copies of val;
  } else {                     // LITERAL
    emit next lead bytes verbatim;
  }
}

The encoder is the mirror image: runs of identical bytes (up to 127) become a 0x80+n / value pair, everything else is copied as literal packets of up to 128 bytes. Because the editor must round-trip files, it ships both halves of this codec and rebuilds only the sections it touched, copying all others through byte-for-byte.

The hex coordinate system

Maps are stored column-major. The constant that ties everything together in SPCAMO is the stride MAPSIZE = 200: any per-hex array is indexed as hex = x · 200 + y. Two map grids coexist — the standalone map file is 100 columns wide, while a full scenario grid is 160 columns × 200 rows, which is why map import has to expand geometry (see §07).

SP1 — the flat-file era

SP1 has no container at all. The scenario is one large fixed-size image of the game's memory, and the reader simply reaches into known absolute offsets. Records are stored as parallel arrays rather than structs: to assemble unit #7 you gather its name, class, position, weapons, ammo and armor from six different regions of the file.

Scenario header block

The scenario parameters sit in a tight cluster just past offset 37,500. Battle type is encoded as a two-byte pair (bf1,bf2); e.g. (1,2) = “Player 1 Assaults”, (1,1) = “Meeting Engagement”.

Unit parallel arrays

Each domain of unit data lives in its own striped region. Positions are 19-byte records split by side; soft units (infantry, guns) carry all-zero armor.

Leaders & obstacles

Leaders are striped much like units: names at offset 0 (15 B each), ranks at 8500, rally at 9000, skills (infantry/artillery/armor) at 9500. Battlefield obstacles live in a 19-byte record array beginning at offset 301236 (0x49854), organized into blocks of 100 slots.

Entrenchments are SP1's most baroque structure: they are reconstructed from paired blocks — a position-marker record in one block and a graphic/type record in a parallel block share the same slot index. Block 2/3 hold P1/P2 position markers; block 6/7 hold the matching graphic tiles that name the emplacement (foxhole vs. sandbag).

SP2 — one reader, two formats

SP2 sits on the fault line between eras. The reader sniffs the first 16 bytes and the file size to decide which layout it is dealing with, then presents a unified view either way.

Uncompressed section anchors

The unit record (Section 1, 220 bytes)

Unlike SP1's parallel arrays, SP2 packs a unit into one contiguous record. Crucially, records are not split by side — the side is read from a single control byte at +178.

Obstacles & entrenchments in Section 17

SP2 folds both unit positions and battlefield obstacles into Section 17 — 5000 records of 19 bytes, organized as ten blocks of 500. Obstacle type is the byte at +14; the side at +15.

The strength = 0xFFFF marker is what distinguishes a foxhole/sandbag emplacement from a destructive obstacle sharing the same block. Tile IDs name the type — sandbags 1430–1433, foxholes 1464–1466 — a numbering that SPCAMO inherits unchanged.

SPCAMO — the SPCTS v3 container

This is the live format: the editor both reads and writes it, so its structure is documented in the most detail. It is the §01 container with magic SPCTS_SAVE_V100, and its records carry explicit structural metadata — side, validity, formation parentage — that the legacy formats only implied by position.

Section inventory

The unit record (Section 1, 261 bytes)

Where SP1 implied side by slot range and SP2 used one control byte, SPCAMO makes everything explicit and self-consistent — which is what lets the editor insert, delete and re-side units safely.

Scenario metadata (Section 37)

594 decompressed bytes hold the whole scenario envelope. Victory locations are four parallel 21-entry arrays; an empty slot is 0xDE.

Cross-format comparison

Read sideways, the same conceptual record takes three very different shapes. This is the table to keep open when writing a converter.

Two invariants survive every generation and are worth committing to memory: the 19-byte obstacle/position record and the entrenchment tile numbering (sandbags 1430–1433, foxholes 1464–1466). Everything else — container, striping, side encoding — was redesigned at least once.

Entrenchment deep-dive

Unit-level entrenchment is the one place where a single game concept is spread across three independent sections that must agree. It was the hardest part of the format to pin down, and it was settled empirically by diffing matched “entrenched / not-entrenched” save pairs for each side.

The three writes (per entrenched unit)

Section-8 hex byte is a bitfield

Because the byte is OR-combined rather than overwritten, the importer must read-modify-write: a hex that already holds a foxhole and gains a sandbag must end at 192, and a single hex may legitimately own two emplacement records in Section 17.

The map conversion chain

Maps are not converted in one hop. They are walked up a version ladder — SP1/SP2 geometry is first lifted into the intermediate SPWW2 v2.2 shape, then into v3, then wrapped into a full playable scenario.

The two source modules feed the same converter from different starting points. SP2 compressed files are already in v2.2 shape and pass through almost directly; SP2 uncompressed and all SP1 files have their map sections extracted and assembled into a synthetic STEEL2 blob first.

Geometry the stub must reconcile

• The v3 map file is 100 columns wide; a playable scenario grid is 160 × 200. SP_ScenStub.js expands each tile layer from 100 → 160 columns, column-major.
• v2.2 tile layers are 16,000 bytes each (sections 2–7); the elevation/extra layers use 12-, 13-, and 1-byte-per-hex records (sections 8, 28, 29).
• The expanded map sections are merged with blank non-map sections from an embedded template so the result is a complete, loadable SPCTS scenario rather than a bare map.

JSON import & cross-game translation

The reader app exports any SP1/SP2/SPCAMO scenario to a portable JSON. The editor's import handlers replay that JSON into a live SPCAMO file — and the difficult part is not the bytes, it is reconciling three games' incompatible numbering schemes.

Why translation is unavoidable

Nation, unit-class and weapon indices are per-game enumerations. SP2 nation 0 (“West Germany”) must become SPMBT nation 44 (“Germany”); an SP1 unit class must resolve to a concrete SPWW2 OBAT slot before its weapons and armor can be looked up. The unit importer therefore does more than copy fields — it re-homes each unit into the target game's order of battle, writes new Section 35 formation records, wires leader ranges, and lets the editor's patched writer lay down all structural Section-1 fields explicitly.

Entrenchment import — the two-phase flow

The entrenchment importer runs map obstacles first (dragon's teeth + mines from the JSON obstacles array), then prompts before touching units. On confirmation it reads the unitPersonalEntrenchments array, matches each record strictly by hex + side to an on-map unit, and performs the three §06 writes — honoring the source tile id so a foxhole stays a foxhole.

Scenario packaging

Distribution scenarios travel in ZIP packs. SP_Zip.js opens a pack, finds every .DAT, and pairs it with its .CMT sidecar — a 200-byte fixed record whose leading ASCIIZ string is the human-readable scenario title — matching by case-insensitive filename stem.

File inventory

What each module in the V5 release is responsible for. The data is intentionally fragmented across many files so the apps can lazy-load only the tables they need.

Offset appendix

A consolidated quick-reference of the magic numbers most often needed when writing tooling against these formats.

Magic & structural constants

Entrenchment write recipe (SPCAMO)

// for each entrenched unit at (x,y), side s:
S1[ slot*261 + 178 ] = 1;                       // ① dug-in flag
S17.block2.append({ x, y,                          // ② emplacement
     tile:pictureID, active:5,
     strength:0xFFFF, typ:1, side:s });
S8[ (x*200+y)*15 + 8 ] |= isFoxhole ? 0x40 : 0x80;  // ③ hex marker (OR)

Entrenchment tile ids (shared SP1 / SP2 / SPCAMO)