Crusader_Decomp/docs/retail-debug-arg.md

# Retail `-debug` Argument in `CRUSADER.EXE`

This note records the current evidence-backed read of the retail `-debug` command-line switch in the live NE `CRUSADER.EXE` database.

Short version:
- retail `CRUSADER.EXE` does recognize `-debug`
- the switch is not fully disabled in the parser
- it sets a global debug-print threshold and two debug-related globals
- one surviving `-debug` feature is now concretely identified as an AVI/video-player timing overlay
- current evidence does **not** show it constructing or wiring the hidden seg109/seg1408 usecode debugger state object at `1478:659c/659e`
- current best read is `debug-print threshold plus movie-playback timing overlay`, not `the lost hidden debugger bootstrap`

## Verified Parser Evidence

In the live NE image, `HandleCommandlineArgs` at `1048:09b9` contains a real branch for `"-debug"` at `1048:0a93`.

The branch body does all of the following:
- writes `0x000a` to `1478:87e0` (`g_debugMsgLevel`)
- calls `ConsolePrintf(0x32, 1478:0ad6)`
- writes `1` to `1478:0845` (`g_someDebugFlag`)
- writes `1` to `1478:0859` (`g_someDebugFlag2`)

So the parameter has exactly three direct state effects currently recovered:
- it changes the global print threshold
- it sets one still-unresolved debug latch at `1478:0845`
- it enables the seg1468 video timing overlay through `1478:0859`

The printed string at `1478:0ad6` is:

`Debugging mode ON.`

That is strong evidence against the narrow claim that retail only still recognizes the string but has the feature body disabled. The retail parser still executes real side effects when `-debug` is present.

Nearby startup strings in the same table also confirm this is the normal command-line switch cluster:
- `CRUSADER:  No Remorse`
- `Cheats are active.`
- `You DO need help!`
- `Debugging mode ON.`
- `Enabling ENHANCED mode. (NOT!)`

## What Still Reacts To `-debug`

### 1. Debug message threshold is live

`1478:87e0` is already symbolized as `g_debugMsgLevel` in the live export.

Data-use recovery shows it is read by:
- `ConsolePrintf`
- `DebugPrintAndWaitForInput`
- two adjacent positioned debug-print helpers in the same family (`12d0:0391`, `12d0:0442`)

Current best read:
- `-debug` sets the runtime print threshold to `10`
- the compare in the wrappers is effectively `if (call_level < g_debugMsgLevel) skip`
- so `-debug` does **not** create a new console sink by itself; it only changes which existing callsites are eligible to print
- the shared print staging buffer at `1478:45a6` is allocated independently by `12d0:0513`, not by the `-debug` parser branch

The low-level sink path is now tighter too:
- `ProbablyPrintDebugMessage` at `1000:65cc` formats through the generic `ProbablySomethingDebuggy` / `FUN_1000_67ac` stream pipeline
- that helper passes DS:`1478:6c46` as the target stream object
- the surrounding DS data at `1478:6c32..1478:6c81` is a four-entry static stdio-style table with handle words `0`, `1`, `2`, and `3`
- the `1478:6c46` entry is therefore the handle-`1` stream, i.e. the program's `stdout` slot

Practical implication:
- the text side of `-debug` is not a hidden second debugger UI and not a newly-created in-memory log sink
- it is ordinary formatted DOS standard-output text gated by `g_debugMsgLevel`
- the main reason it is easy to miss is that Crusader spends most of its runtime in graphics mode, while many eligible callsites are startup, shutdown, or failure diagnostics

This matters because it narrows the real effect of the print side:
- `-debug` definitely changes print gating
- but it does not add a new visible on-screen text channel by itself
- any visible text side effect depends on already-existing print callsites and on how DOS `stdout` is surfaced in the running environment

### 1a. What subsystems use that print gate

