Captive DOSBox X Startup

Captive DOSBox-X startup

This is the repeatable startup procedure for testing Captive with the original game data. It deliberately uses the real CAPTIVE.BAT 1 chain and the repository's VGA profile. Do not start CAPPO.EXE directly.

Normal daily launch

From the repository root, run:

tools/run_captive_dosbox_x.sh /Users/bosse/.opencaptive/captivedebug/captive

The helper selects /opt/homebrew/bin/dosbox-x on Apple Silicon when it is available. To use another verified DOSBox-X binary, set DOSBOX_X_BIN:

DOSBOX_X_BIN=/path/to/dosbox-x \
  tools/run_captive_dosbox_x.sh /path/to/authentic/captive-data

The data directory must contain the original Captive files, including CAPTIVE.BAT. OpenCaptive must not create replacement maps, planets, landings, droids, or dungeon data when these files are missing.

Verification boundary

This procedure proves the original startup chain, VGA mode, intro handoff, and Mission 0001 route-selection boundary. It does not turn a reference image, a memory dump, or a locally generated route into evidence of arrival, orbit, landing, or dungeon entry.

Use only the original runtime and the player's real files for those states. No replacement planet, landing marker, terrain, dungeon, scrolling status text, or procedural fallback may be substituted. If the original session has not visibly reached destination orbit and produced the original landed view, stop at that boundary and report it as unverified.

The graphical OpenCaptive start menu launches the same authentic DOSBox-X runtime as a separate normal game window and then closes its launcher process. This is intentional: DOSBox-X/CAPPO must own the original VGA timing, audio, mouse, keyboard and game state. The launcher must not keep a second debugger-backed or native gameplay surface alive behind it.

For debugger-backed input verification, use the repository's diagnostic sequence harness. It injects make/break bytes through DOSBox-X's emulated AT keyboard controller and the original CAPPO IRQ1 handler; it does not write a private CAPPO matrix or create a route, planet, landing point, or dungeon.

Exact repeatable startup

Use this order every time:

cd /Users/bosse/Documents/OpenCaptive
tools/run_captive_dosbox_x.sh /Users/bosse/.opencaptive/captivedebug/captive

Then, in the DOSBox-X window:

1. Choose 1 (VGA) at the video-mode prompt.
2. Click inside the game viewport once so DOSBox-X owns keyboard and mouse focus.
3. Let the original intro run until Captive accepts the normal input.
4. Use Ctrl+F10 only to release or recapture the DOSBox-X mouse lock.

Never launch CAPPO.EXE directly. The batch file performs the original startup/unpack chain and selects the real game data. Starting the executable directly is a different, unsupported state and is a common cause of a black, stalled, or incorrect viewport.

Daily reset checklist

Use this short checklist when a previous DOSBox-X session has been left open:

1. Close the old DOSBox-X window. If macOS asks whether to quit a running program, choose No for the window you still want to use; choose Yes only when deliberately closing the stale session.
2. If that warning stays on top, do not send game keys yet. Bring the warning forward, dismiss it, and click the new DOSBox-X viewport once. A warning window left above the viewport captures the keyboard and makes the game appear frozen.
3. Start OpenCaptive or run the helper command above.
4. Confirm that the new window title is DOSBox-X and that it shows the Captive video-mode prompt.
5. Click the game viewport, press 1 for VGA, and wait for the original intro.

Do not reuse a window that is already showing a dungeon, a debugger prompt, or an old planet. A fresh launch is required for each startup verification.

First screen and keyboard focus

1. Wait until DOSBox-X displays Please Select your Video Mode.
2. Click once inside the DOSBox-X game viewport. This gives the SDL window keyboard focus; clicking only the title bar is not sufficient.
3. Press 1 for VGA.
4. Wait for the original Captive title/intro to finish loading.

If the number is ignored, click inside the viewport again and press 1. There is no debugger prompt in a normal launch.

When testing with the helper, the only supported launch command is:

tools/run_captive_dosbox_x.sh /Users/bosse/.opencaptive/captivedebug/captive

The helper mounts that directory as C:, changes to C:, and runs CAPTIVE.BAT 1. This is the original startup path. Do not add a second CAPPO.EXE command, do not copy generated files into the data directory, and do not use a debugger launch for an interactive test.

DOSBox-X captures the system pointer when the game starts so CAPPO can receive its original INT 33 motion. Press Ctrl+F10 to release or recapture the pointer. This is a DOSBox-X shortcut, not a Captive command. The repository profile deliberately uses mouse emulation=locked; integration would stop feeding CAPPO while the pointer is captured.

On a MacBook keyboard, the number row is not the Captive keypad. Use the original on-screen arrow buttons, or a real/emulated numeric keypad, for navigation. In particular, 7 and 9 mean ORBIT and LAND only when CAPPO receives the keypad scan codes; ordinary number-row 7/9 input is not a substitute. This avoids mistaking a key that was never delivered to CAPPO for a broken flight or landing state.

Space navigation sequence

Captive's original controls are still owned by the DOS runtime:

• keypad 7: ORBIT
• keypad 9: LAND
• keypad arrows: steer the ship
• the on-screen arrow buttons: the same navigation controls

The blinking green marker identifies the destination planet. After reaching that planet, the white circle identifies the landing point. Press ORBIT and wait for the ship to enter the destination planet's orbit before pressing LAND. Landing early is rejected by the original game. If the selected point is surrounded by water, it is the wrong landing point; return to orbit and find the white landing circle.

The zoom keys change the original navigation state. They must not be treated as a post-process pixel enlargement of the rendered frame.

The original keyboard mapping used by the game is:

