Crusader_Decomp/docs/pentagram-crusader-reference.md

# Pentagram Crusader Reference

## Purpose

This note mines Pentagram's Ultima 8 / Crusader code and bundled docs for evidence that is useful to current Crusader reverse-engineering, especially the USECODE / VM lane.

It complements [docs/scummvm-crusader-reference.md](docs/scummvm-crusader-reference.md). Where Pentagram and ScummVM agree, that usually strengthens provenance, but not always confidence: several of the relevant ScummVM Ultima8 components appear to descend from the same Pentagram-era implementation ideas, so matching behavior between the two should not be treated as fully independent confirmation.

## Highest-Value Findings

1. Pentagram contains direct Crusader USECODE parser and VM support, not just generic U8 notes.
   Files: `convert/crusader/ConvertUsecodeCrusader.h`, `usecode/UsecodeFlex.cpp`, `usecode/Usecode.cpp`, `usecode/UCMachine.cpp`, `usecode/remorseintrinsics.h`, `kernel/GUIApp.cpp`.

2. Pentagram's older U8 USECODE documentation is still useful as contrast material because it shows which parts of the object/event model stayed stable and which parts changed in Crusader.
   File: `docs/u8usecode.txt`.

3. Pentagram preserves one practical caution that ScummVM does not show as clearly: its Crusader runtime support is incomplete.
   Files: `FAQ`, `world/Item.cpp`, `games/RemorseGame.cpp`.

4. Pentagram also records a few engine-format deltas that are useful outside USECODE, including Crusader map coordinate scaling, larger map chunks, and a wider Crusader `typeflag.dat` record.
   Files: `world/Map.cpp`, `world/CurrentMap.cpp`, `graphics/TypeFlags.cpp`.

## Direct Pentagram Crusader Evidence

### USECODE class layout and event lookup

`usecode/UsecodeFlex.cpp` matches the broad Crusader model already noted from ScummVM:

- class body object = `classid + 2`
- class names come from object `1` at `name_object + 4 + 13 * classid`
- Crusader class base offset is read from bytes `8..11` of the class object and decremented by `1`
- Crusader event count is computed as `(get_class_base_offset(classid) + 19) / 6`

`usecode/Usecode.cpp` then resolves Crusader event offsets from class data at `20 + 6 * eventid`, using bytes `+2..+5` of each 6-byte row as the code offset.

Implication for current RE:

- Pentagram independently preserves the same `classid + 2` and 6-byte event-row reading used in the ScummVM note.
- The shared `(base + 19) / 6` event-count rule should still be treated carefully in current owner-loaded/raw EUSECODE work, because local binary validation already showed that this shared Pentagram/ScummVM rule is not a clean fit for sampled raw class records.
- In other words, Pentagram is strong provenance for the implementation lineage, but not a reason to override validated binary-side arithmetic.

### Crusader event-name table

`convert/crusader/ConvertUsecodeCrusader.h` provides a named Crusader event table for `0x00..0x1f`:

- clear names: `look`, `use`, `anim`, `setActivity`, `cachein`, `hit`, `gotHit`, `hatch`, `schedule`, `release`, `combine`, `calledFromAnim`, `enterFastArea`, `leaveFastArea`, `justMoved`, `AvatarStoleSomething`, `animGetHit`
- weak placeholders remain for `0x0a`, `0x0b`, `0x0d`, `0x11`, and `0x15..0x1f`

This is slightly rougher than the current ScummVM note in naming quality, but it is still useful because it shows which ordinals were already considered understood in the older Pentagram work and which ones remained unresolved.

### Crusader call opcode semantics inside the VM

`usecode/UCMachine.cpp` contains one especially useful comment-backed distinction:

- U8 opcode `0x11` calls a function at an explicit class/code offset
- Crusader opcode `0x11` calls function number `yy yy` of class `xx xx`, then translates that number through `get_class_event()`