Recovered `ConsolePrintf` callers show that the thresholded text/debug lane is not limited to video. Current caller families include:
- command-line handling and startup/shutdown (`HandleCommandlineArgs`, `CheckForLaurieArg`, `Init_Everything`, `Uninitialize`)
- config parsing (`LoadConfigFile`)
- cache/shape rebuild work (`CacheShapeHand_1070_15a9`)
- item/glob spawning failure paths (`ItemGlob_GlobEggHatch`)
- drawlist or display initialization (`DList_Init`)
- audio init (`Init_ASS`)
- joystick init/calibration (`Joystick_Init`, `Joystick_Calibrate`, nearby helper `1400:0c7e`)
- teleporter and several `UProcess_*` / `1428:*` runtime helpers

The rarer blocking helper `DebugPrintAndWaitForInput` is much narrower. Current recovered callers are:
- `Dispatch_Init_320_0281`
- `Dispatch_1320_103e`
- `NewGump_Alloc`

Those are all failure/debug-stop style paths rather than normal AVI playback logic.

Practical interpretation:
- there **is** a non-video `-debug` lane
- but the recovered non-video lane is primarily `thresholded debug/error text`, often in startup or failure handling
- it is not currently a second confirmed visible feature on the level of the movie timing dots you observed

### 1c. Recovered printed strings and format strings

The print inventory is now tighter than the earlier subsystem-only caller list.

Recovered call levels so far:
- `0x32`
- `0xff`

Because retail `-debug` sets `g_debugMsgLevel = 10`, both recovered levels are above threshold and therefore eligible to print when their code paths execute.

#### Command-line and startup argument strings

Recovered directly from `HandleCommandlineArgs` / `CheckForLaurieArg`:
- `Cheats are active.`
- `You DO need help!`
- `Debugging mode ON.`
- `Enabling ENHANCED mode. (NOT!)`
- `Warping to mission %d.`
- `Warping to mission %d @ x:%d y:%d z:%d.`
- `Defaulting to skill level %d`
- `Map offset = %d`
- `Destination Egg = %d`
- `Demo mode.`

These are the cleanest first things to look for in DOSBox logging because they belong to deterministic early startup/argument paths.

#### Init / config / install-status strings

Recovered from `Init_Everything` and `LoadConfigFile`:
- `Using map patch file.`
- `Loading: [`
- `           ]`
- `.`
- `Running with partial installation.`
- `Running with full installation.`
- `Redirecting mission %d tune to '%s'`

Interpretation:
- some of these are not human-readable status sentences so much as progress-bar fragments and single-character emitters
- that means an `INT 21h` log may show very short writes rather than one tidy line of text

#### Cache / rebuild strings

Recovered from `CacheShapeHand_1070_15a9`:
- `Creating Swap file [`
- `                                        ]`
- `]            `
- `\n\r[`
- `       ]\r[`
- a single-byte progress marker at `1478:0e1e`

Interpretation:
- this lane appears to print progress scaffolding rather than rich prose
- if DOSBox logs writes with counts but not payload text, many tiny startup writes may belong to this cache/swap-file progress path

#### Runtime / failure diagnostics

Recovered from narrower runtime and failure paths:
- `dl init ` from `DList_Init`
- `COULD NOT CREATE GLOB ITEM!` from `ItemGlob_GlobEggHatch`

These are useful because they are strong “real debug text” fingerprints if they ever show up in a live log.

#### Audio init marker

Recovered from `Init_ASS`:
- `.`

Current best read:
- this is another minimal progress marker, not a descriptive sentence

#### Blocking `DebugPrintAndWaitForInput` strings

Recovered from the three currently known `DebugPrintAndWaitForInput` callers:
- `No room for Dispatcher Record/Playback.`
- `End of script! (press any key)`
- `Out of Memory! [%u]`

Interpretation:
- these are failure/debug-stop strings
- they are good fingerprints for recognizing the lane, but they should not be expected during healthy normal gameplay

#### Shutdown strings

Recovered from `Uninitialize` and nearby startup/shutdown text:
- `CRUSADER:  No Remorse`
- `No pity.  No mercy.  No remorse.`

Current best read:
- the first is a normal shutdown-side banner
- the second is associated with the Laurie-enabled lane and is not a generic `-debug` print on its own

