262 lines
5.0 KiB
Markdown
262 lines
5.0 KiB
Markdown
< [Back](chapter-6.md) | [Summary](table-of-contents.md) | [Next](chapter-8.md) >
|
||
|
||
# 🖐️ TOUCH Peripheral (Absolute Pointer Input System)
|
||
|
||
## 1. Overview
|
||
|
||
The **TOUCH** peripheral provides PROMETEU with an **absolute pointer**, based on screen coordinates, intended for:
|
||
|
||
- UI interaction
|
||
- direct element selection
|
||
- contextual actions in the scenery
|
||
- drag-based mechanics (drag, slash, trail)
|
||
|
||
The TOUCH is a **first-class peripheral**, as valid as D-Pad and buttons.
|
||
|
||
---
|
||
|
||
## 2. Design Principles
|
||
|
||
TOUCH in PROMETEU follows strict principles:
|
||
|
||
- ✅ **Universal single-touch**
|
||
- ✅ **Deterministic**
|
||
- ✅ **Per-frame state**
|
||
- ✅ **No gestures**
|
||
- ✅ **No acceleration**
|
||
- ✅ **No heuristics**
|
||
- ✅ **Same behavior on all platforms**
|
||
|
||
> If a behavior cannot be guaranteed on all platforms, it does not exist in PROMETEU.
|
||
>
|
||
|
||
---
|
||
|
||
## 3. Conceptual Model
|
||
|
||
PROMETEU exposes **only one active pointer at a time**, regardless of how many physical touches the hardware recognizes.
|
||
|
||
- Hardware may detect multitouch
|
||
- Runtime selects **only one active touch**
|
||
- The API **never exposes multitouch**
|
||
|
||
This model guarantees:
|
||
|
||
- total portability
|
||
- predictability
|
||
- absence of ambiguities
|
||
|
||
---
|
||
|
||
## 4. Coordinate Space
|
||
|
||
- TOUCH coordinates use **the same space as the framebuffer**
|
||
- Resolution: **320×180**
|
||
- Origin: top-left corner `(0,0)`
|
||
- Ranges:
|
||
- `x ∈ [0, 319]`
|
||
- `y ∈ [0, 179]`
|
||
|
||
TOUCH is **absolute**:
|
||
|
||
> (x, y) represents the exact position of contact, without dynamic transformation.
|
||
>
|
||
|
||
---
|
||
|
||
## 5. TOUCH Peripheral API
|
||
|
||
### 5.1 Exposed Structure
|
||
|
||
```
|
||
TOUCH:
|
||
present : bool
|
||
down : bool
|
||
pressed : bool
|
||
released : bool
|
||
x : int
|
||
y : int
|
||
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 Field Semantics
|
||
|
||
- **present**
|
||
- `true` if the TOUCH peripheral is available
|
||
- `false` if there is no physical touch (desktop, hardware without touch)
|
||
- **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`
|
||
|
||
---
|
||
|
||
## 6. Pointer Selection Policy
|
||
|
||
### *Single Pointer Capture Policy*
|
||
|
||
When multiple physical touches occur, PROMETEU applies the following policy:
|
||
|
||
---
|
||
|
||
### 6.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`
|
||
|
||
---
|
||
|
||
### 6.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
|
||
|
||
---
|
||
|
||
### 6.3 Release
|
||
|
||
When the active pointer is released:
|
||
|
||
- `released = true`
|
||
- `down = false`
|
||
- The system enters a **no active pointer** state
|
||
|
||
---
|
||
|
||
### 6.4 Recapture (Important Rule)
|
||
|
||
After release:
|
||
|
||
- Touches that **were already present** are ignored
|
||
- A new pointer is only captured with a **new touch event**
|
||
|
||
> This avoids unexpected pointer jumps and accidental actions.
|
||
>
|
||
|
||
---
|
||
|
||
## 7. Deliberately NOT Supported 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
|
||
|
||
---
|
||
|
||
## 8. “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.
|
||
|
||
---
|
||
|
||
## 9. “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.
|
||
|
||
---
|
||
|
||
## 10. Integration with Other Input Forms
|
||
|
||
- Desktop:
|
||
- mouse can emulate TOUCH
|
||
- Mobile:
|
||
- direct physical touch
|
||
- Steam Deck:
|
||
- physical touchscreen
|
||
- PROMETEU Hardware:
|
||
- optional touch, but supported
|
||
|
||
From PROMETEU's point of view:
|
||
|
||
> TOUCH is always TOUCH.
|
||
>
|
||
|
||
---
|
||
|
||
## 11. Expected Uses
|
||
|
||
The TOUCH peripheral is suitable for:
|
||
|
||
- UI (menus, inventory, maps)
|
||
- drag-and-drop
|
||
- direct selection
|
||
- “click to investigate”
|
||
- pointing-based puzzles
|
||
- trail mechanics (e.g.: Fruit Ninja-like)
|
||
|
||
---
|
||
|
||
## 12. 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
|
||
|
||
---
|
||
|
||
## 13. Summary
|
||
|
||
The TOUCH in PROMETEU is:
|
||
|
||
- simple
|
||
- explicit
|
||
- predictable
|
||
- universal
|
||
- deterministic
|
||
|
||
< [Back](chapter-6.md) | [Summary](table-of-contents.md) | [Next](chapter-8.md) > |