implemented intrinsecs de input and specs adjustment

This commit is contained in:
2026-03-24 13:40:48 +00:00
parent 1bd921979f
commit 10dfc7bf15
17 changed files with 957 additions and 1089 deletions
+57 -112
View File
@@ -1,6 +1,6 @@
# Input Peripheral (Input System)
# Input Peripheral (VM-Owned Snapshot Input)
Domain: virtual hardware: input
Domain: virtual hardware: input
Function: normative
Didactic companion: [`../learn/input-mental-model.md`](../learn/input-mental-model.md)
@@ -11,154 +11,99 @@ 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.
- 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 Input Devices
## 2 Devices and Surface
PROMETEU abstracts different devices into a common interface.
For v1, the input domain includes:
Typical devices:
- `pad`
- `touch`
- `button` (as a nested state surface used by `pad` and `touch`)
- digital control (D-Pad + botões)
- keyboard (mapped to buttons)
- gamepad
- touch (mobile, mapped)
No analog axis is part of the v1 input contract.
Regardless of source, PROMETEU exposes the same logical model.
## 3 Frame Sampling 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.
Input state is captured at the beginning of each logical frame, before update logic runs.
Conceptual flow:
```
```text
FRAME N:
SAMPLEINPUT
SAMPLE_INPUT
UPDATE
DRAW
AUDIO
SYNC
```
Throughout the entire frame:
Within the same frame:
- the input state is immutable
- repeated calls return the same value
- input state is immutable;
- repeated reads return the same values.
## 5 Determinism and Reproducibility
## 4 State Semantics
The PROMETEU input model guarantees:
`button` exposes:
- same sequence of inputs
- same frames
- same results
- `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)
This allows:
`pad` is a fixed set of buttons:
- execution playback
- deterministic replays
- reliable certification
- `up`, `down`, `left`, `right`
- `a`, `b`, `x`, `y`
- `l`, `r`, `start`, `select`
Input can be:
`touch` exposes:
- recorded
- played back
- artificially injected
- `x: int`
- `y: int`
- `button` with the same `pressed/released/down/hold` semantics
## 6 Input and CAP
PROMETEU handheld v1 uses single-touch active pointer semantics.
Input operations:
## 5 Access Model
- consume few cycles
- participate in the per-frame budget
- appear in certification reports
Input is VM-owned in v1:
Example:
- 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.
```
Frame 18231:
input.btn():12cycles
Illustrative (language-level) shape:
```text
Input.pad().up().hold()
Input.touch().x()
```
Although cheap, input **is not free**.
The normative contract is intrinsic identity/version and semantics, not source syntax.
## 7 Button Mapping
## 6 Determinism and Replay
### 7.1 Logical Identifiers
Given the same per-frame input snapshots, execution must produce the same observable results.
PROMETEU defines logical button identifiers:
This enables:
- `UP`, `DOWN`, `LEFT`, `RIGHT`
- `A`, `B`, `X`, `Y`
- `START`, `SELECT`
- deterministic replay;
- deterministic certification analysis;
- controlled input injection in tests/tooling.
The physical mapping:
## 7 Capability and Certification
- depends on the platform
- is resolved outside the VM
- is transparent to the program
Input reads are not capability-gated by syscall capability policy in v1.
### 7.2 Portability
Input access is VM-owned and should not be reported as host syscall consumption.
The same PROMETEU cartridge:
## 8 Portability
- runs on a keyboard
- runs on a gamepad
- runs on touch
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
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
Platform differences in physical device mapping are resolved outside VM semantics.
@@ -37,7 +37,6 @@ Example:
```
("gfx", "present", 1)
("input", "state", 1)
("audio", "play", 2)
```
@@ -47,6 +46,8 @@ This identity is:
- toolchain-stable;
- used for linking and capability gating.
Input queries are VM-owned intrinsic calls in v1 and are outside the syscall identity space.
## 3 Syscall Resolution
The host maintains a registry:
+2 -1
View File
@@ -41,12 +41,13 @@ Example groups:
- `gfx`
- `audio`
- `input`
- `asset`
- `memcard`
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
## 3 Interaction with the Garbage Collector
The VM heap and host-managed memory are separate.