### 1b. How to read that text in practice

Current best evidence-backed read is:
- the messages go to the executable's normal DOS `stdout` stream, not to a bespoke debugger console
- if `stdout` is left attached to `CON`, text may only be practically visible when Crusader is still in a text-ish startup/shutdown context or when a failure path forces a text-mode-style report
- replacing `stdout` with a disk file via shell redirection is now a poor default recommendation, because live user testing showed `CRUSADER.EXE -debug > DEBUG.TXT` surviving startup but crashing after the intro cutscene

What this does and does not mean:
- plain file redirection probably changes the handle-1 stream semantics enough to destabilize later stdio/device logic in this executable or runtime
- it will not magically produce extra chatter unless existing callsites actually execute at or above the threshold
- it does not by itself surface the hidden seg109/seg1408 debugger UI, because that is a separate control path

Remaining caution:
- this is a strong static conclusion about the sink identity
- runtime capture details still depend on the exact DOSBox / shell setup, because the game often runs after switching away from a normal text-console presentation
- safest current guidance is to keep handle `1` attached to a character-device-style sink and capture around it, rather than redirecting directly to a regular file

### 2. `g_someDebugFlag2` is live

`1478:0859` (`g_someDebugFlag2`) is written by the `-debug` parser branch and read later in segment `1468`.

Recovered readers:
- `VideoPlayer_AdvanceFrameAndHandleSkip` (`1468:2869`)
- `VideoPlayer_StreamChunks` (`1468:2af4`)

Both routines conditionally call `VideoPlayer_DrawDebugTimingOverlay` (`1468:2de9`) when `g_someDebugFlag2 != 0`.

The current live export already places these functions in the `VideoPlayer_*` neighborhood:
- preceding function `1468:283f..2868` is typed as `VideoPlayer_Run(struct Process * p_proc)`
- `AVI_1468_2188` is an AVI-header parser that recognizes `AVI ` / `LIST` / `strl` / `strh` / `strf`
- `FUN_1468_3904` is a later `movi`-chunk setup/prime path that calls `VideoPlayer_StreamChunks(..., 1)`

Current best read of this lane:
- this is part of a video / presentation / media-processing subsystem
- `-debug` leaves behind an extra instrumentation path in that subsystem
- the behavior does not currently look like debugger-object creation, breakpoint management, or usecode UI entry

`VideoPlayer_DrawDebugTimingOverlay` is now specific enough to describe concretely:
- it clears a temporary `0x1f4`-byte buffer (`500` bytes)
- it computes marker positions from AVI timing fields using a divisor of `6000`
- it writes marker bytes `8` and `9` into that temporary line buffer
- it copies the resulting `500`-byte line into a video buffer near offset `0x1de * 0x280 + 0x78`
- it builds and copies a second `500`-byte line into the next scanline at `+0x280`

Because the helper writes into two adjacent scanlines of a `0x280`-wide (`640`-pixel) buffer near the bottom of the frame, current best read is:
- this is a built-in movie-playback timing overlay or marker strip
- it is probably intended to visualize AVI/video timing state while playback is running
- it is a practical runtime feature that may be observable during intro/cutscene playback when launched with `-debug`
- it is still unrelated to the seg109/seg1408 usecode debugger object model

Runtime confirmation now matches the static read:
- the observed moving dots at the bottom of played videos are consistent with this helper's two-line marker overlay
- that closes the strongest user-visible effect of retail `-debug`

### 3. `g_someDebugFlag` is only weakly understood

`1478:0845` is symbolized as `g_someDebugFlag` and is also written by the `-debug` branch.

Current evidence is weaker here:
- the parser write is confirmed
- no equally clear downstream reader has been recovered yet

Current safest read:
- this is a real surviving `-debug` state cell
- it may be vestigial, sparsely used, or hiding inside still-unrecovered data/indirect uses
- it should not currently be overinterpreted as a debugger bootstrap flag

