Crusader_Decomp/docs/retail-debugger-entry-options.md

Retail Usecode Debugger Entry Options

This note consolidates the current best entry-path analysis for the hidden retail usecode debugger in live CRUSADER.EXE.

Question:

• What is the lowest-modification path that could realistically get the hidden debugger menu working?
• Can ordinary usecode or a -u startup override reach it without another fragile executable patch?
• If retail still cannot do it cleanly, what should the next comparison pass in No Regret and JP No Remorse look for?

Short Answer

Current best answer:

• No zero-modification retail entry path is currently evidenced.
• -debug, -laurie, jassica16, ~, and Ctrl+Q still do not provide a proven bootstrap into the hidden debugger.
• The hidden debugger UI is real and usable, but it expects a live seg1408 break-state object at 1478:659c/659e and valid current-unit/runtime context.
• The cleanest non-EXE exploration path is now the -u usecode-root override, but current evidence still does not show a script-visible way to construct the break-state object or write 1478:659c/659e.
• The smallest structurally defensible executable patch is still the current interpreter-callsite-retarget family, but that remains more complex than a one-site tweak and therefore is not the preferred next move unless cross-build comparison fails.
• The best next investigation is a comparison pass in REGRET.EXE and JP /ja/CRUSADER.EXE looking specifically for a surviving writer/bootstrap path for 1478:659c/659e, a constructor caller for 1408:0000, or a direct caller to the seg109 wrappers.

New Live-Ghidra Findings From This Pass

1. The missing retail bootstrap is still missing

Fresh live data-use recovery on 1478:659c still shows reads only.

Current confirmed reader families:

• Interpreter_NextUsecodeOp at multiple sites including 1418:049e, 1418:04b1, 1418:0519, and several later helper windows
• usecode_debugger_open_for_current_unit at 13a0:00af / 13a0:0165
• usecode_debugger_format_expression_to_shared_buffer at 13a0:03db / 13a0:03f4
• usecode_debugger_handle_event at 13a0:1e13, 13a0:1e3b, 13a0:1e5d, 13a0:20b2, 13a0:20b6
• one additional seg109 local helper FUN_13a0_1791

What is still missing:

• no recovered retail writer to 1478:659c/659e
• no recovered retail caller of 1408:0000 Create
• no recovered direct caller of 13a0:0086 usecode_debugger_open_for_current_unit
• no recovered direct caller of 13a0:020d usecode_debugger_open_modal

That keeps the current retail model unchanged:

• the seg109 UI is real
• the seg1408 break-state object is real
• the interpreter callback lane is real
• but retail still looks like an orphaned debugger subsystem whose bootstrap/entry wiring was removed or compiled out

2. The UI wrappers are valid, but they are not safe cold-entry targets

Fresh decompile reads tighten the wrapper roles:

13a0:0086 usecode_debugger_open_for_current_unit

• immediately calls usecode_debugger_gump_create(..., mode=1)
• pulls the current unit name from Remorse::UsecodeDebuggerBreakState::CurrentEntryGetUnitName(_DAT_1478_659c)
• resolves a usecode path under s_usecode
• loads the corresponding unit file into the debugger pane
• centers on current_line - 1
• then enters Dispatch_ModalGump

Implication:

• this wrapper is closest to the original intended debugger experience
• but it absolutely expects a valid debugger object and current-entry state first

13a0:020d usecode_debugger_open_modal

• also calls usecode_debugger_gump_create, but with generic mode 0
• skips current-unit preload and line-centering
• enters the same modal debugger gump

Implication:

• this is the safer force-open target than 13a0:0086
• but it still assumes the surrounding caller/context is sane enough for the debugger gump to live

3. usecode_debugger_gump_create proves the debugger control bundle is complete once the gump exists

Fresh decompile of 13a0:19b1 usecode_debugger_gump_create now gives the cleanest current constructor summary.

Verified behavior:

• allocates a 0x50-byte root gump object when this == null
• builds the debugger menubar and child panes
• initializes the shared watch table
• resolves the base usecode path with Filespec_GetFullPath(0, s_usecode, 0, 0)
• registers the debugger/control event bundle through NewGump_1360_0f2a

Recovered registered event set from this pass:

