maddo/Crusader_Decomp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add Crusader-specific USECODE data and documentation

Browse source 
- Introduced new file `vm_mask_ladder.tsv` containing detailed mappings for Crusader USECODE VM masks and their associated descriptors.
- Added comprehensive documentation in `scummvm-crusader-reference.md` outlining the structure, findings, and implications for reverse-engineering the Crusader engine within ScummVM.
- Created `usecode-roundtrip-ir.md` to document the plan for converting Crusader USECODE bytes into a human-readable format, detailing the container layout, event names, and intrinsic tables.
- Implemented a PowerShell script `temp_usecode_sample.ps1` for extracting and analyzing USECODE data from the Crusader FLX files, providing insights into class and event structures.
This commit is contained in:
MaddoScientisto 2026-03-22 17:26:39 +01:00
commit de42fd1ea1
42 changed files with 21970 additions and 1522 deletions
Download patch file Download diff file Expand all files Collapse all files

6
crusader_segment_coverage_ledger.csv
View file

@ -89,7 +89,7 @@
"88","code","0xA2E00","0x523","None","","","","crusader_ne_segments.csv"
"89","code","0xA3400","0x373","None","","","","crusader_ne_segments.csv"
"90","code","0xA3800","0x9C6","None","","","","crusader_ne_segments.csv"
"91","code","0xA4400","0x6FA","Partial","Init/context RNG and runtime callback/video-state lifecycle","seg091_func_00fd; seg091_func_014d; rng_set_seed; rng_next_modulo; runtime_callback_object_init_once; runtime_callback_object_teardown_once; video_bios_state_snapshot; video_mode_set_and_record_state","00fd/014d still positional; callback object subsystem identity still unresolved","crusader_decompilation_notes.md; plan-mid.md"
"91","code","0xA4400","0x6FA","Partial","RNG, fatal-report helpers, and runtime callback/video-state lifecycle","fatal_error_report_fmt_a_and_exit; fatal_error_report_buffered_fmt_and_exit; fatal_error_report_fmt_c_and_exit; rng_set_seed; rng_next_modulo; runtime_callback_object_init_once; runtime_callback_object_teardown_once; video_bios_state_snapshot; video_mode_set_and_record_state","Exact fatal-report template text and callback object subsystem identity still need tighter recovery","crusader_decompilation_notes.md; plan-mid.md"
"92","code","0xA4E00","0x59E","None","","","","crusader_ne_segments.csv"
"93","code","0xA5600","0x4F1","None","","","","crusader_ne_segments.csv"
"94","code","0xA5E00","0x606","Partial","Tracked handle table control","tracked_entity_handle_table_init; tracked_entity_handle_table_shutdown; tracked_entity_handle_table_clear_and_dispatch","Downstream dispatch tail still unresolved","crusader_decompilation_notes.md"
@ -132,8 +132,8 @@
"131","code","0xCF000","0x44D","None","","","","crusader_ne_segments.csv"
"132","code","0xCF600","0x3EB8","None","","","","crusader_ne_segments.csv"
"133","code","0xD3800","0x215A","None","","","","crusader_ne_segments.csv"
"134","code","0xD6000","0xEF0","None","","","","crusader_ne_segments.csv"
"135","code","0xD7000","0x3B7","None","","","","crusader_ne_segments.csv"
"134","code","0xD6000","0xEF0","Foothold","VM runtime bootstrap and post-init seeding","entity_vm_runtime_init_from_path_if_configured; entity_vm_referent_registry_init; entity_vm_runtime_release_slots; entity_vm_runtime_init_slots","Configured path/global at 0x65a and the exact external file format behind the 0x6611 runtime owner table still need tighter classification","plan-mid.md; docs/raw-0008-000c.md"
"135","code","0xD7000","0x3B7","Foothold","VM runtime owner-resource helper","entity_vm_runtime_owner_resource_create; entity_vm_runtime_owner_resource_destroy","Embedded file-backed helper class and 0x0d-stride slot-table population semantics still need callee-side recovery","plan-mid.md; docs/raw-0008-000c.md"
"136","code","0xD7600","0x5BD","Foothold","Active dispatch-entry lifecycle helpers","active_dispatch_entry_mark_enabled; active_dispatch_entry_mark_disabled; active_dispatch_entry_create_default","Broader meaning of the active dispatch entry and its relationship to the startup/display lane still needs caller-side confirmation","crusader_decompilation_notes.md; plan-mid.md"
"137","code","0xD7E00","0xFBB","Partial","Palette and dispatch-entry emission helper family","entity_dispatch_entry_init_runtime_state; entity_dispatch_entry_release_runtime_state; vga_palette_set_all_black; vga_palette_set_all_white; vga_palette_set_all_rgb; dispatch_entry_create_black_palette_state_active; dispatch_entry_create_grayscale_palette_state_active; dispatch_entry_create_solid_palette_state_active","Higher-level event/script meaning is still unresolved, especially the paired 0x68bf object and the exact role of the 0004:5ad4-5b6e caller sequence","crusader_decompilation_notes.md; plan-mid.md"
"138","code","0xD9200","0x32E4","Foothold","Entity cleanup/finalize with callback and dispatch-entry palette emission","entity_cleanup_resources_and_dispatch; sprite_redraw_global_if_active","Concrete callback-object subsystem naming is still unresolved; FUN_000d_938c is now verified as a caller-side dispatch-entry/palette emission helper but remains intentionally unnamed","crusader_decompilation_notes.md; plan-mid.md"

