Nexus Timer 🕰️✨

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.

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 (their immediate successor) is in the bottom half. This clear visual pairing indicates the flow of turns, making it perfect for board games, round-robin discussions, timed presentations, or any scenario needing structured turn management with individual countdowns.

Hardware Recommendations (Optional Enhancement)

For an enhanced tactile experience, Nexus Timer supports a 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 (Example):
  • 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.
    • Long Press (if Player 3 is Game Admin): Emulates a key press (e.g., 's'). Configure as the "Global Stop/Pause All" hotkey in the app.

Key Features ✨

• Circular Player Display:
  • Central focus on the Current Player (top) and Next Player (bottom).
• 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 or the Current Player's "Pass Turn / My Pause" hotkey.
     • Tap Current Player's area or use "Global Stop/Pause All" hotkey to pause/resume their timer without passing the turn.
  2. All Timers Running Mode:
     • All active player timers run simultaneously.
     • Enter by clicking "All Timers Mode" (starts all timers).
     • App-wide visual pulsing and continuous ticking sound when active.
     • Swipe Up to change which active player is "in focus" in the Current Player display.
     • Focused player can tap their area to pause their own timer. Any player can use their "Pass Turn / My Pause" hotkey to pause their own timer.
     • 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 (2-10 players).
  • Upload photos, use device camera, or default avatars.
  • Set initial timer values per player (Default: 60:00).
  • Assign unique "Pass Turn / My Pause" hotkeys.
  • Optionally designate one player as "Game Admin" for special hotkey functions.
  • Easily re-order (drag-and-drop planned), reverse, or shuffle player order.
• Intuitive Controls:
  • Swipe Up: (On the Next Player's area). Primary gesture for passing turns (Normal Mode) or changing focus (All Timers 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.
• Persistence: Player setups, timer states, and settings are saved locally.
• Global Reset: "Reset Game" button restores all timers to initial values and resets game state.

Tech Stack (Planned/Example)

• Progressive Web App (PWA) for smartphone screens.
• Modular codebase.
• Simple sounds using pure Web Audio API.
• CSS for styling, animations, and placeholder avatars.
• Local Storage/IndexedDB for persistence.

Getting Started

(Details to be added once development begins)

1. Prerequisites:
   • A modern web browser on a smartphone or tablet.
   • (Optional) Bluetooth-enabled microcontroller for hardware buttons.
2. Installation:

   # Placeholder for PWA installation instructions or link
   

3. Running the Application:

   # Placeholder for how to access/run the app
   

Usage Guide

1. Manage Players:
   • Tap "Manage Players."
   • Add players: Enter name, set initial timer. Optionally, add a photo, assign a "Pass Turn / My Pause" hotkey, and designate an admin.
   • Edit existing players or change their order.
   • Save changes.
2. Main Screen:
   • The Current Player appears in the top half, Next Player in the bottom. Effective use of the phone's screen. No additional elements like header or footer.
3. Normal Mode (Default):
   • Tap the Current Player's area to start/pause their timer.
   • 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.
   • Click the "All Timers Mode" button to switch modes (this will also start all timers).
4. All Timers Running Mode:
   • All active player timers run. The app background pulses, and a ticking sound plays (if unmuted).
   • The "Current Player" area shows one of the players with an active timer. Swipe Up to cycle focus to other players with active timers.
   • A player can pause their own timer by:
     • Tapping their display area (if they are the focused Current Player).
     • Pressing their "Pass Turn / My Pause" hotkey.
   • If all players pause their timers, the app reverts to Normal Mode.
   • The main control button will say "Stop All Timers." Clicking it (or using the "Global Stop/Pause All" hotkey) pauses all timers and returns to Normal Mode. If all timers are already paused in this mode, it says "Start All Timers."
5. Reset Game:
   • Tap "Reset Game" and confirm to restore all timers to their initial values.

Configuration

• Player Hotkeys (in "Manage Players"):
  • "Pass Turn / My Pause" Key:
    • Normal Mode: If pressed by Current Player, passes the turn.
    • All Timers Mode: Pauses/resumes the respective player's own timer.
• Global Hotkeys (configured in settings or player management for admin):
  • "Global Stop/Pause All" Hotkey:
    • Normal Mode: Pauses the Current Player's timer.
    • All Timers Mode (timers running): Pauses all timers and returns to Normal Mode.
    • All Timers Mode (all timers paused): Resumes all timers in All Timers Mode.
• Audio Mute: Look for a mute/unmute icon or setting.

Future Enhancements 🚀

• Light/Dark theme options.
• Game statistics (e.g., average turn time).