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

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

Current Recommendation

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

1. Compare REGRET.EXE and JP /ja/CRUSADER.EXE for any surviving debugger bootstrap/writer.
2. Keep -u / replacement EUSECODE.FLX as the preferred low-risk experiment surface for any script-side proxy ideas.
3. Do not resume broader retail executable patching unless the cross-build pass fails to yield a clearer bootstrap or the existing O/P family gets one clean runtime confirmation target.

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.