# Interaction Pattern Library — IStalk

## Document Status

- **Version:** 1.0
- **Last Updated:** 2026-06-23
- **Covers:** MVP interaction patterns for Runner and Eye roles

---

## Pattern 1: Proximity Prompt (Runner)

**Used by:** Item pickup, shrine interaction, extraction altar

| Property | Value |
|----------|-------|
| Trigger | Runner enters trigger collider radius |
| Visual | Floating prompt above interactable: "[E] Pick Up" / "[E] Interact" |
| Activation | Press and release interact key (E default) |
| Feedback | Item disappears from world, weight meter updates, inventory strip adds icon |
| Cancel | Walk away from radius (prompt fades) |
| Edge case | Multiple interactables in range: show nearest, prioritize by distance |

### Accessibility Notes

- Prompt uses text label, not icon-only
- Prompt scales with UI Scale setting
- Key shown in prompt updates when remapped

---

## Pattern 2: Hold-to-Channel (Runner)

**Used by:** Extraction altar channeling

| Property | Value |
|----------|-------|
| Trigger | Press interact key while in extraction zone |
| Visual | Progress bar fills over channel duration (5s default) |
| Hold behavior | Hold interact key for full duration |
| Toggle option | If "Toggle Interact" enabled: press once to start, press again to cancel |
| Interrupt | Taking damage or leaving radius cancels channel |
| Feedback | Bar fills → completion flash → items extracted → weight reduced |
| Failure | Bar resets to 0, brief shake animation |

### Accessibility Notes

- Toggle option available for players who cannot hold keys
- Progress bar has percentage text overlay (not fill-only)
- Audio cue at 50% and 90% completion

---

## Pattern 3: Point-and-Click (Eye)

**Used by:** Laser targeting, camera pan

| Property | Value |
|----------|-------|
| Trigger | Mouse position on screen (always active) |
| Visual | Charge ring follows cursor, fills as charge builds |
| Activation | Click to fire laser at cursor position |
| Feedback | Brief telegraph line → beam fires → hit/miss result shown |
| Cooldown | Charge ring empties, refills over cooldown duration |
| Edge case | Clicking outside valid area: no response (no error sound) |

### Accessibility Notes

- Charge ring size adjustable (UI Scale)
- Mouse sensitivity affects pan speed, not targeting precision
- No rapid-click requirements (single deliberate shots)

---

## Pattern 4: Camera Navigation (Eye)

**Used by:** Eye 2D camera pan/zoom

| Property | Value |
|----------|-------|
| Pan | WASD or edge-of-screen cursor |
| Zoom | Scroll wheel (stepped) or +/- keys |
| Bounds | Camera cannot leave map boundaries |
| Speed | Pan speed increases at wider zoom levels |
| Edge scroll | Optional — can be disabled in settings |
| Reset | Double-click to re-center on a runner (if visible) |

### Accessibility Notes

- Edge scroll toggle in settings (some players find it disorienting)
- Zoom has defined min/max stops (not infinite)
- Pan speed slider available

---

## Pattern 5: Inventory Management (Runner)

**Used by:** Carried item display, item dropping

| Property | Value |
|----------|-------|
| Display | Horizontal strip of icons (max 4 slots visible) |
| Selection | No active selection needed — items are passive cargo |
| Drop | Press drop key (G default) to drop most recent item |
| Visual feedback | Icon slides out of strip, item appears at feet |
| Weight update | Weight meter decreases immediately |
| Constraint | Cannot drop during extraction channel |

### Accessibility Notes

- Items show name tooltip on hover (not icon-only identification)
- Drop key is remappable
- No drag-and-drop (pure keyboard/key-press interaction)

---

## Pattern 6: Lobby Interaction

**Used by:** Room creation, joining, role selection, ready state

| Property | Value |
|----------|-------|
| Navigation | Mouse click on UI buttons |
| Room creation | Single button press → room created, player is host |
| Joining | Click room in list → join as Runner (Eye role goes to host) |
| Ready | Toggle button — click to ready/unready |
| Start | Host-only button, enabled when all players ready |
| Feedback | Player list updates in real-time, role badges shown |

### Accessibility Notes

- All lobby actions are single-click (no drag, no hold)
- Text labels on all buttons (not icon-only)
- Keyboard navigation (Tab/Enter) for all lobby elements

---

## Global Patterns

### State Transitions

All state transitions (menu → lobby → game → results) use:
- Fade-to-black (0.3s) → load → fade-from-black (0.3s)
- No instant cuts between major states
- Loading indicator if transition exceeds 1s

### Error Communication

- Connection errors: top-of-screen banner (red background, white text, auto-dismiss 5s)
- Invalid actions: brief shake animation on the element + muted error sound
- Never modal popups for non-critical errors during gameplay

### Confirmation Pattern

Destructive actions (leave room, disconnect) require:
- Single confirmation dialog: "Leave room? [Yes] [No]"
- No triple-confirm or long holds for menu actions
- ESC always cancels/backs out