• 0x13d
• 0x443
• 0x142
• 0x141
• 0x143
• 0x23f
• 0x43e
• 0x41f
• 0x417
• 0x431
• 0x411
• 0x410
• 0x441
• 0x421
• 0x22d

Current direct callers are still only:

• 13a0:009b from usecode_debugger_open_for_current_unit
• 13a0:0256 from usecode_debugger_open_modal

This strengthens one important boundary:

• 0x410 is a real debugger-gump event once the debugger UI has already been created
• it is not evidence that retail gameplay already has a reachable path that creates the gump

4. 0x410 remains parallel debugger UI state, not the debugger bootstrap itself

usecode_debugger_handle_event at 13a0:1df3 still confirms the same split, but the current decompile makes it easier to summarize.

Verified cases include debugger-style commands for:

• open file
• resume / break-next / single-step state changes
• go to line
• watch / inspect / clear watches
• change global memory
• find / search again
• local breakpoint/debug actions

Relevant 0x410 detail:

• incoming event 0x410 is rewritten to local state 0x0e
• case 0x0e clears one local selection/watch slot and refreshes debugger state

Implication:

• the debugger's own event machine knows what to do with 0x410
• but only after the debugger gump already exists and is registered
• this does not give us a new no-patch retail entry path by itself

5. Retail still preserves a substantial debugger UI and command surface once the gump exists

The latest live CRUSADER.EXE decompile pass makes the surviving retail debugger capability map much clearer.

What retail can still do once a valid debugger object and gump already exist:

• usecode_debugger_build_menubar still builds the full hidden debugger menu bar with File, Run, Breakpoints, Search, and Data menus.
• usecode_debugger_translate_registered_event still translates the registered debugger/control event bundle into the local debugger command ids consumed by usecode_debugger_handle_event.
• usecode_debugger_handle_event still implements real debugger actions rather than decorative UI stubs: open file, run, break-next, single-step, go to line, watch, inspect, change global, search, search again, break to TDP, and watch clearing.
• usecode_debugger_source_pane_draw_visible_lines still clamps the source viewport, highlights the current line, scans the breakpoint table for visible marks, and draws the loaded source rows from the .unk buffer.
• usecode_debugger_source_pane_handle_pointer_event still converts pointer position into source line and column state and also drives scroll-style commands when the pointer is above or below the pane.
• the child-pane split is now clearer in retail than in the earlier first-pass mirror list: one pane is the loaded source view, while the sibling 13a0:16ee/1791/193f lane is a separate watch-pane create/draw/click surface.

The live retail file-loading path is now also much clearer than before.

• usecode_debugger_source_pane_load_file resets local source-pane cursor state, destroys any previous source buffer, allocates a fresh source-buffer object from the requested path, updates the pane's line-count field, and refreshes the child widgets.
• usecode_debugger_source_buffer_create_from_path and usecode_debugger_source_buffer_open_from_path still build a dedicated far-memory file object, normalize the requested path, open the file, and pass it into the text-loader path.
• usecode_debugger_source_buffer_load_text still reads the whole file into far memory, rejects obviously non-text inputs, and hands the buffer to usecode_debugger_source_buffer_split_lines_in_place.
• usecode_debugger_source_buffer_split_lines_in_place still walks the loaded text, zero-terminates newline boundaries in place, and populates the per-line pointer table later consumed by draw, click, search, and goto-line logic.
• usecode_debugger_source_buffer_get_line_ptr is still the shared accessor used by source draw, pointer handling, find/find-next, and source-pane command handling.

Retail source navigation helpers are now closed well enough to describe the pane behavior directly.

• usecode_debugger_set_line_selection clamps the requested line against the loaded file range, clears transient cursor state, optionally updates the anchor line, and forces a redraw.
• usecode_debugger_center_on_line stores the target current line, computes a top-of-window line from the visible row count, and then delegates to usecode_debugger_set_line_selection.
• this means retail still preserves the ordinary source-browser workflow expected from the strings: load file, jump to line, center on current line, search through lines, and redraw the viewport around the active selection.

The watch-pane side is also more concrete now.

• usecode_debugger_watch_pane_create still allocates a real watch child gump and installs the watch-pane vtable.
• usecode_debugger_watch_pane_draw still iterates the shared 10-slot watch table at 1478:5580, asks the break-state callback table to format each populated watch entry, and highlights the selected row.
• usecode_debugger_watch_pane_handle_click still converts pointer Y position into a watch-row index, updates the selected watch slot, and triggers a repaint.
• that is stronger evidence for interactive watch list still survives than the earlier weaker watch-related strings still exist wording.

