Crusader_Decomp/docs/combat-dat.md

# COMBAT.DAT

## Scope

This note documents the shipped `COMBAT.DAT` used by the Crusader builds in this workspace.

Verified corpus facts:

- `STATIC/COMBAT.DAT`, `STATIC_1.01/COMBAT.DAT`, `STATIC_DEMO/COMBAT.DAT`, `STATIC_JP/COMBAT.DAT`, `STATIC_REGRET/COMBAT.DAT`, and `STATIC_REGRET_DEMO/COMBAT.DAT` are byte-identical.
- All six files are `1734` bytes and share SHA-256 `c6097a721141a2e66ec6d0cd578427305f28ae9efe8a206bd5cf946ce2075faf`.
- ScummVM's Crusader support code and the live `CRUSADER.EXE` database agree that this file drives NPC ranged-combat tactics through a small bytecode interpreter.

This note uses three evidence sources together:

- direct binary parsing of the shipped `COMBAT.DAT`
- live `CRUSADER.EXE` function/type names already present in the workspace export map
- ScummVM Crusader-source behavior as a readable reference model for the tactic interpreter

## High-Level Findings

- The file is a small FLEX-style archive with `14` populated tactic records.
- Each tactic record has a zero-padded `16`-byte name, followed by four `uint16` block offsets, followed by bytecode.
- In the shipped data, only block `0` and block `1` matter. Block `0` acts like an entry/setup phase. Block `1` acts like the steady-state loop. The third and fourth offset slots are present but only contain near-EOF placeholder values in this file.
- The tactic bytecode is not just a name table. It is real AI scripting: face target, move, pathfind, test line-of-fire, loop, jump, sleep, and switch tactic/block.
- Several tactics are waypoint-driven. ScummVM identifies opcode `0xA6` as a search for nearby shape `0x33A` marker objects by frame number; that matches the naming of `OneToTwo`, `ThreeToFour`, `EggHopper1`, and `123_Shoot`.
- There is one notable model discrepancy to keep in mind: the shipped archive contains a valid entry `0` named `Dumb`, but ScummVM still special-cases tactic number `0` as a generic built-in attack path rather than always interpreting `COMBAT.DAT` entry `0`. Treat that as an open compatibility detail rather than silently preferring one model.

## Archive Layout

### Outer Container

Observed on-disk structure:

- file size: `0x06c6`
- first populated record starts at `0x0280`
- archive directory begins at `0x0080`
- directory entries are `8` bytes each: `<uint32 offset, uint32 length>`
- the shipped file leaves most directory slots empty and populates only `14` entries

Populated record table:

| Index | File offset | Length | Name |
|------:|------------:|-------:|------|
| 0 | `0x0280` | `0x004f` | `Dumb` |
| 1 | `0x02cf` | `0x003f` | `Pivot` |
| 2 | `0x030e` | `0x004f` | `Advance` |
| 3 | `0x035d` | `0x0047` | `Mental` |
| 4 | `0x03a4` | `0x0052` | `Careful` |
| 5 | `0x03f6` | `0x004c` | `OneToTwo` |
| 6 | `0x0442` | `0x004c` | `ThreeToFour` |
| 7 | `0x048e` | `0x0074` | `EggHopper1` |
| 8 | `0x0502` | `0x0056` | `StepOutShootNE` |
| 9 | `0x0558` | `0x005c` | `StepOutShootNW` |
| 10 | `0x05b4` | `0x0046` | `Random_CHAOS` |
| 11 | `0x05fa` | `0x003b` | `Static_Chaos` |
| 12 | `0x0635` | `0x0043` | `Stand_Choas` |
| 13 | `0x0678` | `0x004e` | `123_Shoot` |

Two names preserve the shipped typos/spelling:

- `Stand_Choas`
- `Random_CHAOS` / `Static_Chaos` mixed casing

### Inner Record Format

Per record:

| Offset | Size | Meaning |
|-------:|-----:|---------|
| `0x00` | `16` | ASCII tactic name, NUL-padded |
| `0x10` | `2` | block 0 start offset |
| `0x12` | `2` | block 1 start offset |
| `0x14` | `2` | block 2 start offset |
| `0x16` | `2` | block 3 start offset |
| `0x18+` | variable | bytecode stream |

Observed block-offset pattern:

