SCRYDOSBox-XReferenceInputsend_keys

DOSBox-XInput

send_keys

Send keystrokes to the DOS program, and check in its log that it reacted to them.

send_keys(keys, modifiers=null, expect="", seconds=null, action="press")

Try it

On Bricks, the game this repository builds, running, with the ball waiting on the paddle. The example session sends this key as one step of a perform.
Ask

Press the space bar to serve the ball, and tell me whether the game logged the serve.

Call
send_keys(keys=["space"], expect="SERVE$", seconds=10)
Reply 7 of 9 fields
{
  "summary": "send_keys (guest): reaction seen",
  "status": "ok",
  "keys": ["space"],
  "route": "guest",
  "posted": 1,
  "bytes": 2,
  "frames": 2
}

"reaction seen" means the game wrote a line matching SERVE$ to its log after the key. One key (posted) went in as two scan-code bytes, each a command (frames) to the helper inside DOS, the guest route.

The whole reply
JSON
{
  "summary": "send_keys (guest): reaction seen",
  "status": "ok",
  "keys": ["space"],
  "modifiers": [],
  "route": "guest",
  "posted": 1,
  "bytes": 2,
  "frames": 2,
  "verify": {
    "checked": true,
    "seen": true,
    "expected": "SERVE$",
    "verdict": "TARGET",
    "line": "Bochs port E9h: SERVE",
    "seen_before_waiting": "<volatile>",
    "lines_before": "<volatile>",
    "waited_s": "<volatile>",
    "lines_total": "<volatile>"
  }
}

Arguments

keys array of string, required
The names of the keys to send, in order: at most 64, such as enter, a, f1 or left.
modifiers array of one of "shift", "ctrl", "control", "alt", "option" (in any case), optional
Keys held around the others: shift, ctrl (or control) and alt (or option), in any case. Left out, none.
expect string, default ""
A regular expression for the line the program writes to its log when it reacts. Left out, nothing is checked.
seconds number (> 0, <= 600.0), optional
How long to wait for the expect line, up to 600. Left out, 10; refused without expect.
action one of "press", "down", "up", default "press"
press taps each key; down presses and holds, up lets go, so a key can stay held across calls. Left out, press.

What comes back

verify
Whether the program reacted. checked is false with no expect; else verdict is TARGET (the line came, in line) or TIMEOUT (it did not).
posted
How many keys were sent into the program. bytes is how many scan-code bytes they made, and frames how many commands the helper took.
route
Which way the input went in: always guest here, through the helper inside DOS.
polls
From a stopped machine, how many frames it ran while the keys went in. The reply then also carries the stop it was left at.
delivered
Only on a send that failed: false when nothing went in and the call can be sent again, true when part of it did.
All 19 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • e9 (object)
  • frame (integer or object)
  • instruction (DosboxInstruction)
  • pc (string or object)
  • polls (integer)
  • regs (object)
  • stop_seq (integer)
  • watches (array)
  • bytes (integer)
  • delivered (boolean)
  • frames (integer)
  • keys (array)
  • modifiers (array)
  • posted (integer)
  • route (string)
  • verify (object)

What it refuses

Why it works this way

An input sent to a running program lands whenever it arrives, an instant no replay can find again. Sent to a machine stopped at the debugger, it goes in as the machine runs frame by frame. The reply counts those frames in polls and carries the stop, so an exported session can replay the input.

The commands go in a BIOS timer tick apart, so a game that reads its keyboard once a frame sees a key go down before it comes up. That is also why a call takes at most 64 keys: every scan-code byte is one command, and the session answers nothing else until the last one is in.

expect is matched against what the program literally writes, so read its log once first: a program that logs key down x mods=4 for alt+x is telling you its pattern. A miss is TIMEOUT beside what was sent, because a swallowed key and a key never sent are different facts.

More on why

The helper

The server takes the emulated COM1 for the helper and switches on DOSBox-X's integration device itself: your conf needs neither, and one that sets serial1 loses it. start loads the helper on the first drive letter from Y: down that the conf's [autoexec] does not mount; a conf that mounts them all is refused.

