DOS games in DOSBox-X: what to know before the first run

What to know

A DOS game is one of four kinds of program. The kind decides which tools you use after it. Run ./gameframe run dosinfo GAME.EXE first. Then run the game in DOSBox-X through scripts/dosbox-run.sh. Run it on a copy of its folder, with a fixed CPU speed, and log its file reads. Use the debugger through the dosbox MCP server or dbx_control.py.

• The kind of program. MZ is real mode (Turbo Pascal, Turbo C, Microsoft C). NE is 16-bit protected mode with a DPMI host (Borland Pascal 7, Borland C++). LE or LX is 32-bit code behind a DOS extender (Watcom with DOS/4GW, PMODE/W). PE is a Windows program (docs/DOS.md).
• Packed programs. LZEXE, PKLITE, EXEPACK and DIET must be unpacked first. dosinfo names them. Unpack with UNP, or dump memory from DOSBox-X after the unpacker has run.
• Overlays and appended data. Data after the MZ load image is an overlay (Borland's starts with FBOV), a packed payload or debug symbols. Check for debug symbols before anything else.
• Addresses. Use Ghidra's numbering everywhere: segment 1000 for MZ, selectors 1000, 1008 and on for NE. The DPMI host chooses a live selector. Map it through the LDT.
• Speed. Many games time themselves by the CPU or by timer interrupts. Fix the speed with --cycles N and use the same value for every run you compare.
• Files. --fileio logs every open, read, seek and write, and fileio_trace.py turns it into a map per file. The Pascal runtime reads a text file in 128-byte blocks. For such a file, read the code.
• Hardware. insns GAME.EXE '^(in|out)' lists the ports: 0x201 joystick, 0x40 to 0x43 timer, 0x220 to 0x22f Sound Blaster, 0x388 AdLib. '^int ' lists the BIOS and DOS calls.
• Exit codes. A batch file reads them with IF ERRORLEVEL. DOSBox-X's shell does not expand %ERRORLEVEL%.
• One function at a time. dos_emu runs a single routine for exact results. dos_env runs the whole program headless, with frames and memory for scripts.