Skip to content

Player Screen Guide

Jump to bottom
chdvg edited this page May 20, 2026 · 1 revision

Player Screen Guide

The player screen runs at http://<server-ip>:3000/remote/player. Open it in any browser — phone, tablet, laptop, or a projector screen. No install required.

First Load — Tap Overlay

On first load, a full-screen tap overlay appears. This is required to unlock browser audio autoplay. Two options are presented:

Option Description
▶ Tap to Begin Guest / audio-unlock only. No login.
⚔ Login as Character Bind to a rostered player character.

Player Login

  1. Select your name from the Player dropdown (populated from seeds/players.json).
  2. Click Enter Session.

Your character name is bound to your browser tab. Login is persisted in sessionStorage so a page refresh silently re-binds without showing the tap overlay again.

Log Off

Click the ⚔ Log Off button in the bottom-left corner. This releases your character binding and returns to the tap overlay.

What Players See

Element Description
Scene image The map or image currently shown by the DM.
Fog of war Dark overlay on unrevealed cells. Tokens in fogged cells are hidden.
Token overlay Colored token markers for players, enemies, and items.
Popup overlays Initiative order, dice rolls, text, and images appear at the top-center as semi-transparent parchment panels.

Overlay Auto-Dismiss Timers

Overlay Dismisses after
Dice roll 8 seconds
Initiative 12 seconds
Text 15 seconds
Image 20 seconds

Token Movement

Logged-in players can drag their own token on the map:

  • Only the token whose label matches your player name is interactive; all other tokens are locked.
  • Supports mouse drag and touch drag (scroll is suppressed while dragging).
  • Drag sends a move-player-token WebSocket action; the server validates ownership before updating.
  • Movement is reflected in real time on every connected screen — other players and the DM map update simultaneously.

Movement Lock

The DM can lock individual players or all players at once. When locked, your token is not draggable and move attempts are silently dropped server-side.

Player Dice Roller

After logging in, a HUD bar appears at the bottom of the screen:

  • Buttons for d4, d6, d8, d10, d12, d20, d% (d100).
  • Rolling triggers a 3D dice animation on your screen.
  • The same anonymous roll animation plays on every other connected player screen simultaneously.
  • The DM sees a named entry in the 🎲 Player Rolls log: who rolled, which die, and the result — green for nat-20, red for nat-1.

Combat Targeting

Tap any mob token on your screen to set it as your combat target:

  • Tap the same token again to clear the target.
  • Your targeted token shows a pulsing red ring + 🎯 badge.
  • When the DM clicks Next Turn during your initiative turn, an attack animation automatically fires on your target.

Screen Controls

Button Location Effect
⛶ Fullscreen Corner Toggle fullscreen — useful for projectors to hide browser chrome.
🔄 Sync Top-right (below fullscreen) Send a full state sync request, or force-reconnect the WebSocket if the connection is down. Spins green briefly to confirm.

Projector / Guest Screen Resilience

The non-logged-in projector screen has hardened connection logic:

  • Max reconnect backoff: 3 seconds — the projector reconnects almost immediately after losing connection.
  • 35-second watchdog — detects zombie (dead but not closed) WebSocket connections and reconnects.
  • Tab wake — visibilitychange event triggers an instant request-sync when the projector tab comes back into focus after sleeping.
  • Network restore — online event reconnects immediately when the device regains network.
  • Tap overlay auto-dismiss — on page refresh, the guest tap overlay is automatically dismissed (stored in sessionStorage). The projector never needs a physical walk-over just to re-tap.

Overlay Popups

  • Dice rolls, initiative order, sent text, and sent images appear as semi-transparent parchment panels anchored to the top-center of the screen.
  • Attack animations and tokens remain visible beneath the overlay.
  • The DM can dismiss any open overlay with the 🧹 CLEAR button without disturbing the scene.

Clone this wiki locally