125 lines
10 KiB
Markdown
125 lines
10 KiB
Markdown
---
|
||
applyTo: "**"
|
||
---
|
||
|
||
# Crusader Ghidra Workflow
|
||
|
||
## Safety Guardrails
|
||
|
||
- Never create a git commit on your own.
|
||
- Never run a command that may delete files outside a temporary folder unless you first ask the user with `vscode_askQuestions` and get explicit confirmation.
|
||
- If a request could remove or overwrite repository files, pause and confirm before proceeding.
|
||
|
||
- Active target is the NE Ghidra program `CRUSADER.EXE` unless explicitly stated otherwise.
|
||
- Use Ghidra MCP tools for analysis, decompilation, renaming, comments, and xref work.
|
||
- Treat the verified `CRUSADER-RAW.EXE` work already captured in `docs/` and notes as a cross-reference evidence base for the live `CRUSADER.EXE` session, not as the default active program.
|
||
- Avoid speculative renames. Prefer names that are supported by one of these:
|
||
- verified raw mapping from standalone segment work
|
||
- direct string evidence
|
||
- clear call/field behavior in decompiler or disassembly
|
||
- xref relationships to already-named functions
|
||
- When porting names from standalone segment extracts or prior raw full-EXE work into `CRUSADER.EXE`, use only verified base mappings and keep the older raw address evidence with the live NE address where practical.
|
||
|
||
# Verified Raw Mapping Rules
|
||
|
||
- `seg001` raw base = `0x6E570`
|
||
- `seg021` raw base = `0x87170`
|
||
- Porting formula: `raw_full_exe_flat = verified_segment_base + standalone_segment_relative_offset`
|
||
- `seg001` and `seg021` both contain a keyboard handler; keep the seg001 name as `seg001_input_keyboard_handler` to avoid collision.
|
||
|
||
# Working Method
|
||
|
||
- Prefer a single decompile call first.
|
||
- If the decompiler collapses to thunk-heavy output, use one disassembly lookup to confirm the wrapper or parameter setup.
|
||
- **When `decompile_function` output is too large** (>~50KB), the result is written to a temp JSON file that `read_file` returns as empty `{}`. Use `disassemble_function` instead — it returns inline assembly directly and is fully navigable for large functions.
|
||
- Cross-reference new `CRUSADER.EXE` findings against the old raw notes before promoting a rename or behavioral claim. If the two differ, keep both addresses and explain the mismatch instead of silently preferring one.
|
||
- Add a short decompiler comment when a rename is mapped from verified notes so the provenance stays visible in Ghidra.
|
||
- Keep `crusader_decompilation_notes.md` updated after each verified batch. That file is now a short index — append new analysis to the appropriate file in `docs/` and add a row to the index table if a new file is created.
|
||
- Keep `crusader_segment_coverage_ledger.csv` updated after each verified batch whenever a segment can be promoted or reclassified.
|
||
- Keep the progress section in `plan-mid.md` updated after each verified batch so the next pass can resume from the exact stopping point.
|
||
- Keep `ghidra_mcp_wishlist.md` updated whenever the workflow hits a missing MCP capability and has to fall back to PyGhidra or another local-only path.
|
||
- Each wishlist entry should be short and concrete: what MCP lacked, what command/script/tool had to replace it, and what a useful MCP endpoint or behavior would look like.
|
||
- Record raw-import addresses alongside original segment-relative offsets when porting names.
|
||
- **Always use `rename_function_by_address`** — `rename_function` (by name) fails with "must have required property 'old_name'" and is broken. Use `"function_address": "000c:XXXX"` format.
|
||
- For substantive RE batches, end with at least 6 concrete future steps unless the task is fully closed and there are genuinely fewer defensible next actions.
|
||
- When a batch analyzes currently unnamed Ghidra functions and the behavior is clear enough, rename them in Ghidra instead of leaving them as positional `FUN_xxxx_xxxx` placeholders.
|
||
-
|
||
- **Terminal execution rule:** Always write multi-line Python scripts to a temporary `.py` file and execute that file with the Python interpreter instead of pasting multi-line Python directly into an interactive terminal. This avoids paste/encoding/line-ending issues and ensures the script runs in the expected environment.
|
||
# Executable Write Safety
|
||
|
||
- Normal Ghidra database work on `CRUSADER.EXE` remains in scope: renames, comments, prototypes, local-variable/type cleanup, function creation/deletion, and boundary repair are allowed unless the user says otherwise.
|
||
- Treat only actual program-byte changes as destructive actions: byte patching, write-back flows that alter loaded memory bytes, or any operation that would make the executable differ from the original program bytes.
|
||
- Never run destructive byte-write operations against the main reference executable in the project.
|
||
- Only use byte-patching or other byte-diverging executable write flows when the target program is an explicitly writable patch target, normally a program in the `/Writable` folder.
|
||
- Treat `CRUSADER.EXE`, `CRUSADER-RAW.EXE`, and other main reference executables as read-only with respect to program bytes unless the user explicitly says otherwise.
|
||
- Before running write endpoints such as `patch_bytes_and_reanalyze` or any PyGhidra byte-write script, verify that the selected program is the intended writable copy, not the reference executable.
|
||
- If the target program is not clearly a writable patch copy in `/Writable`, stop and ask the user before performing the byte write.
|
||
|
||
# PyGhidra Fallback
|
||
|
||
- Use the local PyGhidra toolkit in `tools/pyghidra_crusader` when MCP is missing an operation such as function creation, deletion, or batched scripted edits.
|
||
- When PyGhidra is needed because MCP lacks a required operation, append a note to `ghidra_mcp_wishlist.md` in the same batch if the gap is not already documented.
|
||
- The workspace-local Python environment for this toolkit is `.venv-pyghidra311`, created from `C:\Users\Maddo\.pyenv\pyenv-win\versions\3.11.6\python.exe` and installed from the bundled Ghidra 12.0.4 offline packages.
|
||
- Default install dir for the toolkit is `I:\Apps\ghidra_12.0.4_PUBLIC`.
|
||
- Invoke the toolkit with `\.venv-pyghidra311\Scripts\python.exe -m tools.pyghidra_crusader ...` from the repo root.
|
||
- Rebuild or refresh that environment with `powershell -ExecutionPolicy Bypass -File .\tools\pyghidra_crusader\bootstrap_env.ps1` from the repo root when the local PyGhidra packages drift or a Ghidra upgrade lands.
|
||
- Keep PyGhidra batches small too: prefer one focused repair plan or 1-5 direct edits at a time.
|
||
- Write operations require the Ghidra project to open successfully. If `Crusader.lock` is present because the GUI owns the project, close Ghidra first or operate on a project copy.
|
||
- If the workflow needs the user to change Ghidra state, use the ask-questions tool with a yes/no confirmation prompt instead of plain text. Ask the user to close Ghidra before PyGhidra write commands, and ask the user to open the Ghidra project before MCP server commands. The prompt should briefly describe exactly what to do and instruct the user to answer `Yes` only after the action is complete.
|
||
|
||
# Current Verified Raw-Import Ports
|
||
|
||
These remain valid cross-reference anchors for `CRUSADER.EXE` work. Keep the old raw-import addresses and original segment-relative offsets in notes/comments when using them to support live NE renames.
|
||
|
||
- `0006:e5d0` = `cursor_update_hover` from seg001 `0x0060`
|
||
- `0008:7377` = `entity_count_by_type_a` from seg021 `0x0207`
|
||
- `0007:28ce` = `shot_entity_alloc` from seg001 `0x435e`
|
||
- `0007:2a19` = `shot_entity_free` from seg001 `0x44a9`
|
||
- `0007:2bc9` = `projectile_init_vector` from seg001 `0x4659`
|
||
- `0007:3001` = `entity_fire_weapon` from seg001 `0x4a91`
|
||
- `0007:3088` = `fire_weapon_from_cursor` from seg001 `0x4b18`
|
||
- `0007:30e8` = `projectile_check_hit` from seg001 `0x4b78`
|
||
- `0007:319e` = `projectile_step_update` from seg001 `0x4c2e`
|
||
- `0007:3298` = `projectile_trace_ray` from seg001 `0x4d28`
|
||
- `0007:371d` = `projectile_update_tick` from seg001 `0x51ad`
|
||
- `0007:4009` = `projectile_apply_hit` from seg001 `0x5a99`
|
||
|
||
# Named 000e: Functions (direct analysis — not segment-ported)
|
||
|
||
## Parser Cluster (`000e:34xx–38xx`)
|
||
- `000e:345e` = `record_table_init`
|
||
- `000e:34cc` = `record_table_destroy`
|
||
- `000e:35c6` = `record_table_release_buffer`
|
||
- `000e:35ef` = `record_table_next_slot`
|
||
- `000e:3639` = `record_table_parse_buffer`
|
||
- `000e:3798` = `record_parser_read_line`
|
||
- `000e:38f8` = `record_parser_find_marker`
|
||
|
||
## RIFF/Animation Cluster (`000e:03xx–2xxx`)
|
||
- `000e:2a28` = `riff_find_chunk_by_type` (RIFF LIST/RIFF walker; FourCC match at chunk+8)
|
||
- `000e:2104` = `animation_start` (finds "movi" chunk, inits timing ring buffer, kicks advance)
|
||
- `000e:12f4` = `animation_advance_frame` (fixed-point 0x1000 timer stepper, ring buffer update)
|
||
- `000e:103f` = `animation_tick` (guard wrapper — checks +0xd4 != -1, calls advance_frame)
|
||
- `000e:06f7` = `anim_load_audio_frame` (checks "01wb" chunk tag 0x62773130, copies audio into ring buffer)
|
||
|
||
## Constructor/Assert Helpers (`000e:22xx–29xx`)
|
||
- `000e:223d` = `assert_alive_sentinel` (expects +0xd4 == -1; traps on mismatch)
|
||
- `000e:2777` = `animation_ctor_variant_a` (alloc + init flags + chained init/assert/finalize)
|
||
- `000e:2860` = `animation_ctor_variant_b` (variant A with extra +0x109 init)
|
||
- `000e:2969` = `animation_ctor_variant_c` (default static flag profile +0x4c=0xd)
|
||
|
||
# Documentation Structure
|
||
|
||
Detailed RE notes live in the `docs/` folder. `crusader_decompilation_notes.md` is a short index. Unless a doc says otherwise, read raw-focused docs as evidence sources to be cross-checked against the live `CRUSADER.EXE` session.
|
||
|
||
| File | Topic |
|
||
|------|-------|
|
||
| `docs/overview.md` | Binary overview, address layout, segment map, next steps |
|
||
| `docs/phar-lap-extender.md` | DOS extender functions and string references |
|
||
| `docs/ne-segment1.md` | NE Segment 1: entity system, cheat system, full game logic analysis |
|
||
| `docs/raw-porting-progress.md` | seg091 RNG, 0x4588 callbacks, 0007 gameplay batches, `snap_entity_to_ground` |
|
||
| `docs/raw-000e.md` | 000e parser cluster and RIFF/animation subsystem |
|
||
| `docs/raw-0007-rendering.md` | Draw list, scroll/camera, coordinate transforms, tile visibility |
|
||
| `docs/raw-0008-000c.md` | 0008 dispatch helpers and 000c state machine |
|
||
| `docs/raw-000a-000d.md` | Tracked handles, cache manager, seg082 allocator, palette helpers, seg004/005 startup |
|
||
| `docs/far-call-targets.md` | Top-104 far-call targets (Tiers 1–5), supporting functions, analysis gaps |
|