Events and input

Input reaches a program as events: four-byte records in a queue that the host fills at the start of each frame and the program empties with the system device's next_event call. Keys, typed text, the pointer and the wheel come from the user; other events are answers from devices (content requests, page layout) and, for the shell of a system, news about its machines. Game controllers are not events: their state is read with the controller call. This article lists every event and the controller state byte by byte.

The queue

next_event (101h) takes a0 = a 4-byte buffer in RAM. It removes the head event, writes type, a, b, c in that order, and returns 1; if the queue is empty it writes nothing and returns 0. In C:

terse_event e;                 /* fields: type, a, b, c */
while (terse_event_pop(&e) != EV_NONE)
    handle(&e);                /* EV_NONE is 0: queue empty */

Event types

TypeNameabc
01hKey downkey codemodifiers0
02hKey upkey codemodifiers0
03hTextcode point bits 0-7bits 8-15bits 16-20
04hPointerx bits 0-7y bits 0-7bits 0-1 x bits 8-9, bit 2 y bit 8, bits 3-5 buttons, bits 6-7 zero
05hContent donerequest handlestatus0
06hWheelvertical steps, signedhorizontal steps, signed0
07hFeeds updated000
08hPage laid outheight bits 0-7bits 8-15bits 16-23
09hPage anchoranchor id bits 0-7bits 8-15bits 3-5 buttons
0AhMachine changedhandlenew state0
0BhHome000
0ChMachine pressedhandlebuttons0
0DhPage locatedanchor id bits 0-7bits 8-15line height
0EhPage located yy bits 0-7bits 8-15bits 16-23
0FhOpen requestedhandle00
10hSnapshot doneslotstatus0

terse.h names them EV_KEY_DOWN, EV_KEY_UP, EV_TEXT, EV_POINTER, EV_CONTENT_DONE, EV_WHEEL, EV_FEEDS_UPDATED, EV_PAGE_LAID_OUT, EV_PAGE_ANCHOR, EV_MACHINE_CHANGED, EV_HOME, EV_MACHINE_PRESSED, EV_PAGE_LOCATED, EV_PAGE_LOCATED_Y, EV_OPEN_REQUESTED and EV_SNAPSHOT_DONE.

Keys

Key down and key up carry the key's USB HID keyboard usage ID: the physical key, whatever the keyboard layout. Use text events for the characters a user types.

KeyCodeterse.h
A to Z04h to 1Dh
1 to 9, 01Eh to 26h, 27h
Enter28hKEY_ENTER
Escape29hKEY_ESCAPE
Backspace2AhKEY_BACKSPACE
Tab2BhKEY_TAB
Space2ChKEY_SPACE
F1 to F123Ah to 45h
Insert49h
Home4AhKEY_HOME
Page Up4BhKEY_PAGE_UP
Delete4Ch
End4DhKEY_END
Page Down4EhKEY_PAGE_DOWN
Right, Left, Down, Up4Fh, 50h, 51h, 52hKEY_RIGHT, KEY_LEFT, KEY_DOWN, KEY_UP

The modifiers byte b has bit 0 Shift, bit 1 Control, bit 2 Alt and bit 3 Meta (MOD_SHIFT, MOD_CONTROL, MOD_ALT, MOD_META); the other bits are zero.

A host may keep some keys for itself. In a system the home key (F12 in terse-host) is never delivered to any machine; with a single machine there is no home key. While the host shows a consent prompt the keyboard is the host's. A host may keep a few more, such as a paste key (terse-host takes Ctrl+V and Shift+Insert); such a key's press and its release reach no program, though the modifier keys held with it do.

While a key is held a host may repeat it: more key-down events for the same key, each followed by the text it types, with no key-up between them, and one key-up at the end. So a key-down for a key that is already down is a repeat.

Text

A text event carries one Unicode scalar value (up to 21 bits) produced by the host's text input, after the keyboard layout and input-method composition: a is bits 0-7, b bits 8-15 and c bits 16-20. In terse-host a key that types a character gives a key down, then a text event. No host sends a text event for a control character: Enter, Tab, Backspace, Escape and Ctrl+letter give only their keys.

uint32_t cp = e.a | (uint32_t)e.b << 8 | (uint32_t)e.c << 16;

Text the user pastes arrives the same way, one event per character, with no key events, no faster than the queue has room for, to whichever machine has the focus as it is sent. A CR LF pair or a lone CR becomes U+000A; other control characters are dropped.

Pointer