The helper announces itself in the program's log. The first input is refused no_channel when that line is missing or names another protocol version; with no logfile there is no line to read, and input goes out unchecked.

  • It works from the serial port's interrupt, so a game that takes over the timer still gets its input. One that also masks IRQ 4 does not.
  • It runs on the stack of the program it interrupts, so a small private stack has to leave room for it.
  • Each command is acknowledged before the next goes: a lost byte is sent again, and no command runs twice.
  • The tick between commands is the program's own emulated time, which a slow host stretches; without the RUNSTATE debugger command it is real time.

If a breakpoint stops the machine inside the helper, resume from that stop: moving the instruction pointer out leaves the helper ignoring every later input. A breakpoint_interrupt on INT 33h can stop there, since the helper calls INT 33h itself.

A stopped machine

A code breakpoint that stops one of the frames ends the send there (wait_stopped), with the commands already taken in. A stop from a change watch or an interrupt breakpoint looks like the end of a frame and counts as one, as in run_for.

expect is then waited for one frame per look, and its seconds are the program's own time, so a replay that misses runs the same frames. In the stop the reply carries, e9 is what the program logged during every frame run, and watches are as the last frame read them.

No reaction seen

A machine that stops during the expect wait is refused wait_stopped, with last_stop. A command sent before the stop lands at the next resume, and later ones are not sent. So a key whose press stopped the machine stays down until a later send lets it go.

  • Whether an input went in before such a stop is for the program's log to say: read log since the send.
  • An emulator that died is verify.checked: false, never a swallowed key.
  • A program that writes nothing to its log gives expect nothing to match.
  • seen_before_waiting: true: the line came while the keys were still going in. It is still this input's reaction.
  • In a perform or a drive, a TIMEOUT ends the list there.
  • A new session's first key can be swallowed while DOS settles: send it once more before looking for a dialog.

verify in full: checked, expected (the pattern), seen, verdict, waited_s; when seen, line, seen_before_waiting, lines_before and lines_total; on a TIMEOUT, note, arrived_during and lines_examined. arrived_during counts the lines the program wrote during the wait: zero means it wrote nothing at all. why says why nothing was checked, and a stop during the wait adds stopped_during_wait and lines_on_disk.

Keys

A key sent while a dialog is closing can be swallowed. To send it once the screen has settled: stop, run_for a few frames, read screen_signature, and repeat until two reads agree; then send the key. A stopped machine's time moves only when run_for moves it, so the wait costs the program no time.

  • The keys go in as set 1 scan codes, composed by the server.
  • A cancelled call lets go of every key it had pressed, so none stays down repeating in the program.

A send the emulator could not take

While the emulator is inside a long host call, such as the first long-name open in a folder of very many files, its debugger does not answer. A send that meets this before writing anything is refused host_failed with delivered: false. Nothing went in: send it again once status answers.

A send cut part-way answers delivered: true with how many commands went in and how many did not: send only what was not written. A key it pressed and could not let go stays down until the session's next input, which lets it go first and says so in note.

Keys a call holds on purpose (action="down") are not let go this way, and loading a saved state forgets any key still owed.

The contract your client receives
Text
Send keystrokes to the guest; with `expect`, prove the program took them.

`keys`: at most 64. `action`: `press` taps them; `down` holds the modifiers and
presses the keys, `up` releases them, so a held key spans the calls between; a held key
makes no repeats of its own, each repeat is a further `down`. `expect`: a regex over the
E9 log the program's reaction writes, waited up to `seconds` (default 10).
A stopped machine is
run retrace by retrace until the stub takes each key, and left stopped at a retrace; its
`expect` waits `seconds` of the guest's own time.

Refused: an unknown key or modifier, `seconds` without `expect`, no stub, a stopped
machine on a build with no `RUNSTATE` (`no_channel`).

Reply: `route`, `posted`, `bytes`, `frames` (stub commands, a BIOS tick apart), `verify`
(`verdict` `TARGET` or `TIMEOUT`, `seen`); from a stopped machine `polls` and the stop
it was left at (the stop: `pc` (`SSSS:OOOOOOOO`), `cpu_mode`, `stop_seq`, `frame`, `instruction`, `regs`, `watches`, `cause`, `regpoint_hit` (a registerpoint stopped it) and `e9`).

Reference: REFERENCE.md, Input and the screen.
Tools