128 lines
3.4 KiB
Markdown
128 lines
3.4 KiB
Markdown
# Input Peripheral (VM-Owned Snapshot Input)
|
|
|
|
Domain: virtual hardware: input
|
|
Function: normative
|
|
|
|
Didactic companion: [`../learn/mental-model-input.md`](../runtime/learn/mental-model-input.md)
|
|
|
|
## 1 Scope
|
|
|
|
This chapter defines the runtime-facing input contract of PROMETEU.
|
|
|
|
Core contract:
|
|
|
|
- input is exposed as VM-owned snapshot state;
|
|
- sampling happens at a deterministic point of each logical frame;
|
|
- queries are deterministic inside the same frame;
|
|
- input access uses VM-owned intrinsics (not host syscalls in v1).
|
|
|
|
## 2 Devices and Surface
|
|
|
|
For v1, the input domain includes:
|
|
|
|
- `pad`
|
|
- `touch`
|
|
- `button` (as a nested state surface used by `pad` and `touch`)
|
|
|
|
No analog axis is part of the v1 input contract.
|
|
|
|
## 3 Frame Sampling Model
|
|
|
|
Input state is captured at the beginning of each logical frame, before update logic runs.
|
|
|
|
Conceptual flow:
|
|
|
|
```text
|
|
FRAME N:
|
|
SAMPLE_INPUT
|
|
UPDATE
|
|
DRAW
|
|
AUDIO
|
|
SYNC
|
|
```
|
|
|
|
Within the same frame:
|
|
|
|
- input state is immutable;
|
|
- repeated reads return the same values.
|
|
|
|
## 4 State Semantics
|
|
|
|
`button` exposes:
|
|
|
|
- `pressed: bool` (true only on transition up -> down in this frame)
|
|
- `released: bool` (true only on transition down -> up in this frame)
|
|
- `down: bool` (true while physically pressed in this frame snapshot)
|
|
- `hold: int` (count of consecutive pressed frames)
|
|
|
|
`pad` is a fixed set of buttons:
|
|
|
|
- `up`, `down`, `left`, `right`
|
|
- `a`, `b`, `x`, `y`
|
|
- `l`, `r`, `start`, `select`
|
|
|
|
`touch` exposes:
|
|
|
|
- `x: int`
|
|
- `y: int`
|
|
- `button` with the same `pressed/released/down/hold` semantics
|
|
|
|
PROMETEU handheld v1 uses single-touch active pointer semantics.
|
|
|
|
## 5 Access Model
|
|
|
|
Input is VM-owned in v1:
|
|
|
|
- frontend surfaces may be ergonomic and language-specific;
|
|
- lowering maps to VM-owned `INTRINSIC <id_final>`;
|
|
- no input syscall is required in the host ABI path.
|
|
|
|
Illustrative (language-level) shape:
|
|
|
|
```text
|
|
Input.pad().up().hold()
|
|
Input.touch().x()
|
|
```
|
|
|
|
The normative contract is intrinsic identity/version and semantics, not source syntax.
|
|
|
|
## 6 Determinism and Replay
|
|
|
|
Given the same per-frame input snapshots, execution must produce the same observable results.
|
|
|
|
This enables:
|
|
|
|
- deterministic replay;
|
|
- deterministic certification analysis;
|
|
- controlled input injection in tests/tooling.
|
|
|
|
## 7 Capability and Certification
|
|
|
|
Input reads are not capability-gated by syscall capability policy in v1.
|
|
|
|
Input access is VM-owned and should not be reported as host syscall consumption.
|
|
|
|
## 8 Portability
|
|
|
|
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
|
|
|
|
Platform differences in physical device mapping are resolved outside VM semantics.
|
|
|
|
## 9 Host/System Controls
|
|
|
|
Host/System controls are not part of the guest-visible input surface.
|
|
|
|
The Home/SystemOS request changes machine foreground authority. It must be
|
|
handled by the host, firmware, or SystemOS before input is exposed to the Game.
|
|
It must not be represented as `pad.start`, `pad.select`, a new pad field, a VM
|
|
intrinsic, or a userland syscall.
|
|
|
|
For the desktop host, `Esc` is the primary keyboard mapping for the
|
|
Home/SystemOS request. The physical `Home` key may be supported as an alias.
|
|
Both mappings are host controls and must not mutate `InputSignals`.
|
|
|
|
When a Game leaves or re-enters foreground, pending Game input must be cleared
|
|
or barriered so held or pressed input cannot leak across pause/resume
|
|
boundaries. This barrier applies to the Game-facing snapshot; it does not
|
|
change the meaning of host/system Home controls.
|