Crusader_Decomp/docs/crusader-disasm-reference.md

Crusader Disasm Reference Corpus

Purpose

This note records the reusable knowledge in the separate local project at K:/ghidra/crusader-disasm and how it should be consumed inside the main Crusader_Decomp workflow.

Treat that repo as an auxiliary evidence corpus, not as direct rename authority for CRUSADER-RAW.EXE or the NE-loaded CRUSADER.EXE program.

Main Assets

Handwritten notes

misc_crusader_notes.txt is a compact scratchpad with a few still-useful anchors:

• keyboard event/code notes: CTRL-M = 0x432, CTRL-L = 0x426, CTRL-V = 0x42f, CTRL-Q = 0x410
• shape/event examples: STEAM2 (shape 1297) is noted with event 15 (enterFastArea) and 24 animation frames
• SnapEgg (shape 0x4fe) is noted as entering the fast area and being handed to a SnapProcess
• chest/monitor examples preserve concrete shape ids and field snapshots that can be cross-checked against map/object dumps
• old standalone function labels such as FUN_1130_0896 are useful only as historical waypoints; they are not direct rename authority for the current raw or NE Ghidra databases

Safe use:

• event/id hinting
• shape-id cross-checks
• lead generation for later binary confirmation

Unsafe use:

• direct function renames based only on these handwritten notes
• assuming the old segment numbering matches the current CRUSADER-RAW.EXE or CRUSADER.EXE imports without a verified address mapping

Shape metadata tables

shapedata.txt and especially shapedata_more_complete.txt provide a broad Shape info N data 4(top),5,7,8 table.

Current best reuse:

• cross-check shapeinfo bytes and flags against item/entity behavior already seen in the binary
• identify repeated per-shape flag/value families before promoting any field meaning
• support later naming of shape-related globals, cache entries, and trigger/object classes

This is one of the strongest data-side additions in the external corpus because it is broad, structured, and easy to re-test locally.

Static map/object dumps

mapdump/map-item-dump.txt is a large coordinate/event-style dump of placed world items.

Current best reuse:

• correlate static placements with EVENT, NPCTRIG, CRUZTRIG, and related USECODE families
• cross-check specific shapes noted in misc_crusader_notes.txt against real map presence
• build targeted map-level test cases for later CRUSADER.EXE naming and annotation work

This file is valuable because it gives real world-layout evidence that complements the owner-loaded USECODE work already documented in docs/usecode-roundtrip-ir.md.

USECODE opcode list

usecode_opcodes.txt contains an extracted opcode table for the JP release of Crusader: No Remorse.

Useful properties:

• broad opcode coverage from 0x00 through 0x7b
• readable names for assignment, local/member reference, control-flow, spawn/process, and search-family operations
• a concrete local opcode vocabulary independent of ScummVM/Pentagram naming layers

Reuse rule:

• use these names as parser and report hints only
• do not assume the textual names alone are enough to rename compiled handlers in the DOS binary

Intrinsic and function dumps

The unkcoffs/ directory holds older cross-version name tables such as:

• reg_functions.txt
• rem_functions.txt
• reg_intrinsic_dump.txt
• rem_intrinsic_dump.txt
• u8_intrinsic_dump.txt

These dumps are useful because they preserve prior RE vocabulary for Remorse/Regret/U8 function and intrinsic families, including many item, actor, audio, palette, and world operations.

Current safe use:

• hint-only metadata for intrinsic ordinals, signatures, and broad subsystem labels
• cross-version comparison when a Remorse/Regret difference matters
• porting candidate generation for the NE CRUSADER.EXE project, where segment-based labels may be easier to reconcile than in the flat raw import

Current unsafe use:

• direct rename authority for modern Ghidra functions
• assuming one game's intrinsic numbering matches another without local confirmation

Combat data note

combat_dat/readme.txt records that the extracted combat.dat tactic files are identical between No Remorse and No Regret.

That is small but useful: tactic names from the combat data are portable labels and should be treated as version-stable unless contradicted by later binary evidence.

How This Fits The Existing Docs

This external corpus mainly strengthens four areas already active in Crusader_Decomp:

1. docs/usecode-roundtrip-ir.md The opcode list, intrinsic dumps, and static trigger/map data provide local cross-checks for the USECODE parser and event-family work.

2. docs/ne-segment1.md The handwritten note set preserves shape ids, keyboard/event codes, and gameplay object examples that can be matched against the segment-1 gameplay/input lane.

3. docs/raw-porting-progress.md The external notes add candidate gameplay/object labels and map-backed test targets, but they should remain supporting evidence until verified in the raw full-EXE database.

4. docs/overview.md The separate disasm repo is now part of the local evidence stack alongside ScummVM and Pentagram, but unlike those source ports it is a prior RE corpus tied directly to Crusader assets and old disassembly work.

Safe Reuse Policy

Use the external disasm repo for:

• opcode-name hints
• intrinsic/signature hints
• shape-id and map-placement cross-checks
• event-code and key-code lead generation
• candidate subsystem vocabulary before binary confirmation

Do not use it for:

• speculative raw-function renames
• address mapping without an explicit verified translation
• replacing direct binary evidence from CRUSADER-RAW.EXE or CRUSADER.EXE

Immediate Porting Frontier For CRUSADER.EXE

The next practical use of this corpus is not another raw-only note pass. It is a controlled porting pass into the NE-loaded CRUSADER.EXE project in Ghidra.

Best initial targets:

1. Port already-verified raw names that clearly correspond to NE-segment functions where the segment:offset identity can be confirmed directly.
2. Use unkcoffs/ function and intrinsic dumps as hint-only comparison tables when the NE database exposes clearer segment-local call structure than the flat raw import.
3. Use map-item-dump.txt plus shape tables to annotate trigger-heavy or object-heavy NE lanes before promoting any names.
4. Use usecode_opcodes.txt to keep future USECODE parser/report output aligned with an additional local opcode vocabulary, especially where ScummVM and Pentagram leave placeholders.

Recommended Order For The Next Porting Pass

1. Start with one small NE segment or subsystem that already has strong raw names or old disasm vocabulary.
2. Prefer functions with direct string, data-table, or caller-role evidence over unlabeled wrappers.
3. Use the map/shape corpus to explain data-driven objects first; use the intrinsic/function dumps only as secondary hints.
4. Record exact successful raw-to-NE name correspondences so later passes can reuse the mapping instead of re-deriving it.

Current High-Value Follow-Ups

• Build a shape-id crosswalk between shapedata_more_complete.txt, map-item-dump.txt, and the existing EVENT / NPCTRIG / CRUZTRIG families.
• Compare the handwritten key/event codes against the already-named cheat/input paths to see which parts of the old notes are now directly closed.
• Use rem_functions.txt / reg_functions.txt to identify conservative candidate names for still-positional NE functions, but only when the local caller/data evidence matches.
• Keep the external disasm corpus explicitly separated from ScummVM/Pentagram-derived evidence so provenance stays clear in future porting notes.