# Touch Peripheral (Absolute Pointer Input System) Domain: virtual hardware: touch Function: normative Didactic companion: [`../learn/mental-model-touch.md`](../runtime/learn/mental-model-touch.md) ## 1 Scope This chapter defines the runtime-facing TOUCH contract of PROMETEU. Core contract: - one absolute pointer at a time; - framebuffer-aligned coordinates; - per-frame state exposure; - no gesture semantics; - no acceleration or smoothing semantics. ## 2 Coordinate Space - TOUCH coordinates use **the same space as the framebuffer** - Resolution: **480×270** - Origin: top-left corner `(0,0)` - Ranges: - `x ∈ [0, 479]` - `y ∈ [0, 269]` TOUCH is **absolute**: - `(x, y)` represents the current contact position after normalization; - the runtime does not apply dynamic transformation to that coordinate pair. ## 3 TOUCH Peripheral API ### 3.1 Exposed Structure ``` TOUCH: down : bool pressed : bool released : bool hold : Int64 x : Int64 y : Int64 ``` ### 3.2 Field Semantics - **availability** - is not a guest field or endpoint value - a known query without a platform source raises `TRAP_UNAVAILABLE` - **down** - `true` while the active pointer is pressed - **pressed** - `true` only in the frame where the active pointer was captured - **released** - `true` only in the frame where the active pointer was released - **x, y** - current position of the active pointer - valid only when `down == true` ## 4 Pointer Selection Policy ### *Single Pointer Capture Policy* When multiple physical touches occur, PROMETEU applies the following policy: ### 4.1 Initial Capture 1. If **no pointer is active** 2. And a **new physical touch** occurs 3. The **first detected touch** is captured 4. This touch becomes the **active pointer** This frame generates: - `pressed = true` - `down = true` ### 4.2 Capture Maintenance While the active pointer is pressed: - Only it is tracked - All other physical touches are ignored - `x, y` follow only the active pointer ### 4.3 Release When the active pointer is released: - `released = true` - `down = false` - The system enters a **no active pointer** state ### 4.4 Recapture After release: - Touches that **were already present** are ignored - A new pointer is only captured with a **new touch event** ## 5 Deliberately Unsupported Behaviors The TOUCH peripheral **does not implement**: ❌ Multitouch ❌ Gestures (swipe, pinch, rotate, long-press) ❌ Acceleration or smoothing ❌ Dynamic sensitivity ❌ Implicit history ❌ Intent interpretation If a game wants any of these behaviors, it must: - implement them explicitly - using only per-frame state - without implicit hardware support ## 6 “No Gesture” — Formal Definition PROMETEU **does not interpret temporal patterns**. The TOUCH peripheral **does not classify actions** as: - swipe - drag - long press - double tap It only reports: - current position - contact state All semantics are the game's responsibility. ## 7 “No Acceleration” — Formal Definition PROMETEU **does not modify** the TOUCH input. - No sensitivity curves - No speed-based amplification - No smoothing The relationship between the physical touch and `(x, y)` is **1:1** after normalization. ## 8 Integration with Other Input Forms - Desktop: - mouse can emulate TOUCH - Mobile: - direct physical touch - Steam Deck: - physical touchscreen - PROMETEU Hardware: - optional touch, but supported ## 9 Portability Guarantees Every PROMETEU game that uses TOUCH: - behaves identically on all platforms - does not depend on host-specific capabilities - does not suffer semantic variation between desktop, mobile, and dedicated hardware ## Fixed query catalogue Touch button queries occupy 0x2130–0x2133 (pressed/released/down/hold); x/y use 0x2134/0x2135. All have zero arguments and read the frame snapshot. Button states return Bool; hold and coordinates return Int64. See the [complete input contract](02c-program-registry-and-pbx-v0.md#input).