- Most tactics use block 0 at `0x002c` and block 1 at `0x0031`.
- The waypoint tactics `OneToTwo`, `ThreeToFour`, and `123_Shoot` have a longer setup block and therefore move block 1 farther forward.
- The later two offset slots are usually `0x004d` and `0x004e` even when they point at the final sentinel bytes rather than real independent blocks.

ScummVM's comment in `combat_dat.h` says the format has `10x2-byte offsets`, but both its constructor and the live executable logic only use four offsets. The shipped file matches the implementation, not the stale comment.

## Live Executable Integration

The live `CRUSADER.EXE` export map already carries the important attack-process fields:

- `combatDatTacticPtr` at attack-process offset `0x45`
- `combatDatTacticPtr2` at `0x49`
- `combatDatTacticCurOffset` at `0x4d`
- `combatDatBlockNo` at `0x4f`
- `tacticNo` at `0x51`

Relevant live helpers:

- `1108:0586` `Attack_SetupForTacticNo`
- `1108:0506` `Attack_SetupForBlockNo`
- `10e8:3572` `NPC_GetNPCTacticNo`
- `10e8:358c` `NPC_SetNPCTacticNo`

Current best read of the runtime flow:

1. NPC state stores a tactic number in `ItemNPCData.field21_0x5c`.
2. `Attack_SetupForTacticNo` validates that the tactic slot has loaded COMBAT.DAT data, stores the selected tactic number in the attack process, and copies the far pointer to that archive entry into the process.
3. `Attack_SetupForBlockNo` selects one of the record's four offset words and seeds `combatDatTacticCurOffset` from it.
4. The attack-process main loop reads one opcode byte at a time from the selected block and executes it as AI logic.

ScummVM's Crusader attack-process code adds one more important detail:

- `readNextWordWithData()` treats any immediate operand `>= 33000` as an index into a `10`-entry tactic-local variable array instead of as a literal value.

The shipped `COMBAT.DAT` in this workspace does not appear to use that variable indirection. All operands decoded here are direct literals.

## Used Opcode Set

Only this subset is actually used by the shipped tactics:

| Opcode | Mnemonic | Meaning |
|------:|----------|---------|
| `0x84` | `set_target_objid` | Set attack target object id |
| `0x85` | `anim_walk` | Play walk/advance animation |
| `0x88` | `turn_left_90` | Turn `90` degrees left |
| `0x89` | `turn_right_90` | Turn `90` degrees right |
| `0x8a` | `fire_small_if_clear` | Fire if line-of-fire is valid |
| `0x8d` | `pathfind_home` | Pathfind to actor home position |
| `0x8f` | `pathfind_midpoint` | Pathfind to midpoint between actor and target |
| `0x93` | `sleep_scaled` | Sleep for N ticks, scaled by difficulty |
| `0x94` | `loiter` | Run a loiter sub-process for N ticks |
| `0x95` | `face_target` | Turn toward target center |
| `0x9a` | `jump_if_dist_lt_481` | Jump if target distance is under `481` |
| `0x9c` | `jump_if_shot_blocked` | Jump if `fireDistance()` fails |
| `0x9d` | `jump_if_shot_clear` | Jump if `fireDistance()` succeeds |
| `0x9f` | `loop_begin` | Set loop counter and remember current stream position |
| `0xa6` | `pathfind_marker_frame` | Find nearby shape `0x33a` marker by frame and pathfind to it |
| `0xa9` | `face_east` | Turn east |
| `0xaa` | `face_west` | Turn west |
| `0xc0` | `jump` | Unconditional jump to stream offset |
| `0xc1` | `loop_end` | Decrement loop counter and jump back while nonzero |
| `0xff` | `flip_to_block1_restart` | If still in block 0, switch to block 1; then restart current block |

Practical interpretation of `0xff` in shipped data:

- In block `0`, it is a one-way handoff into block `1`.
- In block `1`, it behaves like `restart block 1 forever`.

That is why most tactics have a very short block `0`: setup once, then live in block `1`.

## Tactic Catalog

### 0. `Dumb`

Role:

- simplest mobile shooter with midpoint fallback

Decoded behavior:

- block 0: target object `1`, face target, then hand off to block 1
- block 1:
  - if a shot is already clear, jump straight into a `3`-iteration fire loop
  - otherwise pathfind to the midpoint between NPC and target, face target, and re-test line-of-fire
  - if still not clear after midpoint attempts, loiter briefly
  - once clear, loop `3` times: face target, fire, sleep `30`
  - restart block 1

Human read:

- close some distance toward a firing lane, then burst-fire three times

### 1. `Pivot`

Role:

- stationary pivot-and-shoot burst

Decoded behavior:

- block 0: target object `1`, face target, hand off
- block 1:
  - if line-of-fire is clear, enter a `3`-shot loop immediately
  - loop body: face target, fire, sleep `30`
  - restart

Human read:

- no movement logic beyond facing the target; just turn and shoot in bursts

### 2. `Advance`

Role:

- move forward between bursts if a clear shot is available; midpoint fallback otherwise

Decoded behavior:

- block 0: target object `1`, face target, hand off
- block 1:
  - face target
  - if shot is blocked, jump to midpoint-reposition logic
  - otherwise run a `3`-iteration loop: face target, fire, loop
  - sleep `30`
  - play walk animation
  - restart
  - midpoint branch: pathfind midpoint, face target, re-test for clear shot, loiter briefly if still blocked, restart

Human read:

- pressure forward when able to shoot, otherwise drift toward a midpoint lane until a shot opens

### 3. `Mental`

Role:

- shoot if clear; otherwise midpoint hop and shoot

Decoded behavior:

- block 0: target object `1`, face target, hand off
- block 1:
  - if shot is blocked, pathfind to midpoint first
  - run a `3`-iteration fire loop
  - restart

Human read:

- simpler than `Advance`: it does not include the extra walk/sleep pressure cycle, only burst-fire with midpoint correction

### 4. `Careful`

Role:

- range-gated cautious shooter

Decoded behavior:

- block 0: target object `1`, face target, hand off
- block 1:
  - if target distance is not under `481`, loiter and restart
  - if within `481` and shot is clear, fire once and restart
  - if blocked, face target and test again
  - if still blocked, pathfind midpoint and test again
  - if still blocked, face target and test again
  - if still blocked after all of that, loiter briefly and restart

Human read:

- only engages at medium/close range and spends more effort finding a clean shot before moving or firing

### 5. `OneToTwo`

Role:

- shuttle between marker frame `1` and marker frame `2`

Decoded behavior:

- block 0:
  - target object `1`
  - pathfind to marker frame `1`
  - face target
  - hand off
- block 1:
  - pathfind to marker frame `2`
  - face target
  - run a `3`-iteration fire loop while line-of-fire is clear
  - return to marker frame `1`
  - face target
  - sleep `120`
  - restart block 1

Human read:

- waypoint-based peek-and-return behavior across two authored combat markers

### 6. `ThreeToFour`

Role:

- same pattern as `OneToTwo`, but between marker frames `3` and `4`

Decoded behavior:

- block 0: target object `1`, face target, pathfind marker `3`, hand off
- block 1:
  - pathfind marker `4`
  - face target
  - if shot is clear, run a `3`-shot burst loop
  - return to marker `3`
  - face target
  - sleep `120`
  - restart

Human read:

- authored two-point lateral or cover movement using a second pair of marker frames

### 7. `EggHopper1`

Role:

- multi-marker patrol shooter

Decoded behavior:

- block 0: target object `1`, face target, hand off
- block 1:
  - pathfind marker `0`, attempt a `3`-shot loop
  - pathfind marker `1`, attempt a `3`-shot loop
  - pathfind marker `2`, attempt a `3`-shot loop
  - pathfind marker `3`, attempt a `3`-shot loop
  - pathfind home
  - face target
  - restart

Human read:

- sweep across four authored combat markers in order, trying a short firing burst at each stop, then return home

### 8. `StepOutShootNE`

Role:

- east-west step-out gunner, nominally biased to an east-facing start

Decoded behavior:

- block 0: target object `1`, face east, hand off
- block 1:
  - walk outward
  - face target
  - up to `3` short fire attempts with `5`-tick delays
  - face west
  - walk back
  - face target
  - another `3` short fire attempts with `5`-tick delays
  - if blocked, wait `25` ticks instead of firing through
  - face east
  - restart

Human read:

- pop out from one side, take a short burst, step back across the lane, burst again, and reset orientation