Current safest interpretation:

• retail did not merely keep a few string tables or unused menu labels
• retail still keeps a functioning debugger front-end shell with real search, breakpoint, watch, inspect, and source-view logic
• the main missing piece is still how execution ever reaches that shell with valid live state

6. Retail callback and reachability limits are still the decisive difference from Regret

The same live pass also tightened the what retail still cannot do side.

Current direct-caller state in live CRUSADER.EXE:

• usecode_debugger_open_for_current_unit still has no recovered callers
• usecode_debugger_open_modal still has no recovered callers
• Remorse::UsecodeDebuggerBreakState::Create at 1408:0000 still has no recovered callers
• usecode_debugger_handle_event is still only reached through usecode_debugger_translate_registered_event and usecode_debugger_forward_child_event

Current callback state is still the key retail blocker too:

• Remorse::UsecodeDebuggerBreakState::OnBreakTriggeredNoop at 1408:046f is still the live slot-0 callback
• Remorse::UsecodeDebuggerBreakState::VtableSlot1ReturnZero at 1408:0474 is still the live slot-1 callback
• unlike Regret, retail still has no recovered bootstrap that rewires the break-state object onto a live frontend-aware vtable

So the retail-versus-Regret split is now even sharper:

• both builds preserve a large debugger UI/event subsystem
• retail still lacks the recovered object bootstrap and live callback target that would naturally open the debugger on break
• Regret keeps both the writer/bootstrap path and the vtable upgrade that turns break-state callback slot 0 into a real open_for_current_unit launch path

That is why retail still reads as functional debugger shell plus dormant break-state object, while Regret reads as same shell plus a surviving end-to-end open-on-break path.

One practical refinement from the latest retail pass is that the shell is not merely a static menu/window skeleton.

• the file-open path still reaches a real far-memory source-buffer loader
• the search path still walks live source lines through usecode_debugger_source_buffer_get_line_ptr
• the goto-line path still updates line selection through the same source-pane helpers used by current-line centering
• the watch path still stores, formats, selects, clears, and redraws real watch rows

So the remaining barrier is still entry/bootstrap, not lack of interior debugger behavior after entry.

What This Means For Usecode As An Entry Path

Current Best Read

The -u retail override is now the best non-EXE exploration tool, but not yet a proven debugger-entry solution.

Why it still matters:

• startup_apply_u_override_if_present at 1420:0cdf is a real startup hook
• it is called from Init_Everything at 1048:05d3
• it swaps the single live usecode runtime root rather than layering a second source
• that replacement root is then consumed by ordinary compiled paths like Usecode_ItemCallEvent, UsecodeProcess_CreateProcess, and Interpreter_NextUsecodeOp

So -u gives a practical route to:

• replace scripted behavior with minimal executable modification
• test whether a data-driven/usecode-side path can indirectly reach an otherwise hidden compiled control lane

But the current negative evidence is still stronger than the hopeful side:

• no recovered usecode intrinsic or compiled helper currently reads like open usecode debugger
• no recovered usecode-visible primitive currently reads like construct debugger break state
• no recovered usecode-visible primitive currently writes 1478:659c/659e
• current script/event scans still do not show a plain usecode literal/ordinal trail for event 0x410

Current safest conclusion:

• a -u archive replacement is the least invasive experimental platform
• it is not yet an evidence-backed direct debugger unlock

Best Script-Side Host Families If We Try -u

If the next step is an asset-only experiment, the best current targets remain:

• MONITNS / monitor-computer families
• SURCAMNS / SURCAMEW
• NPCTRIG

Why these are stronger than a generic chest or one-off gadget:

• they already sit near real modal UI / camera / event-control behavior
• they are more plausible bridges into a hidden control/event lane than ordinary loot or animation scripts

What they still do not currently prove:

• direct debugger construction
• direct seg109 wrapper calls
• direct 1478:659c/659e bootstrap

So the immediate asset-only goal should be framed narrowly:

• not open the debugger from usecode directly
• but test whether any scripted family can reach a compiled control path closer to the hidden debugger than the currently known public gumps

Ranked Entry Options By Modification Cost

