Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Environment and Running the Game

Host tools

The first inventory found:

  • QEMU 11.0.2 (qemu-system-i386 and qemu-img)
  • Rizin 0.9.1
  • mdBook 0.5.3

The host is macOS on Apple Silicon. QEMU therefore runs the i386 guest using software emulation rather than hardware virtualization.

Guest operating system

The selected guest is the stable FreeDOS 1.4 release. The FreeDOS project recommends its LiveCD for installation in a virtual machine. Its published minimum is an Intel-compatible processor, 640 KiB of memory, and at least a 20 MB hard disk.

The repository-specific setup instructions require a noninteractive build rather than the FreeDOS installer. tools/setup_freedos_image.py downloads and verifies the official LiteUSB archive, extracts the largest image member, preserves its boot code and filesystem, and builds a new 1 GiB raw disk with a single active FAT16 LBA partition.

The base image is:

build/freedos/freedos.img

It has a 1 MiB partition offset (LBA 2048), so its mtools path is:

build/freedos/freedos.img@@1048576

The builder initially produces a clean FreeDOS base image. run.sh clones it to a separate persistent play image, copies CB/ to C:\CBDOME, installs CuteMouse from the LiteUSB package set, and replaces the clone’s boot scripts so the game starts automatically. At the user’s request, the complete game was also copied into the current base image at C:\CBDOME; rebuilding the base image will remove that additional copy.

Run the game

From the repository root:

./run.sh

The persistent play disk is build/captain-bible/captain-bible.img. Use ./run.sh --setup-only to prepare the disk without opening QEMU or ./run.sh --rebuild to replace it from the current CB/ tree. Rebuilding discards saves stored only in the old play disk.

For deterministic comparison, supply an unsigned decimal initial state from 0 through 65,535:

./run.sh --rng-seed 1

This mode never edits CB/CB.EXE. Immediately before QEMU starts, the launcher reconstructs and signature-checks the unpacked executable, installs the portable RNG, clones the persistent disk into a unique run directory below build/qemu-deterministic-rng/, injects the patched executable only into that clone, and copies it back out for a byte-for-byte check. QEMU runs the clone with -snapshot, so guest writes are discarded at exit. An existing persistent play image is unchanged unless --rebuild is also supplied; initial setup may create it. A normal launch removes the unique run directory after QEMU exits. Use ./run.sh --setup-only --rng-seed 1 to build and verify the disposable image without opening QEMU and retain its printed directory for inspection.

When booting the current base image directly instead, enter CD \CBDOME followed by CB. The normal ./run.sh path needs no DOS commands because its derived play image starts the game automatically.

The QEMU machine provides:

  • a Pentium-class i386-compatible CPU with 16 MiB RAM;
  • standard VGA in a visible Cocoa window with zoom-to-fit enabled on macOS;
  • a PS/2 mouse served through the CuteMouse DOS driver;
  • Sound Blaster 16 digital audio; and
  • AdLib-compatible FM synthesis.

The supplied SOUND.1 identifies itself as a Sound Blaster 16 driver, and SOUND.2 identifies itself as a Sound Blaster Pro FM driver. These match the emulated devices.

Verification result

The base image passed a screenshot-free boot smoke test. A temporary clone wrote FREEDOS_READY to C:\BOOT.OK from both patched boot-script paths, and the marker was read with mtools after QEMU stopped. A separate bounded launch of the play image reached the Captain Bible title screen at 640×400.

The user subsequently verified the complete interactive path: keyboard and mouse input work in the visible QEMU session, and the game exits normally through its menus. This closes the environment/playability check independently of the automated boot and title-screen evidence.

Initial game requirements

The supplied MANUAL.TXT says to change to the installation directory and run CB. It reports that the game needs approximately 500 KiB of conventional memory. Its optional command-line switches and player-name prefix are now recovered from game_main and documented in the static-analysis and save-game chapters.