Positions are in screen units: x from 0 to 639, y from 0 to 479, (0, 0) at the top left. A pointer event is sent when the position or a button changes, at most once per frame for movement; a button change is sent at once, with the current position. Positions outside the screen are clamped to it, and nothing is sent when the pointer leaves the host's window.

ByteBitsContents
a0-7x bits 0-7
b0-7y bits 0-7
c0-1x bits 8-9
c2y bit 8
c3primary button
c4secondary button
c5middle button
c6-7zero

The macros of terse.h decode it:

if (e.type == EV_POINTER) {
    uint32_t x = EV_POINTER_X(e);       /* 0-639 */
    uint32_t y = EV_POINTER_Y(e);       /* 0-479 */
    uint8_t buttons = EV_POINTER_BUTTONS(e);
    if (buttons & BUTTON_PRIMARY)
        press(x, y);
}

EV_POINTER_BUTTONS gives the three button bits shifted down to bits 0-2, where BUTTON_PRIMARY (1), BUTTON_SECONDARY (2) and BUTTON_MIDDLE (4) test them. A button that was pressed is detected by comparing with the buttons of the previous pointer event. A terminal cell under the pointer is column x / 8, row y / 16.

Wheel

a is the vertical steps and b the horizontal steps, each a signed byte from −127 to 127 (read them as (int8_t)e.a). A positive vertical step means scroll down, towards later content; a positive horizontal step means scroll right. At most one wheel event is sent per frame; the host adds up smaller movements until they make a whole step.

Answers from devices

The page device's article has the exact rules for its events.

Events only the shell gets

These go only to the shell of a system, the machine with device 8:

TypeNameMeaning
0AhMachine changedmachine a is now in state b (1 loading, 2 running, 3 paused, 4 exited, 5 faulted, 6 failed), a change the shell did not make with a call
0BhHomethe user pressed the host's home key; the focus is now the shell
0ChMachine presseda pointer button was pressed over machine a's picture; b is the buttons
0FhOpen requestedmachine a made an open request the shell can read with request
10hSnapshot donethe snapshot asked for slot a: b = 1 stored, 3 failed

Input in a system

In a system the host's input is in the shell's screen units, and each frame it is routed before the shell runs:

InputGoes to
Key down, key up, text, wheelthe machine with the focus if it is running; the shell if the focus is 0; otherwise nobody
Pointer over a machine's picturethat machine (the highest handle where pictures overlap), mapped into its screen units, if it is running; otherwise nobody
Pointer over no picturethe shell, unchanged
Controllersthe machine with the focus (the shell if it is 0); every other machine reads all four as not connected
Content done, feeds updated, page eventseach machine its own
Anything else in the host's inputthe shell, unchanged

The focus that routes a frame's input, controllers included, is the one at routing: a home key changes it for the events after it, and a focus call takes effect at the next frame.

A position (x, y) over a picture at (px, py) of size pw × ph is mapped to x′ = ⌊(2(x − px) + 1) × 640 / (2pw)⌋ and y′ = ⌊(2(y − py) + 1) × 480 / (2ph)⌋. A pointer event that presses a button over a picture also gives the shell a machine pressed event, whatever the machine's state.

Controllers

Up to four game controllers, numbered 0 to 3. Their state is latched at the start of each frame, so it does not change within a frame. The controller call (105h, a0 = number, a1 = 8-byte buffer in RAM) writes eight bytes and returns byte 0; a number above 3 reads as not connected.

ByteContents
0bit 0: connected; other bits zero
1bits 0-7: up, down, left, right, A (bottom), B (right), X (left), Y (top)
2bits 0-7: left shoulder, right shoulder, left trigger, right trigger, select, start, left stick press, right stick press
3left stick x, signed: −127 left to 127 right
4left stick y, signed: −127 up to 127 down
5right stick x
6right stick y
7zero

A controller that is not connected reads as all zeros. Axis values are never −128. In C, terse_pad_read(n, &pad) fills a terse_pad (fields connected, buttons, buttons2, lx, ly, rx, ry), and PAD_UP ... PAD_Y test buttons, PAD_L1, PAD_R1, PAD_L2, PAD_R2, PAD_SELECT and PAD_START test buttons2.

terse_pad pad;
terse_pad_read(0, &pad);
if (pad.connected) {
    x += pad.lx / 32;
    if (pad.buttons & PAD_A)
        jump();
}

Recording and replay

Every event is an input. The events of each frame, with the Unix time, the random bytes, the controller states and the content completions, are what a host records to replay a run exactly; terse run --events <file> reads such input from a text file. Reading an event costs 4 units plus 1 for the copied record; see charges.