# Input Peripheral (Input System)

Domain: virtual hardware: input
Function: normative

Didactic companion: [`../learn/input-mental-model.md`](../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