Crusader_Decomp/.github/instructions/ghidra.instructions.md

applyTo
**

Crusader Ghidra Workflow

• Active target is the raw full-EXE Ghidra program CRUSADER-RAW.EXE unless explicitly stated otherwise.
• Use Ghidra MCP tools for analysis, decompilation, renaming, comments, and xref work.
• 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 into CRUSADER-RAW.EXE, use only verified base mappings.

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.
• 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.

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 11.3.2 offline packages.
• Default install dir for the toolkit is I:\Apps\ghidra_11.3.2_PUBLIC.
• Invoke the toolkit with \.venv-pyghidra311\Scripts\python.exe -m tools.pyghidra_crusader ... from the repo root.
• 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

• 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.

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