Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/docs/specs/hardware/topics/chapter-7.md

5.0 KiB
Raw Blame History

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