### 9. `StepOutShootNW`

Role:

- mirror-image of `StepOutShootNE`, nominally biased to a west-facing start

Decoded behavior:

- block 0: target object `1`, face west, hand off
- block 1:
  - walk outward from the west-facing side
  - face target and attempt short burst fire
  - if blocked, delay `25`
  - face east and walk across
  - repeat the short-burst pattern
  - face west and restart

Human read:

- same authored cover-pop logic as the northeast variant, but with opposite home orientation

### 10. `Random_CHAOS`

Role:

- immediate short burst, then aggressive midpoint pressure

Decoded behavior:

- block 0:
  - target object `1`
  - face target
  - run a `2`-shot loop with `30`-tick sleeps
  - hand off
- block 1:
  - face target
  - pathfind midpoint
  - face target
  - run a `3`-shot loop with `30`-tick sleeps
  - restart block 1 forever

Human read:

- start with a short static burst, then keep pressing toward midpoint and firing

### 11. `Static_Chaos`

Role:

- pure stationary burst shooter

Decoded behavior:

- block 0: target object `1`, face target, hand off
- block 1:
  - face target
  - loop `3` times: fire, loop
  - sleep `30`
  - restart

Human read:

- no pathfinding at all; just keep facing and firing from the current spot

### 12. `Stand_Choas`

Role:

- stationary turret-like spread pattern

Decoded behavior:

- block 0: target object `1`, hand off
- block 1:
  - face target
  - if shot is clear, fire once and skip to the post-shot delay
  - otherwise rotate and fire in a fixed sweep: left, original/right-adjusted, then right again
  - sleep `30`
  - face target
  - restart

Human read:

- a stand-and-sweep pattern for targets that are partially obstructed or moving across the arc

### 13. `123_Shoot`

Role:

- two marker hops followed by midpoint pressure

Decoded behavior:

- block 0:
  - target object `1`
  - face target
  - pathfind marker `0`
  - face target
  - pathfind marker `1`
  - face target
  - run a `2`-shot loop
  - hand off
- block 1:
  - face target
  - pathfind midpoint
  - run a `3`-shot loop
  - restart

Human read:

- staged opening movement across authored markers, then transition into a more ordinary midpoint-pressure gunner

## Pattern Summary

Across the whole file, the tactics cluster into a few clear families:

| Family | Tactics | Shared idea |
|--------|---------|-------------|
| stationary shooters | `Pivot`, `Static_Chaos`, `Stand_Choas` | little or no movement; rely on facing and burst loops |
| midpoint pressers | `Dumb`, `Advance`, `Mental`, `Random_CHAOS`, `123_Shoot` block 1 | move toward a midpoint lane when a shot is blocked |
| cautious/range-gated | `Careful` | only engage inside a distance window and avoid overcommitting |
| authored marker shuttles | `OneToTwo`, `ThreeToFour`, `EggHopper1`, `123_Shoot` block 0 | follow placed map markers keyed by frame number |
| step-out cover shooters | `StepOutShootNE`, `StepOutShootNW` | walk out, burst, walk back, repeat |

This is enough to treat `COMBAT.DAT` as a compact authored AI-script table rather than a loose name list.

## Open Questions

1. Tactic `0` is the main remaining semantic mismatch. The archive contains `Dumb` at index `0`, while ScummVM still routes `_tactic == 0` through `genericAttack()`. The live executable-side helper accepts tactic `0` as a normal COMBAT.DAT slot, so this needs a later direct compiled-side pass if exact retail precedence matters.
2. The later two per-record offset slots are structurally present but operationally unimportant in this file. A future pass could still check whether any retail code path ever selects block `2` or `3`.
3. The marker-search opcode `0xA6` is strongly understood from ScummVM and the tactic names, but the live-game name of shape `0x33A` and the exact authored map placement conventions remain better documented on the map-data side than in the live NE database.

## Practical RE Use

For future compiled-side work, the main safe takeaways are:

- `tacticNo` in NPC data is not cosmetic; it selects a real bytecode program.
- block `0` is usually an initialization or reposition phase; block `1` is the stable loop.
- the named tactics are portable data labels because the shipped file is identical across the local Remorse/Regret variants.
- waypoint-driven tactics should be interpreted together with local marker placements, not only from executable code.