86 lines
6.3 KiB
Markdown
86 lines
6.3 KiB
Markdown
# Nexus Timer 🕰️✨
|
|
|
|
# Table of Contents
|
|
1. [Core Concept](#core-concept)
|
|
2. [Target Audience](#target-audience)
|
|
3. [Hardware Recommendations (Optional Enhancement)](#hardware-recommendations-optional-enhancement)
|
|
4. [Key Features](#key-features)
|
|
|
|
Nexus Timer is a dynamic multi-player timer designed for games, workshops, or any activity where turns pass sequentially in a circular fashion. It provides a clear visual focus on the current participant and their immediate successor, ensuring everyone stays engaged and aware of who is next. This document serves as a detailed specification for a Progressive Web App (PWA) prototype aimed at game enthusiasts.
|
|
|
|
## Core Concept
|
|
|
|
Nexus Timer visualizes players in a circular sequence. The **Current Player** is prominently displayed in the top half of the screen, and the **Next Player** is in the bottom half. This clear visual pairing indicates the flow of turns, making it perfect for board games, role-playing games, timed presentations, or any scenario needing structured turn management with individual countdowns.
|
|
|
|
## Target Audience
|
|
|
|
Game enthusiasts who play turn-based games (board games, tabletop RPGs, card games) and need a visually clear and customizable timer solution.
|
|
|
|
## Hardware Recommendations (Optional Enhancement)
|
|
|
|
For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on Bluetooth-connected microcontroller (e.g., XIAO nRF52840) implementing HID (Human Interface Device) protocol.
|
|
|
|
* **Buttons:** Connect 3 physical buttons, potentially extended (e.g., via 1.5m wires) for easy player access.
|
|
* **Configuration:**
|
|
* **Player 1's Button:** Single Click: Emulates a key press (e.g., 'a'). Configure this as Player 1's "Pass Turn / My Pause" hotkey in the app.
|
|
* **Player 2's Button:** Single Click: Emulates a key press (e.g., 'b'). Configure as Player 2's "Pass Turn / My Pause" hotkey.
|
|
* **Player 3's Button:** Single Click: Emulates a key press (e.g., 'c'). Configure as Player 3's "Pass Turn / My Pause" hotkey.
|
|
* **If Player 3 is Game Admin:**
|
|
* **Player 3's Button:** Long Press: Emulates a key press (e.g., 's'). Configure as the "Global Stop/Pause All" hotkey in the app.
|
|
* **Player 3's Button:** Double Click: Emulates a key press (e.g., 'x'). Configure as the "Global Run All Timers" hotkey in the app.
|
|
|
|
## Key Features
|
|
|
|
* **Circular Player Display:**
|
|
1. **Normal Mode (Default):** Central focus on the **Current Player** (top) and **Next Player** (bottom).
|
|
2. **All Timers Running Mode:** List of players with running timers.
|
|
* **Individual Player Timers:**
|
|
* Customizable countdown timer (MM:SS) for each player.
|
|
* Timers continue into **negative time** (e.g., -MM:SS) up to a limit (e.g., -59:59).
|
|
* Players reaching max negative time are **skipped** until reset or timer edit.
|
|
* Visual feedback: Pulsating effect for active timers (background for positive, text for negative). Skipped players are visually distinct (e.g., greyed out).
|
|
* **Two Game Modes:**
|
|
1. **Normal Mode (Default):**
|
|
* Only the **Current Player's** timer runs.
|
|
* Pass the turn via **Swipe Up** on the Next Player's area or the Current Player's "Pass Turn / My Pause" hotkey.
|
|
* 3-seconds ticking sound when the timer starts to alert players about the "Pass Turn".
|
|
* Tap Current Player's area or use "Global Stop/Pause All" hotkey to pause/resume their timer without passing the turn.
|
|
* To pass the turn: **Swipe Up** on the Next Player's area or have the Current Player press their "Pass Turn / My Pause" hotkey. The current timer pauses, the next player becomes Current, and their timer starts.
|
|
* If the current player's timer is paused, and then the turn is passed (via swipe up or hotkey), the next player should become the current player, but their timer should not automatically start. It should remain paused.
|
|
2. **All Timers Running Mode:**
|
|
* All active player timers run simultaneously.
|
|
* Enter by clicking "All Timers Mode" (starts all timers).
|
|
* Continuous ticking sound when active.
|
|
* Initially, all players are shown in a list with their photo, name and timer value.
|
|
* Tapping on a player in the list pauses its timer. Any player can use their "Pass Turn / My Pause" hotkey to pause their *own* timer.
|
|
* Only players with a running timer are shown in the list.
|
|
* If all players pause their timers, automatically reverts to Normal Mode.
|
|
* Main button: "Stop All Timers" (pauses all, returns to Normal Mode) or "Start All Timers" (resumes all in this mode). Can also be triggered by "Global Stop/Pause All" hotkey.
|
|
* **Player Management:**
|
|
* Add, edit, and delete players.
|
|
* Use device camera (access via browser API) or default avatars for the player's picture.
|
|
* Set initial timer values per player (Default: 60:00).
|
|
* Assign unique "Pass Turn / My Pause" hotkeys (single keypresses). E.g.: Use the Player's 1 "single click" action to insert the key.
|
|
* Assign the "Global Stop/Pause All" hotkey (single keypresses). E.g.: Use the Player's 3 "long press" action to insert the key.
|
|
* Assign the "Run All Timers" hotkey (single keypresses). E.g.: Use the Player's 3 "double click" action to insert the key.
|
|
* Re-order players, reverse, shuffle.
|
|
* **Intuitive Controls:**
|
|
* **Swipe Up:** (On the Next Player's area). Primary gesture for passing turns (Normal Mode).
|
|
* **On-Screen Taps:** (On the Current Player's area). For pausing/resuming timers contextually.
|
|
* **Audio Feedback:**
|
|
* Continuous ticking in "All Timers Running Mode" when active.
|
|
* Brief 3-second tick when a timer starts in Normal Mode. Cancel the sound when the timer pauses.
|
|
* Global mute option.
|
|
* **Visuals:**
|
|
* Designed for mobile phone screens (portrait orientation).
|
|
* Light/Dark theme options.
|
|
* **Persistence:** Player setups, timer states, and settings are saved locally using browser Local Storage.
|
|
* **Global Reset:** "Reset Game" button restores all timers to initial values and resets game state.
|
|
|
|
### For Developer Setup, see [Developer Setup Guide](docs/development.md).
|
|
### For Deployment Setup, see [Deployment Setup Guide](docs/deployment.md).
|
|
### For Architecture Docs, see [Architecture](docs/architecture.md).
|
|
|
|
|
|
|