165 lines
2.7 KiB
Markdown
165 lines
2.7 KiB
Markdown
# 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
|