That matters for current USECODE analysis because it reinforces the reading that Crusader bytecode is event-ordinal-driven in places where U8 was direct-offset-driven.

### Remorse intrinsic runtime table exists, but it is partial and sparse

`kernel/GUIApp.cpp` creates `UCMachine(RemorseIntrinsics, 308)` for Remorse, and `usecode/remorseintrinsics.h` holds that live runtime table.

What is useful:

- it confirms a real Remorse-specific runtime intrinsic table with at least `308` entries
- some entries are already mapped to concrete engine hooks such as frame/shape/status/quality accessors, item creation, movement helpers, egg helpers, and timer-tick access

What is not useful enough yet:

- the table is far sparser and rougher than ScummVM's later Remorse/Regret intrinsic descriptions
- many entries are still `0` or placeholder comments

Practical use:

- treat Pentagram intrinsics as secondary hints or provenance for older naming work
- prefer ScummVM for higher-coverage intrinsic labeling
- prefer raw binary behavior over either table for actual renames

### Version-sensitive global evidence

Pentagram's scratch notes add one useful wrinkle to the global-slot story:

- `docs/scratch/globals/remorse1.01.txt` starts with `global_address 003D`
- `docs/scratch/globals/regret1.01.txt` starts with `global_address 001E`

Cross-reference with ScummVM:

- the existing ScummVM note records Remorse global `0x003c` and Regret global `0x001e`

Safest read:

- Regret lines up cleanly at `0x001e`
- Remorse appears version-sensitive or notation-sensitive between Pentagram artifacts and later ScummVM code (`0x003d` in the Pentagram scratch output for Remorse 1.01 versus `0x003c` in the ScummVM runtime initialization path)

Implication for RE:

- keep Remorse global-slot claims version-tagged when possible
- do not collapse `0x003c` and `0x003d` into one unqualified global statement without checking game/version context

## U8-Specific Documentation That Still Helps

### `docs/u8usecode.txt`

This file is U8-specific, not direct Crusader evidence, but it is still useful in three ways.

First, it documents the older U8 class/object indexing model:

- object `0` = global flag names
- object `1` = usecode function names
- object `2 + shape` = shape-linked usecode body
- object `1026 + npc` = NPC-linked usecode body

Second, it records the classic U8 per-class layout:

- 12-byte header prefix
- 32 event pointers
- code body after that table

Third, it preserves an older event-meaning list for ordinals `0x00..0x1f`.

Why it still matters for Crusader:

- many semantic event labels survive into the Crusader table: `look`, `use`, `anim`, `cachein`, `hit`, `gotHit`, `hatch`, `schedule`, `release`, `combine`, `enterFastArea`, `leaveFastArea`, `AvatarStoleSomething`
- the document makes the Crusader deltas clearer: Crusader moved away from a fixed 32 x 4-byte event-pointer table and instead uses a 6-byte-per-event structure with event-number lookup in the VM

Recommended use:

- use `u8usecode.txt` as a contrast document for inherited VM concepts and event semantics
- do not use it as direct proof of Crusader container layout or opcode contracts

## Cross-Reference Against The Existing ScummVM Note

### Where Pentagram and ScummVM clearly agree

Both references point to the same core Crusader USECODE model:

- `classid + 2` class lookup
- class names in object `1`
- bytes `8..11` as the class header field used for Crusader code/event addressing
- 6-byte Crusader event rows
- named event ordinals `0x00..0x1f`
- a Crusader-specific VM/global path rather than a straight U8 reuse

This agreement is useful because it shows the model is not a one-off local interpretation.

### Where Pentagram adds something materially useful

Pentagram contributes a few things the ScummVM note did not emphasize as strongly:

- older U8 documentation that makes Crusader structural deltas easier to isolate
- explicit confirmation in `UCMachine.cpp` that Crusader opcode `0x11` is event-number dispatch, not raw offset dispatch
- scratch global dumps that expose version-sensitive Remorse versus Regret behavior
- explicit incompleteness warnings in the project itself, which help calibrate how much authority to assign to runtime behavior

