List the game profiles this server knows and, for one of them, every named memory offset it exposes. A profile says how to recognise the game's data segment, where the game keeps its mouse state, and what its screen looks like. Call this first: the symbol names it returns can be used anywhere an offset is accepted.

Start DOSBox-X with a config file and attach to it. Returns the process id every other tool takes. The config's [autoexec] section decides what runs; an AUTOTYPE line there is the reliable way past intro screens. Waits until the guest is findable, so a successful call means it is really up and drivable. On Linux, isolated=true puts the emulator on its own Xvfb display -- entirely off the user's desktop, and the only way the emulator's own keyboard shortcuts can be used without taking a keystroke from whatever the user is doing.

Attach to a DOSBox-X process that is already running, by process id, and locate the game's data segment inside it. Use dosbox_sessions to find candidate process ids.

List attached sessions and any other visible DOSBox-X windows on the machine, with their process ids.

Close a DOSBox-X session. By default only sessions this server launched may be killed; pass force to end one it merely attached to. The guest is not asked to save anything first.

Type into the guest by appending to its BIOS keyboard ring buffer -- no window focus, no host keystrokes. Each item is a single character or a key name (space, enter, esc, tab, backspace, up, down, left, right, home, end, pgup, pgdn, plus, minus, f1..f10). Keys are paced apart so the game consumes them one screen at a time; the ring holds 15, so send small batches and let the game catch up. Fails cleanly if the ring is full, which means the game is waiting on the mouse, not the keyboard.

Click at a guest screen coordinate by writing the game's own mouse state, the words its INT 33h handler normally fills in. The host pointer never moves. The state is rewritten continuously for duration because the game's handler keeps overwriting it; a single write usually loses that race. Beware: on 'click to continue' pages one click can advance two pages -- send a key instead when paging through lists.

Hold mouse buttons down for a stretch of time by writing the guest's button word continuously -- the way to drive anything that reads a held button, such as an action sequence that only advances while a button is down. Sparse writes lose to the game's own interrupt handler, so this busy-writes. Give stop_when to release as soon as a memory field says the sequence is over, instead of holding for the full time.

Read bytes from the guest. With no segment this is the game's own data segment and offset may be a profile symbol name; with segment=0x1234 it is any segment in the guest -- another program in a launcher chain, a TSR, an overlay, or the interrupt vector table at segment 0. Choose a format: hex (raw bytes), u8/u16/u32 (little-endian numbers), or text (NUL-terminated string). This is how to read game state -- money, a unit's health, which screen is up -- without any of it being visible on screen.

Patch the game's data segment. This is how to set up a state that would otherwise take hours of play -- a treasury, a rank, a flag -- so a particular screen or code path can be reached. Writes land in the running game and are not undoable; the game may recompute a field shortly after it is written, so patch at a moment where it will be read before it is recomputed.

Write a whole 64 KiB guest segment to a file -- the state at one instant, for later analysis or as a test fixture. With no segment this is the profile's data segment; with segment=0x1234 it is any segment in the guest, which is how the marker for a new profile is captured.

Block until a memory field satisfies a test, or the timeout runs out. Use it to wait for a screen transition, an animation to finish, or a state byte to settle, instead of guessing at sleeps. Returns whether the test was satisfied and the last value seen -- it does not raise on timeout, so a caller can decide what a timeout means.

Look at the emulator's screen. Returns the current frame as an image, photographed from the window without activating it. Use this to see where the game actually is between steps; use dosbox_capture_screen when the frame has to be exact and saved.

Capture the current frame exactly and save it: .rgb (one byte per pixel), .png, and with with_segment also _ds.bin, the data segment from the same instant -- which is what makes a captured frame replayable as a fixture.

source='vram' reads the frame out of the emulator's video memory, which is exact, cheap, cannot catch a half-drawn frame and does not slow the guest. source='window' photographs the window instead, resizing it to an integer multiple of the guest resolution; that is the one visible effect this server has on the desktop, and it costs the guest real time. 'auto' takes video memory when the page has been CONFIRMED against a reference and falls back to the window otherwise, so it never quietly saves the wrong 64,000 bytes.