1. Zero-modification retail route

Current status: no proven path.

Still ruled out by current evidence:

• -debug
• -laurie
• jassica16
• ~
• Ctrl+Q / event 0x410

Why:

• they toggle debug/cheat/display behavior
• they do not currently create the seg1408 break-state object or enter the seg109 wrappers

2. Asset-only route via -u replacement EUSECODE.FLX

Current status: lowest-modification practical experiment, but unproven as a debugger route.

Advantages:

• no retail EXE byte changes required
• fully reversible by swapping the override directory/archive
• reaches normal compiled usecode consumers

Limitations:

• still no direct evidence that usecode can create/write the required debugger state
• more likely to find an indirect bridge than a direct open debugger primitive

Current recommendation:

• prefer this over new ad hoc retail EXE patching if the goal is only to test indirect control-flow ideas

3. Minimal executable route: interpreter-callsite-retarget family

Current status: still the smallest structurally defensible retail patch family.

Why it remains the floor:

• one-site retarget ideas fail because they do not also create/store the debugger object
• direct shared-callback patching is too global and has already caused startup failures
• direct cold-calls into the UI wrappers use the wrong stack/context

What the current viable family still needs:

• lazy create-or-reuse of the seg1408 break-state object
• store into 1478:659c/659e
• preserve deferred interpreter timing
• sanitize wrapper arguments before the seg109 UI entry

So even the best retail EXE path is still not a tiny one-byte/two-byte unlock.

4. Cross-build bootstrap recovery

Current status: best next investigation.

Why this is now preferred over more retail patch fishing:

• if No Regret or JP No Remorse kept any surviving debugger bootstrap, it could collapse the retail problem from invent a new path to port or mimic one missing write/call
• that is more likely to produce a truly minimal modification than another speculative retail patch chain

Retail Ghidra Naming Backlog

The current note corpus now supports a tighter retail seg109 naming batch than the live authoring summary currently reflects.

These are the most important retail debugger-side helpers to promote explicitly in the active CRUSADER.EXE database before any new patch design work:

• 13a0:2882 = usecode_debugger_build_menubar
• 13a0:088f = usecode_debugger_source_pane_create
• 13a0:0ae8 = usecode_debugger_source_pane_init_view_from_break_state
• 13a0:0ba7 = usecode_debugger_source_pane_handle_command
• 13a0:0f16 = usecode_debugger_source_pane_handle_pointer_event
• 13a0:1088 = usecode_debugger_source_line_copy_for_display
• 13a0:1118 = usecode_debugger_source_pane_draw_visible_lines
• 13a0:1413 = usecode_debugger_source_pane_clamp_viewport
• 13a0:15ac = usecode_debugger_source_pane_load_file
• 13a0:16ee = usecode_debugger_watch_pane_create
• 13a0:1791 = usecode_debugger_watch_pane_draw
• 13a0:193f = usecode_debugger_watch_pane_handle_click
• 13a0:1c2c = usecode_debugger_translate_registered_event
• 13a0:1dc6 = usecode_debugger_forward_child_event
• 13a0:2c2e = usecode_debugger_source_buffer_create_from_path
• 13a0:2ca0 = usecode_debugger_source_buffer_destroy
• 13a0:2d14 = usecode_debugger_source_buffer_open_from_path
• 13a0:2e0a = usecode_debugger_source_buffer_load_text
• 13a0:2f4f = usecode_debugger_source_buffer_split_lines_in_place
• 13a0:301d = usecode_debugger_source_buffer_get_line_ptr

Why this batch matters before more patching:

• it converts the remaining patch-target area from anonymous FUN_13a0_xxxx bodies into named UI, event, and source-buffer lanes
• it reduces the chance of patching the wrong helper when the debugger gump is already on-screen but still miswired
• it makes runtime-only experiments easier to reason about because the gump lifecycle, source loading, and event forwarding chain become legible in-session

The current strongest provenance for this retail batch is the combined retail 000b:* -> 13a0:* table in ne-segment1.md plus the one-to-one structural match against the now-closed Regret 1398:* family.

One live correction from the follow-up rename pass matters here: retail 13a0:16ee/1791/193f reads as a watch-pane constructor/draw/click trio, while the source-pane lane remains centered on 13a0:088f/0ae8/0ba7/0f16/1088/1118/1413/15ac. So the Regret-side structural match is still valuable, but the retail child-pane split is now sharper than the earlier first-pass list implied.