At this point the absence evidence is fairly strong:
- direct data-use recovery still finds only the parser write
- nearby bytes `1478:0844` and `1478:0846` do have real readers/writers, so this is not just a search blind spot across the whole region
- current best read is `orphaned or still-hidden latch`, not `known active second feature`

## Comprehensive Current Effect Summary

Based on the current live NE evidence, retail `-debug` enables or changes the following and no more has yet been proven:

### Confirmed direct effects

1. It prints `Debugging mode ON.` during command-line handling.
2. It sets `g_debugMsgLevel` at `1478:87e0` to `10`.
3. It sets `g_someDebugFlag` at `1478:0845` to `1`.
4. It sets `g_someDebugFlag2` at `1478:0859` to `1`.

### Confirmed runtime-visible effect

1. It enables the seg1468 AVI/video-player timing overlay, which draws moving marker dots or traces near the bottom of played videos.

### Confirmed non-video effect class

1. It changes eligibility for existing debug/error print wrappers used across startup, config, cache, joystick, audio, item/glob, dispatch, and some runtime process code.
2. A smaller subset of those callsites are blocking `print-and-wait` diagnostics used on failure/debug-stop paths in dispatch/gump allocation code.
3. The recovered text sink for those wrappers is the program's handle-`1` stdio stream at `1478:6c46`, so the lane is standard-output text rather than a separate debugger-only channel.
4. The recovered printable inventory is currently dominated by startup/status/progress strings plus a smaller number of failure-only diagnostics; it is not a rich always-on gameplay console.

### Things not currently proven as practical effects

1. A new visible text console or new text window.
2. Any hidden usecode debugger bootstrap.
3. Any connection to the seg109/seg1408 debugger-state pointer at `1478:659c/659e`.
4. Any second confirmed user-visible feature beyond the AVI timing dots.
5. Any active downstream behavior for `1478:0845`.

## What `-debug` Does **Not** Currently Prove

The hidden retail debugger / unit-inspector work already mapped elsewhere in this repo still centers on:
- seg109 UI wrappers such as `usecode_debugger_open_for_current_unit` and `usecode_debugger_open_modal`
- seg1408 debugger-state helpers such as `usecode_debugger_break_state_create` and `usecode_debugger_maybe_break_on_current_line`
- the global debugger-state far pointer at `1478:659c/659e`

That `1478:659c/659e` pointer is still read by the known interpreter-side debugger path, including the break callback lane around `1418:04aa..04b5` and the seg109 debugger-opening wrappers.

What has **not** been shown in the current `-debug` pass:
- no recovered write from the `-debug` branch to `1478:659c/659e`
- no evidence that `-debug` calls `usecode_debugger_break_state_create`
- no evidence that `-debug` enters `usecode_debugger_open_for_current_unit`
- no evidence that `-debug` is the same switch as `-laurie`

So the current answer is:
- `-debug` is real
- `-debug` still does something
- but it is currently **not** the same evidence trail as the hidden usecode debugger bootstrap

## Relationship To `-laurie`

The two switches should stay separated.

Current repo evidence still supports:
- `-laurie` / `CheckForLaurieArg(...)` writes the cheat/debugger gate at `1478:0844` (`g_wasLaurieSet` / prior `cheats_enabled` lane)
- `-debug` is handled inside the normal command-line option loop in `HandleCommandlineArgs`
- `-debug` writes `1478:0845`, `1478:0859`, and `1478:87e0`, not `1478:0844`

That means the old hidden debugger/UI work and the `-debug` switch are adjacent only at a broad `debug features existed` level. They are not currently the same recovered control path.

## Best Current Conclusion

The wiki claim is only partly right.

Accurate part:
- there really is a retail `-debug` command-line argument

Inaccurate or currently unsupported parts:
- it is not merely a dead recognized string; the parser branch is still live
- the current evidence does not support `secondary monitor debug kernel` specifically
- the current evidence does not support `-debug` as the missing bootstrap for the hidden seg109/seg1408 usecode debugger

Best current evidence-backed replacement claim:

