SCRYDOSBox-XReferenceInputsend_keys
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
perform.Press the space bar to serve the ball, and tell me whether the game logged the serve.
send_keys(keys=["space"], expect="SERVE$", seconds=10){
"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
{
"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,f1orleft. - modifiers array of one of
"shift","ctrl","control","alt","option"(in any case), optional - Keys held around the others:
shift,ctrl(orcontrol) andalt(oroption), 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
expectline, up to 600. Left out, 10; refused withoutexpect. - action one of
"press","down","up", default"press" presstaps each key;downpresses and holds,uplets go, so a key can stay held across calls. Left out,press.
What comes back
- verify
- Whether the program reacted.
checkedisfalsewith noexpect; elseverdictisTARGET(the line came, inline) orTIMEOUT(it did not). - posted
- How many keys were sent into the program.
bytesis how many scan-code bytes they made, andframeshow many commands the helper took. - route
- Which way the input went in: always
guesthere, 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:
falsewhen nothing went in and the call can be sent again,truewhen 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
- A key or a modifier it has no name for; a DOS keyboard has no command key (
bad_argument). - No key at all, or more than 64 (
bad_argument). secondswithoutexpect, anexpectthat is no valid pattern, or anexpectwith no log to read (bad_argument).- No helper answering inside DOS, or a helper of another protocol version (
no_channel). - A stopped machine on a build whose debugger has no
RUNSTATEcommand (no_channel). - A breakpoint that stops the machine while the keys go in, or during the
expectwait (wait_stopped). - An emulator busy inside a long host call, which answers nothing: no key was sent (
host_failed).
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
RUNSTATEdebugger 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
logsince the send. - An emulator that died is
verify.checked: false, never a swallowed key. - A program that writes nothing to its log gives
expectnothing 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
performor adrive, aTIMEOUTends 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.
Related tools
The contract your client receives
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.