Practical Alternatives To Manual Hex Patching

The current blocker is no longer we do not know what to patch. It is the delivery path needs to stop depending on blind byte edits.

1. Runtime-only proof via DOSBox-X debugger or equivalent live memory tooling

This is now the cleanest first confirmation path.

Use it to:

• keep the retail executable on disk unchanged
• patch or seed the debugger object only in live memory
• prove whether a create/store/open sequence is sufficient before committing to any permanent binary patch

What this should target first:

• seeding 1478:659c/659e with a valid debugger-state object
• reusing the existing interpreter callback lane at 1418:049e..04b5
• testing whether 13a0:020d or the vtable callback path can open a stable debugger gump once state exists

This is especially attractive because it turns the current question from did we edit the NE file correctly? into does the runtime model itself actually work?

2. Scripted patch application to a writable clone, not manual hex editing

If a permanent retail patch is still wanted, the next step should be a reproducible patcher, not another manual byte-edit round.

That means:

• keep a dedicated writable clone of the executable
• store each patch as address + expected old bytes + new bytes + reason
• apply it through a scriptable patcher that validates the original bytes before writing
• regenerate the same patch on demand instead of hand-transcribing offsets each time

This can be done with PowerShell or Python against raw file offsets even if Ghidra export remains unreliable.

3. Use Ghidra only for analysis and verified byte plans

The current evidence does not support treating Ghidra export as the final patch-delivery mechanism for this lane.

What still works well:

• identify the correct callsite and byte budget in Ghidra
• annotate the patch rationale in-session
• test the control-flow hypothesis on a writable target
• then convert the verified result into an external patch manifest or launcher-side patcher

That keeps Ghidra in the role it is good at here: reverse-engineering and patch design, not blind final-binary distribution.

4. Keep -u as the low-risk data-side experiment surface

The -u override still does not solve the missing bootstrap, but it remains valuable for adjacent experiments that do not require byte writes.

Use it for:

• testing whether scripted monitor/camera/control families can get closer to debugger-adjacent compiled paths
• validating source-file and unit-name assumptions without touching the executable
• separating data-side idea failed from patching workflow failed

It should stay in the toolbox, but it should not be mistaken for a direct replacement for the missing retail bootstrap.

Current Recommendation

If the goal is the minimum modification that still has a realistic chance to work, the order should now be:

1. Promote the retail seg109 naming backlog above so the remaining debugger lanes are explicit in Ghidra.
2. Use runtime-only memory seeding on a clean executable to prove or kill the bootstrap theory without committing file changes.
3. Compare REGRET.EXE and JP /ja/CRUSADER.EXE for any surviving debugger bootstrap/writer that can replace a custom retail bootstrap.
4. Keep -u / replacement EUSECODE.FLX as the preferred low-risk experiment surface for any script-side proxy ideas.
5. Do not resume broader retail executable patching unless the runtime proof or cross-build pass yields one clear small patch plan that can be applied by script to a writable clone.

That ranking fits both the new live evidence and the user's practical constraint that complex retail patch attempts have already been unstable.

Cross-Build Exploration Note

When this moves to No Regret and JP No Remorse, the focused targets should be:

1. any write to the debugger global pointer equivalent of 1478:659c/659e
2. any caller of 1408:0000 Create or its build-specific equivalent
3. any direct caller of usecode_debugger_open_for_current_unit
4. any direct caller of usecode_debugger_open_modal
5. any non-stub debugger vtable slot replacing retail 1408:046f / 1408:0474
6. any command-line or cheat/debug hotkey path that lands near the seg109 wrappers or seg1408 constructor
7. any usecode/runtime path that seeds current-unit state for the debugger without using the orphaned retail bootstrap

Bottom Line

Retail No Remorse still looks like it shipped with a real hidden usecode debugger whose UI, event dispatcher, and break-state object all survived, but whose bootstrap path did not.

That means the lowest-modification currently evidenced route is no longer "guess one more retail patch". It is:

• first, look for the missing bootstrap in sibling builds,
• second, use -u and a replacement EUSECODE.FLX only as a low-risk exploration surface,
• and only third, return to the interpreter-callsite-retarget patch family if the cross-build pass gives no smaller bootstrap to port.