> Retail `CRUSADER.EXE` still recognizes and executes a live `-debug` branch. That branch prints `Debugging mode ON.`, raises the debug message level, and enables a concrete seg1468 AVI/video-player timing overlay that draws two 500-byte marker traces into adjacent scanlines near the bottom of the playback buffer. However, current evidence does not show it creating the seg1408 debugger-state object at `1478:659c/659e`, so it should not currently be treated as the missing bootstrap for the hidden usecode debugger UI.

## Claim Check: `E69FB` And The "Secondary Monochrome Monitor" Idea

An external claim said the potential debug instructions were at flat file offset `E69FB` and might only be visible on a secondary monochrome monitor.

Current evidence does not support that.

### `E69FB` mapping

Using the local NE segment map:
- NE segment `144` begins at file offset `0xE3C00`
- flat offset `0xE69FB` therefore lands at segment-relative offset `0x2dfb`
- in the live NE image that maps to `1478:2dfb`

The bytes around that location are not executable instructions for a hidden monitor-debug path. They fall inside a data/string cluster:
- `KeyboardProcess`
- `KEYIO.C`
- `PRIORITY.C`
- `SystemTimer`
- `SYSTIMER.C`
- `AccWait`

`1478:2dfb` itself lands inside the `SYSTIMER.C` string, not inside a code body.

Current safest read:
- the cited flat offset is almost certainly a mistaken pointer into a data/descriptor/source-file-name region
- it is not a useful anchor for `-debug` behavior and not evidence for hidden display-specific code by itself

### Secondary monochrome monitor check

The current `-debug` evidence points elsewhere:
- text/debug output goes through the normal `stdout` sink at `1478:6c46`
- the user-visible runtime feature is the seg1468 AVI timing overlay drawn into the main video buffer

Additional negative evidence from the live program:
- no recovered text strings mentioning `mono`, `monochrome`, `hercules`, or `MDA`
- no recovered instruction hits referencing obvious monochrome-adapter I/O ports such as `0x3b4`, `0x3b5`, `0x3b8`, or `0x3ba`
- no recovered instruction hits referencing the `B000` monochrome text-memory window

That does **not** mathematically prove that no historical or stripped monitor-debug code ever existed during development, but it does mean:
- the current retail `-debug` evidence does not support the "secondary monochrome monitor" explanation
- the current retail implementation is better explained as `stdout`-gated text plus the AVI timing overlay

## Ghidra Refinements Applied

The live `CRUSADER.EXE` database now carries this batch's first-pass refinements too:
- `1468:2869` -> `VideoPlayer_AdvanceFrameAndHandleSkip`
- `1468:2af4` -> `VideoPlayer_StreamChunks`
- `1468:2de9` -> `VideoPlayer_DrawDebugTimingOverlay`
- parser and global comments at `1048:0a93`, `1478:0845`, `1478:0859`, and `1478:87e0`
- overlay-gate comments at `1468:2920` and `1468:2dc8`
- debug-print helper comments at `12d0:0391`, `12d0:03ee`, and `12d0:0442`
- sink/init comments at `1000:65cc` and `12d0:0513`
- stdio-table comments at `1478:6c32` and `1478:6c46`

## Follow-Up Targets

If this lane is revisited, the highest-value remaining questions are:
- identify a concrete behavioral name for `1478:0845` by finding a real downstream consumer
- classify the remaining nearby seg1468 helpers so the AVI/video-player object layout around `+0x117/+0x11b/+0x11f/+0x123` can be named cleanly
- test whether the overlay is visibly present during intro/cutscene playback in DOSBox or another live runtime
- find meaningful callsites into the seg12d0 positioned debug-print helpers to learn whether `-debug` exposes additional text diagnostics beyond movie timing markers
- determine the default runtime value path for `g_debugMsgLevel` more rigorously, since static initialized data alone does not yet explain the full practical print behavior
- sample a few representative `ConsolePrintf` / `DebugPrintAndWaitForInput` format strings under live capture so the stdout lane can be characterized with runtime output rather than only static caller families