1 Segment Type FileOffset Length CoverageStatus KnownSubsystem KeyNamedFunctions Blockers NotesSource
89 88 code 0xA2E00 0x523 None crusader_ne_segments.csv
90 89 code 0xA3400 0x373 None crusader_ne_segments.csv
91 90 code 0xA3800 0x9C6 None crusader_ne_segments.csv
92 91 code 0xA4400 0x6FA Partial Init/context RNG and runtime callback/video-state lifecycle RNG, fatal-report helpers, and runtime callback/video-state lifecycle seg091_func_00fd; seg091_func_014d; rng_set_seed; rng_next_modulo; runtime_callback_object_init_once; runtime_callback_object_teardown_once; video_bios_state_snapshot; video_mode_set_and_record_state fatal_error_report_fmt_a_and_exit; fatal_error_report_buffered_fmt_and_exit; fatal_error_report_fmt_c_and_exit; rng_set_seed; rng_next_modulo; runtime_callback_object_init_once; runtime_callback_object_teardown_once; video_bios_state_snapshot; video_mode_set_and_record_state 00fd/014d still positional; callback object subsystem identity still unresolved Exact fatal-report template text and callback object subsystem identity still need tighter recovery crusader_decompilation_notes.md; plan-mid.md
93 92 code 0xA4E00 0x59E None crusader_ne_segments.csv
94 93 code 0xA5600 0x4F1 None crusader_ne_segments.csv
95 94 code 0xA5E00 0x606 Partial Tracked handle table control tracked_entity_handle_table_init; tracked_entity_handle_table_shutdown; tracked_entity_handle_table_clear_and_dispatch Downstream dispatch tail still unresolved crusader_decompilation_notes.md
132 131 code 0xCF000 0x44D None crusader_ne_segments.csv
133 132 code 0xCF600 0x3EB8 None crusader_ne_segments.csv
134 133 code 0xD3800 0x215A None crusader_ne_segments.csv
135 134 code 0xD6000 0xEF0 None Foothold VM runtime bootstrap and post-init seeding entity_vm_runtime_init_from_path_if_configured; entity_vm_referent_registry_init; entity_vm_runtime_release_slots; entity_vm_runtime_init_slots Configured path/global at 0x65a and the exact external file format behind the 0x6611 runtime owner table still need tighter classification crusader_ne_segments.csv plan-mid.md; docs/raw-0008-000c.md
136 135 code 0xD7000 0x3B7 None Foothold VM runtime owner-resource helper entity_vm_runtime_owner_resource_create; entity_vm_runtime_owner_resource_destroy Embedded file-backed helper class and 0x0d-stride slot-table population semantics still need callee-side recovery crusader_ne_segments.csv plan-mid.md; docs/raw-0008-000c.md
137 136 code 0xD7600 0x5BD Foothold Active dispatch-entry lifecycle helpers active_dispatch_entry_mark_enabled; active_dispatch_entry_mark_disabled; active_dispatch_entry_create_default Broader meaning of the active dispatch entry and its relationship to the startup/display lane still needs caller-side confirmation crusader_decompilation_notes.md; plan-mid.md
138 137 code 0xD7E00 0xFBB Partial Palette and dispatch-entry emission helper family entity_dispatch_entry_init_runtime_state; entity_dispatch_entry_release_runtime_state; vga_palette_set_all_black; vga_palette_set_all_white; vga_palette_set_all_rgb; dispatch_entry_create_black_palette_state_active; dispatch_entry_create_grayscale_palette_state_active; dispatch_entry_create_solid_palette_state_active Higher-level event/script meaning is still unresolved, especially the paired 0x68bf object and the exact role of the 0004:5ad4-5b6e caller sequence crusader_decompilation_notes.md; plan-mid.md
139 138 code 0xD9200 0x32E4 Foothold Entity cleanup/finalize with callback and dispatch-entry palette emission entity_cleanup_resources_and_dispatch; sprite_redraw_global_if_active Concrete callback-object subsystem naming is still unresolved; FUN_000d_938c is now verified as a caller-side dispatch-entry/palette emission helper but remains intentionally unnamed crusader_decompilation_notes.md; plan-mid.md