A set of small Python tools for reading and changing the memory of a running DOSBox-X game, with a launcher that ties them together.
Work in progress. These tools were started as groundwork for letting an AI play DOS games: to play, an AI needs to see the game (screen and video memory) and understand its state (lives, score, position in memory). The current tools do this by hand; automating it is the next step.
- Windows 10 or 11
- Python 3.12 or newer (keep the default installer options; tcl/tk must be included)
- DOSBox-X
Open PowerShell or Command Prompt and run:
# 1. Get the code
git clone https://github.com/<your-username>/DOS_BOX_UTILS.git
cd DOS_BOX_UTILS
# 2. Create and activate a virtual environment
python -m venv venv
venv\Scripts\activate
# 3. Install the dependencies
pip install -r requirements.txt
# 4. Start the launcher
python launcher.pyNext time, only steps 2 (activate) and 4 are needed.
If PowerShell refuses to run
activate, allow local scripts once:Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
Start DOSBox-X with a game, then open a tool from the launcher. Every tool finds the DOSBox process (PID) automatically.
| Tool | File | What it does |
|---|---|---|
| Base Finder | base_finder.py |
Finds the Base address of DOS memory inside the DOSBox process and verifies it. Start here. |
| Live Hex Viewer | live_hex_viewer.py |
Live hex dump of DOSBox memory. Changed bytes light up. Click a byte to see its value and copy its address. |
| Snapshot Diff | comparesnap.py |
Captures DOS memory straight from DOSBox (or loads .bin dumps), compares two snapshots and lists every changed byte. Filters, debugger-style DS view and TXT/CSV export. |
| Memory Trainer | memorytrainerautopid.py |
Writes bytes to an address once, or freezes them at a value. |
| VGA Live Viewer | vgautilityautopid.py |
Shows VGA mode 13h video memory (320x200, 256 colors) live. |
| CGA Live Tuner | cgautilautopid.py |
Shows CGA mode 4 video memory (320x200, 4 colors) live, with a flicker filter. |
| Input Finder | input_finder.py |
Finds where a game stores its key states by counting which bytes go back and forth as you tap a key. |
| Key Injector | key_injector.py |
On-screen keypad that presses keys in the game by writing to memory. Profiles per game. |
| Live Preview | livepreview.py |
Live capture of the DOSBox window. |
| Launcher | launcher.py |
Starts all of the above. |
- Find the Base with the Base Finder (once per DOSBox session, see below).
- Find a value: watch memory in the Live Hex Viewer, or press Capture 1 before and Capture 2 after an event (e.g. losing a life) in Snapshot Diff and filter by old/new value. Find keys with the Input Finder.
- Change it: click Copy for Trainer in the hex viewer, paste the address into the Memory Trainer, and inject or freeze a new value.
- Look at the screen as the game stores it: the VGA and CGA viewers decode video memory directly.
Addresses are written as Base + Offset in hex, for example 0x1F2A0000 + 0x1234:
- Base is where DOS memory starts inside the DOSBox process. It changes every time DOSBox starts.
- Offset is the position inside DOS memory, the same address the DOSBox-X debugger shows.
Open the Base Finder while a game is running. There are three ways, from easiest to most manual:
- Auto Find Base: one click, no input. The tool scans the whole DOSBox process and finds the start of DOS memory directly. No search text, no debugger, no location needed.
- Text or byte search with an empty Location in DOS: search for a text the game shows (for example
barbarian) or bytes copied from the DOSBox-X debugger. For each hit, the tool walks backwards until it finds the start of DOS memory. The results table then shows:- Calculated Base: the real Base.
- In DOS: where the hit sits inside DOS memory, as
segment:offsetwhen it is below 1 MB. This is the same address the DOSBox-X debugger shows.
- Search with a known location: if you already know the
segment:offsetof the pattern (e.g.0823:0010), enter it as Location in DOS and the Base is calculated directly. This is the fallback if the automatic methods do not work.
Verified results get a green tick. Double-click one to copy the Base.
Once the Base is known, the video memory is always at Base + 0xA0000 (VGA) or Base + 0xB8000 (CGA), and offsets in the hex viewer match the DOSBox-X debugger.
The start of DOS memory always looks the same, which gives it a fingerprint:
- Interrupt vector table at
0000:0000: 256 entries. Many of them (about 100 in DOSBox-X) point into the BIOS ROM segmentF000. Unused entries may be empty, so only ROM segments (C000and above) are counted. - BIOS data area right after it (
0040:0000), with values every PC BIOS sets the same way: 640 KB of conventional memory at0040:0013, the keyboard buffer at001E-003E, and the video controller port (3D4or3B4).
All of these together are practically impossible to match by chance, so random data, internal DOSBox tables and leftover copies are rejected.
- The detection was tested on a simulated 16 MB DOSBox memory block placed at an unaligned address across read-chunk borders, with one search hit below 1 MB and a copy above 1 MB (extended memory), next to decoy regions containing thousands of fake "640" values and a zero-filled fake BIOS area. Auto Find Base returned exactly the correct Base, both hits were linked to it, and none of the decoys passed.
- The fingerprint was then checked against the interrupt vector table and BIOS data area captured from a real DOSBox-X session. Two corrections came out of that: DOSBox-X leaves unused vectors empty (the first version expected them to share one segment), and the looser check that followed matched 150+ internal DOSBox tables. Adding the fixed BIOS data area values brought it back to exactly one result.
- If Auto Find Base reports No DOS memory found on your setup, use method 3 (known location) and please open an issue.
Action games usually hook the keyboard interrupt and keep their own table of key states: a byte changes when a key goes down and returns to its old value when the key is released. The Input Finder uses exactly that:
- Stand still in the game and press Learn noise. For 3 seconds every byte that changes on its own (timers, music, animations) is recorded and ignored from then on.
- Press Start watching, switch to the game and tap one key exactly as many times as I tapped says.
- Bytes that left their idle value and came back exactly that many times are marked with a star. The player position or score also change, but they do not return to the idle value, so they get 0 presses.
Simpler games read keys through the BIOS instead: the keyboard buffer at 0040:001E and the shift flags
at 0040:0017 light up in the Live Hex Viewer.
The Key Injector is a keypad with 10 configurable keys. Hold a button (or the number keys 1-0) to keep a key pressed; release it to let go. Each key works in one of two modes:
- Memory: for games with their own key-state table. While held, the Pressed bytes are written to the address again and again; on release, the Idle bytes are written back. Read fills Idle with the current value.
- BIOS key: for games that read keys through the BIOS. The key is pushed into the BIOS keyboard buffer
(
0040:001E-003D) and the buffer's tail pointer is advanced, exactly as the BIOS does when a key is typed. Held keys repeat. Barbarian, which is played with the F-keys, works this way: F8 is scan code42.
Key settings can be saved as a profile per game in profiles/.
DOS_BOX_UTILS/
├── launcher.py Launcher
├── base_finder.py Base Finder
├── live_hex_viewer.py Live Hex Viewer
├── comparesnap.py Snapshot Diff
├── memorytrainerautopid.py Memory Trainer
├── vgautilityautopid.py VGA Live Viewer
├── cgautilautopid.py CGA Live Tuner
├── input_finder.py Input Finder
├── key_injector.py Key Injector
├── profiles/ Key Injector profiles (one JSON per game)
├── livepreview.py Live Preview
├── screen_locator.py Screen Locator
├── palettes.py VGA palettes (used by the VGA viewer)
├── foundresults/ Saved findings
├── logs/ Error output of each tool (created by the launcher)
└── requirements.txt
Some games do not draw straight to the usual video address: they scroll with hardware tricks, flip between several screen pages, or use a virtual screen wider than the visible one. The Screen Locator finds the picture anyway:
- Pause the game (DOSBox-X: Alt+Pause) and take a screenshot (Ctrl+F5), or capture the window.
- Load the screenshot and press Search memory.
- The tool picks detailed rows from the screenshot, uses the pattern of where neighbouring pixels change color as a fingerprint (independent of the palette), and scans the DOSBox process for it, decoded both as VGA 256-color and EGA 16-color planar memory.
- Each hit is checked by finding the line stride from a second row and comparing the whole frame.
The result gives the address, mode, stride and pixel pan to enter in the VGA viewer.
Example: Commander Keen 6. EGA 16 colors with a 512-pixel virtual screen (stride 64), the picture starting 2 pixels into the first byte (pan 2), and three screen pages 0xF000 apart that the game flips between. All of this was found automatically from one screenshot.
- Windows only: the tools use the Windows API to read and write another process's memory.
- Some antivirus software may warn about the trainer, because writing to another process's memory is what game trainers do.
- If a tool does not open from the launcher, its error is in
logs/<tool>.log.
The goal is an AI that can play DOS games. It needs to see the game and act in it:
- Share the found Base with the other tools so it does not have to be pasted
- Read game state (lives, score, position) as structured data
- Switch the emulated screen mode from code
- Script sequences of key presses (macros) that an AI agent can trigger
- Connect the tools to an AI agent that can watch and play
Launcher with the tools around it

**Second Part **



