prometeu-runtime/docs/runtime/specs/06-input-peripheral.md

Input Peripheral (Input System)

Domain: virtual hardware: input Function: normative

Didactic companion: ../learn/input-mental-model.md

1 Scope

This chapter defines the runtime-facing input contract of PROMETEU.

Core contract:

• input is exposed as state, not asynchronous callback flow;
• sampling occurs at a defined moment in the logical frame;
• queries are deterministic during the frame;
• logical identifiers are stable across host devices.

2 Input Devices

PROMETEU abstracts different devices into a common interface.

Typical devices:

• digital control (D-Pad + botões)
• keyboard (mapped to buttons)
• gamepad
• touch (mobile, mapped)

Regardless of source, PROMETEU exposes the same logical model.

3 State Model

3.1 Per-Frame State

For each frame, the system maintains:

• current state of buttons
• state from the previous frame

This allows querying:

• button pressed
• button released
• button held down

3.2 Query Types

Typical operations:

input.btn(id)// button is pressed
input.btnp(id)// button was pressed this frame
input.btnr(id)// button was released this frame

These functions:

• are purely advisory
• do not change state
• have an explicit cost

4 Sampling Moment

The input state is captured at the beginning of each frame, before the UPDATE phase.

Conceptual flow:

FRAME N:
SAMPLEINPUT
UPDATE
DRAW
AUDIO
SYNC

Throughout the entire frame:

• the input state is immutable
• repeated calls return the same value

5 Determinism and Reproducibility

The PROMETEU input model guarantees:

• same sequence of inputs
• same frames
• same results

This allows:

• execution playback
• deterministic replays
• reliable certification

Input can be:

• recorded
• played back
• artificially injected

6 Input and CAP

Input operations:

• consume few cycles
• participate in the per-frame budget
• appear in certification reports

Example:

Frame 18231:
input.btn():12cycles

Although cheap, input is not free.

7 Button Mapping

7.1 Logical Identifiers

PROMETEU defines logical button identifiers:

• UP, DOWN, LEFT, RIGHT
• A, B, X, Y
• START, SELECT

The physical mapping:

• depends on the platform
• is resolved outside the VM
• is transparent to the program

7.2 Portability

The same PROMETEU cartridge:

• runs on a keyboard
• runs on a gamepad
• runs on touch

Without any code changes.

8 Analog Input (Optional)

PROMETEU can expose analog axes explicitly:

input.axis(id)

Characteristics:

• normalized value (e.g.: -1.0 to 1.0)
• explicit cost
• per-frame update

Analog input:

• is not mandatory
• does not replace digital input
• must be used consciously