What this host can do, and what it cannot. Guest memory works everywhere there is a backend; window capture and the emulator's own menu commands do not. Call this when a tool refuses, or before planning a session that depends on frames or recordings.

Find the DOS guest inside an emulator process and report what is loaded in it -- with no profile and no prior knowledge. This is the way in for a game nobody has described yet: it locates guest physical zero from the BIOS data area, then walks the DOS memory chain and names every loaded program, its load segment and the path it was started from. Those segments are what dosbox_read_memory(segment=...) and dosbox_search_memory take, and what a new profile is written from.

Search the guest's 640 KiB of conventional memory for a byte pattern and report every hit as a guest segment:offset. This is how a known string -- a file name the game opens, a message it prints -- becomes the segment that holds it, which is the first step in writing a profile. Give text, or hex for raw bytes.

Fire one of DOSBox-X's own menu items without focus and without a keystroke: record_opl, record_midi, record_wave, record_video, screenshot, save_state, load_state. Firing a record action again stops that recording. Windows only -- DOSBox-X draws its own menu elsewhere; see dosbox_capabilities.

Record the guest's sound for a stretch of time and return the file that appeared: an OPL register log (.dro), the MIDI stream (.mid) or the mixer output (.wav). This is the only independent record of what a game's sound driver actually writes. Arm it EARLY -- DOSBox-X starts an OPL capture at the guest's first register write, so arming late does not truncate the capture, it starts it somewhere else entirely.

Read the guest's screen straight out of the emulator's video memory: the palette indices the guest wrote, at the instant of the read, with no window, no scaling and no palette round trip. Prefer this over dosbox_capture_screen for anything quantitative -- photographing the window costs the guest real time and can catch a half-drawn frame.

FINDING THE PAGE NEEDS A REFERENCE. Give reference= a 64,000-byte frame of what is on screen and the page is confirmed byte for byte; without one this refuses, because a blind scan finds the most picture-like page in memory and on a real guest that is often a sprite bank or an offscreen buffer. Once confirmed the location is cached and every later read is free. allow_unconfirmed=true takes the guess anyway.

Writes .bin (one byte per pixel) and .png when stem is given. A page-flipping game has more than one page; pass page_offset from the pages list to read the other.

Watch the guest's video memory and return every distinct frame it put up, with the moment each appeared. This is how to measure an animation, a fade or a transition -- reading video memory does not slow the guest the way filming the window does, so the timings are the guest's own. Frames are written as _NNN.png.

Sample a set of memory fields repeatedly and write the series as a TSV. dosbox_read_memory answers what a value is and dosbox_wait_for answers when it becomes something; this answers how it MOVES, which is what most questions about a running program actually are. Every field in a row comes from one snapshot, so the columns do not drift against each other. watch takes symbol names, offsets, or the name of a watch set the profile defines. The whole segment at the entry instant is dumped beside the TSV, so a question nobody thought to put in the watch list can still be answered offline.

Find runs of zero in a guest code segment long enough to hold a trace cave. Padding between routines is the usual supply. Longest first; pass one of these offsets to dosbox_install_trace.

Watch a running guest's code without a debugger. Redirects one near CALL in the live code segment through a zero-filled cave that calls the displaced target, preserves its flags, and records the registers and memory words you name -- then read them with dosbox_read_trace while the guest runs at full speed. Nothing on disk changes; the patch dies with the emulator. captures take: a register (ax bx cx dx si di bp sp), a segment register (ds es ss cs), flags, or memory -- word:0x9D10, byte:DS:0x7A0E, word:ES:0x0004. Memory is read through whatever DS holds when the cave runs; capture ds too if the routine changes it. Give expect_hex (the three bytes the call site should hold) so the trace refuses rather than landing on a moved target.

Read what an installed trace has recorded: the values from its most recent hit, and how many times it has fired. A hit count of zero means the traced call has not run -- which is itself an answer.

Remove an installed trace: the call site is restored first so nothing new can enter the cave, then the cave is blanked.