prometeu-runtime/docs/specs/hardware/topics/chapter-7.md

< Back | Summary | Next >

🖐️ 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 | Summary | Next >