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.