Key	Original action
keypad 7	ORBIT; begin travel toward the selected planet
keypad 9	LAND; valid only after arrival in orbit
keypad 8	move forward
keypad 2	move backward / descend
keypad 4 / 6	turn left / right
keypad 1 / 3	climb / descend ladder in the landed view
keypad 5	no movement

The on-screen navigation buttons must call these same original actions. A button that only enlarges the last image is not navigation and is a failure.

The tested route has four separate states:

planet marker selected -> FLIGHT PATH SET -> ARRIVED AT DESTINATION / NOW IN ORBIT -> LAND

ORBIT starts the flight. It does not mean that the ship has already arrived. Wait until the original runtime reports or visibly enters the destination orbit; only then use LAND. LAND is not a shortcut into a dungeon. A successful landing must produce the original landed view and its real local terrain; a water-only view is evidence that the destination point was wrong.

The live DOSBox-X gate has been observed to produce CAPPO's original FLIGHT PATH SET message after ORBIT. Pressing LAND before the ship arrives then produces the original SWAN NOT YET IN ORBIT message. Both messages are useful diagnostics: they prove that the real input reached CAPPO, but neither message proves that the destination was reached. Continue only when the runtime itself shows arrival/orbit.

On macOS, a repeatable manual sequence is:

1. Bring the DOSBox-X window to the front and click once inside the viewport.
2. Choose VGA with the number-row 1 at the startup prompt.
3. Let the original intro finish; press Space only when the intro asks for a key.
4. Select the blinking green planet with the original arrow controls.
5. Activate ORBIT and wait for the real transit state to finish.
6. Activate LAND only after the original runtime confirms orbit.

Do not use a number-row 7/9 as a substitute for the keypad commands on a MacBook. Use the on-screen controls or a real/emulated numeric keypad so the DOS keypad scan codes reach CAPPO.

The valid evidence sequence is:

green planet marker -> ORBIT -> original transit state -> destination orbit
-> white landing circle -> LAND -> original dungeon view

Do not continue by selecting a hard-coded coordinate or fabricating a dungeon when one of these transitions is missing.

Normal launch versus diagnostics

For interactive play, use the helper command above or launch Captive from the OpenCaptive start menu with authentic data. The helper opens a standalone DOSBox-X window for manual testing; the start menu uses the same normal launch path so the original runtime remains fully interactive in DOSBox-X. Do not add these debugger options to either normal path:

• -break-start
• -set debuggerrun=debugger
• the FIFO/expect diagnostic harnesses

Those options intentionally pause CAPPO in the DOSBox-X debugger and are for memory dumps, disassembly, and exact VGA comparisons. They are not evidence of working mouse input, orbit, landing, or dungeon navigation.

For a reproducible startup-only diagnostic, use:

tools/captive_dosbox_intro.expect \
  /Users/bosse/.opencaptive/captivedebug/captive

For the current real-data Mission 0001 route gate, use:

tools/verify_captive_target_route.sh \
  /Users/bosse/.opencaptive/captivedebug/captive

That gate currently proves the authentic initial target/cursor alignment and the FLIGHT PATH SET boundary. The supplied Mission 0001 VGA state already places the green destination marker beneath CAPPO's magenta cursor; moving the holomap first moves away from the real target and is not a valid route proof. It does not claim that the automated route has reached ARRIVED AT DESTINATION, NOW IN ORBIT, or LANDING SUCCESSFUL.

Longer transit observation is supported by the diagnostic harness. Its extended response timeout only gives DOSBox-X time to return a complete original dump; it does not create an arrival or advance the game locally. The harness's mouse-motion commands use DOSBox-X's authentic integration register encoding and never write CAPPO's pointer coordinates directly.

The automated ORBIT-dispatch probe is not part of the verified release path: direct debugger queue injection is not equivalent to a real keyboard event and must not be used as parity evidence.

The full-sequence diagnostic may log CAPPO's live CS:IP, DS, AX, SI, and DI after scan 47. Those registers are observation evidence only. In particular, the previously recorded 0824:CF87 address byte-matches source offset 0xD387, a rendering helper, and is not an Orbit/arrival proof. The probe never writes a guessed orbit or landing state into memory; only a changed original VGA frame and matching original runtime state can advance the parity boundary.

Troubleshooting

DOSBox-X debugger stepping

VRT and TIMERIRQ are DOSBox-X debugger observation commands, not Captive commands. VRT resumes execution to the next vertical retrace, while TIMERIRQ runs one emulated system-timer interrupt. Neither command may create a planet, route, orbit, landing point, dungeon, or status message. A debugger session that reaches FLIGHT PATH SET is still only a route-selection result; arrival must be observed in the original CAPPO state and VGA output before LAND can be tested.

Do not use debugger stepping during normal play. It can pause the original game, alter input timing, or leave DOSBox-X at a debugger prompt. The repeatable interactive procedure remains the authentic CAPTIVE.BAT 1 launch described above.

Symptom	Correct action
VGA choice does nothing	Click inside the game viewport, then press 1.
Debugger window appears	Quit and restart with the normal helper; remove debugger flags.
System pointer moves but Captive pointer does not	Click the DOSBox-X game viewport once so it is captured; the supplied profile must say mouse emulation=locked. Press Ctrl+F10 once if the pointer was released, then click the viewport again.
The ship is still in transit	Wait for the original orbit/arrival state before pressing 9 for LAND.
A landed view contains only water	Restart from orbit and fly to the white landing circle.
The viewport looks stretched or corrupted	Use the repository profile; it forces VGA, surface output, integer scaling, and the CAPPO-compatible VGA memory setting.
An old or unexpected game state appears	Close every old DOSBox-X window and follow the Daily reset checklist.