### Where Pentagram should not increase confidence much

For the current header/count dispute in owner-loaded/raw EUSECODE parsing, Pentagram and ScummVM agreeing with each other does not settle the question.

Reason:

- the relevant Pentagram and ScummVM Crusader USECODE code paths are very close in structure
- that makes them best treated as one implementation lineage, not two independent external confirmations

Current rule for RE remains:

- use Pentagram/ScummVM to anchor object indexing, row size, event labels, and VM intent
- keep the local binary-validated class-header arithmetic as the authority when the shared engine code disagrees with sampled Crusader records

## Non-USECODE Engine Findings Worth Keeping

These are lower priority than the USECODE sections, but still useful for future binary-side work.

### Map loading

`world/Map.cpp` shows that Crusader on-disk map records are still read as 16-byte records, but Pentagram doubles `x` and `y` after loading when `GAME_IS_CRUSADER`.

Implication:

- if a raw loader appears to scale map coordinates or if current external-map tooling sees a factor-of-two mismatch, Pentagram provides a concrete engine-side reason to test that path

### Current map chunking

`world/CurrentMap.cpp` sets `mapChunkSize = 1024` for Crusader versus `512` for U8.

Implication:

- this matches the broader cross-project pattern that Crusader is not just U8 data with renamed files; some world/grid assumptions are materially different

### Crusader `typeflag.dat`

`graphics/TypeFlags.cpp` switches Crusader to 9-byte records instead of U8's 8-byte records, with extended family-bit handling and multiple Crusader-only flag placeholders.

Implication:

- Crusader `typeflag.dat` should continue to be treated as its own format family
- any local parser or reverse-engineered structure should not inherit the U8 8-byte layout blindly

## Confidence Limits

Pentagram is valuable, but only in bounded ways.

Direct reasons for caution:

- `FAQ` says Crusader support was a future goal, not a completed feature
- `games/RemorseGame.cpp` is clearly incomplete compared with the ScummVM Crusader startup path
- `world/Item.cpp` explicitly disables all Crusader usecode events except `use()`

So for current Crusader RE, the best weighting is:

- high confidence: parser/disassembler layout clues, event ordinals, VM intent, container/indexing models, file-format deltas
- medium confidence: sparse Remorse intrinsic names and scratch global artifacts
- low confidence: full runtime behavior, startup semantics, and any absence-based conclusion from Pentagram's Crusader execution path

## Most Useful Pentagram Files

- `convert/crusader/ConvertUsecodeCrusader.h`
- `usecode/UsecodeFlex.cpp`
- `usecode/Usecode.cpp`
- `usecode/UCMachine.cpp`
- `docs/u8usecode.txt`
- `docs/scratch/globals/remorse1.01.txt`
- `world/Item.cpp`
- `graphics/TypeFlags.cpp`
- `world/Map.cpp`
- `world/CurrentMap.cpp`

## Practical RE Follow-Ups

1. Keep using Pentagram and ScummVM event names as slot-label hints only, especially for `0x0a`, `0x0b`, `0x11`, and the still-placeholder high ordinals.
2. When documenting Crusader USECODE VM behavior, cite Pentagram's `opcode 0x11 = class/event dispatch` distinction alongside the existing ScummVM reference.
3. Keep local owner-loaded/raw EUSECODE arithmetic authoritative over the shared Pentagram/ScummVM `(base + 19) / 6` rule until a direct main USECODE sample proves otherwise.
4. Tag Remorse global-slot references with version context when using Pentagram scratch outputs.
5. Reuse Pentagram's map/typeflag deltas when a future binary pass returns to world loaders or shape/type metadata.
6. Treat missing behavior in Pentagram's Crusader runtime as non-evidence unless ScummVM or raw binary analysis supports the same absence.