prometeu-runtime/docs/specs/runtime/07-touch-peripheral.md

Touch Peripheral (Absolute Pointer Input System)

Domain: virtual hardware: touch Function: normative

Didactic companion: ../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: 320×180
• Origin: top-left corner (0,0)
• Ranges:
  • x ∈ [0, 319]
  • y ∈ [0, 179]

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:
  present   : bool
  down      : bool
  pressed   : bool
  released  : bool
  x         : int
  y         : int

3.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

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