Nexus Timer 🕰️✨

Nexus Timer is a dynamic multi-player timer designed for games, workshops, or any activity where turns pass sequentially. It focuses on the current participant and their immediate successor, ensuring everyone stays engaged and aware of who's next.

Table of Contents

1. Core Concept
2. Target Audience
3. Key Features at a Glance
4. Getting Started (User Guide)
5. Remote Control Options
6. Development, Deployment, and Architecture

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, perfect for board games, RPGs, 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.

Key Features at a Glance

• Dynamic Player Display: Clear focus on Current & Next player (Normal Mode) or a list of active timers (All Timers Mode).
• Individual Timers: Customizable (MM:SS), supports negative time, auto-skips players at max negative time.
• Two Game Modes:
  • Normal Mode: Only the current player's timer runs.
  • All Timers Mode: All active players' timers run simultaneously.
• Flexible Player Setup: Add, edit, delete, and reorder up to 99 players. Use camera for avatars or defaults.
• Intuitive Controls: Swipe up to pass turns, tap to pause/resume.
• Customizable Triggers:
  • Keyboard Hotkeys: Assign unique keys for player turns and global actions (Stop/Pause All, Run All Timers). This will allow the connected Bluetooth HID device to act like a remote buttons. See HID Smart Buttons
  • MQTT Remote Triggers: Assign unique characters for remote activation of player turns and global actions via an MQTT broker. This will allow the players use their own smartphone to remote control their timers. See Android Shortcut Setup
• PWA Ready: Installable on desktop and mobile, offline capable, with update notifications and screen wake lock.
• Audio & Visual Cues: Ticking sounds, alerts, light/dark themes, and clear timer states.
• Persistent Settings: Your setup and game state are saved locally.

Getting Started (User Guide)

This guide walks you through setting up and using Nexus Timer.

1. Installation (PWA)

Nexus Timer is a Progressive Web App (PWA), meaning you can install it on your device for a native-like experience.

• Mobile: Open Nexus Timer in a compatible browser (e.g., Chrome on Android, Safari on iOS). Look for an "Add to Home Screen" or "Install App" option in the browser menu.
• Desktop: In browsers like Chrome or Edge, look for an install icon in the address bar or an "Install App" option in the browser menu.

2. Initial Setup (First Use)

When you first open Nexus Timer (or after a full reset), it starts with two predefined players to get you going quickly.

• If you have at least two players defined (either predefined or previously saved), the app will automatically start in Normal Mode.
• If no players are defined, you'll be taken to the Setup Screen.

3. The Setup Screen

This is where you configure your game:

• Players Section:

  • View Players: Shows the current number of players (e.g., "Players (3)").
  • Add Player: Click to add a new player (up to 99). You can set their:
    • Name
    • Avatar: Use your device camera or a default icon.
    • Remaining Time: Set their starting timer (MM:SS). This can also be negative (e.g., -02:30).
    • "Pass Turn / My Pause" Hotkey: Click the display area (shows "-") and press a single keyboard key. This key will be used by this player to pass their turn (Normal Mode) or pause their own timer (All Timers Mode).
    • "Pass Turn / My Pause" MQTT Character: Click the display area (shows "-") and enter a single character. This character, when received via MQTT, will trigger the same action as the player's hotkey. (See Remote Control Options).
  • Edit Player: Click the pencil icon next to a player to modify their details.
  • Delete Player: Click the trash icon to remove a player.
  • Reorder Players: Use the up/down arrow icons to change player turn order.
  • Shuffle/Reverse Order: Buttons to quickly randomize or reverse the player list.

• MQTT Broker (for Remote Control):

  • URL: Enter the WebSocket URL of your MQTT broker (e.g., ws://your-broker-ip:9001).
  • Connect/Disconnect: Toggle the connection to your broker. The status (Connected, Disconnected, Error) will be displayed.

• Global Triggers (Hotkeys & MQTT):

  • Assign a unique keyboard Hotkey and/or a unique MQTT Character for:
    • Global "Stop/Pause All": Pauses the current player's timer (Normal Mode) or all running timers (All Timers Mode). If all are paused in All Timers Mode, this resumes them.
    • Global "Run All Timers": Switches from Normal Mode to All Timers Mode and starts all active player timers.
    • Global "Pass Turn": Passes the turn to the next player (works in both modes).
  • Click the display area (shows "-") next to "Hotkey" or "MQTT" to set the trigger.

• Other Settings:

  • Dark Mode: Toggle between light and dark themes.
  • Mute Audio: Turn all app sounds on or off.

• Action Buttons:

  • Save & Close: Saves your current setup and starts the game (if at least 2 players are configured), taking you to the Game View.
  • Reset Player Timers: Resets all current players' timers back to their initially set values and pauses the game. Player list and other settings remain.
  • Reset Entire App Data: Clears all data (players, settings, timer states) and resets the app to its default state (with 2 predefined players).

4. Game View: Playing the Game

Normal Mode (Default)

• Display: Shows the Current Player (top half) and Next Player (bottom half).
• Timer: Only the Current Player's timer runs.
  • Timers count down. If they reach 00:00, they continue into negative time (e.g., -00:01, -00:02...).
  • If a player reaches the maximum negative time (default -59:59), they are skipped automatically until their timer is edited or reset. Skipped players are visually distinct.
• Passing the Turn:
  1. Swipe Up on the Next Player's area (bottom half).
  2. Or, the Current Player presses their assigned "Pass Turn / My Pause" Hotkey or sends their MQTT Character.
  • Behavior: The current player's timer pauses, the next non-skipped player becomes "Current," and their timer starts.
  • Sound: A 3-second ticking sound alerts players when a new turn starts.
• Pausing/Resuming the Current Player's Timer (without passing):
  1. Tap on the Current Player's area (top half).
  2. Or, use the "Global Stop/Pause All" Hotkey or MQTT Character.
  • Behavior: If the current player's timer was paused when the turn was passed to them, it will remain paused. They need to tap their area or use a global resume trigger to start it.
• Switching to All Timers Mode: Click the "Run All Timers" button in the header.

All Timers Mode

• Display: Shows a list of all non-skipped players with their timers.
• Timers: All active (non-skipped) players' timers run simultaneously.
  • A continuous ticking sound plays while any timer is active in this mode.
• Entering this Mode:
  • Click "Run All Timers" in the Game View header (when in Normal Mode).
  • Or, use the "Global Run All Timers" Hotkey or MQTT Character.
  • All non-skipped players' timers will start.
• Pausing/Resuming Individual Timers:
  • Tap on a player in the list to pause/resume their specific timer.
  • A player can press their own "Pass Turn / My Pause" Hotkey or send their MQTT Character to pause their own timer.
• Visuals:
  • Players with running timers are clearly indicated (e.g., green/red border, pulsing background).
  • Players with paused timers are visually distinct (e.g., dimmer, yellowish border) but remain in the list.
• Global Pause/Resume:
  • The "Global Stop/Pause All" Hotkey or MQTT Character will:
    • Pause all currently running timers if any are active.
    • Resume all previously running (and still active, non-skipped) timers if all were paused.
• Reverting to Normal Mode:
  • Click "Back to Normal Mode" in the Game View header.
  • Automatically reverts if all player timers in this mode are paused (and at least one non-skipped player exists).
  • All timers will be paused when switching back to Normal Mode. The player who was "Current" before switching to All Timers mode (or the first player if starting fresh) will be the new Current Player.

5. Info Screen

• Accessible via the "Info" icon (ℹ️) in the Game View header.
• Displays "About" information, key features, and the app's build time.
• Includes a "Check for Update" button to manually trigger a PWA update check.
• Provides a link to the source code.

Remote Control Options

Nexus Timer supports remote control via physical HID buttons or MQTT messages. For detailed setup instructions, please see the Remote Control Options Guide.

Development, Deployment, and Architecture

Technology Stack

Nexus Timer is built using modern web technologies:

• Framework: Vue.js 3 with Composition API
• State Management: Vuex 4
• Routing: Vue Router 4
• Styling: Tailwind CSS with Typography plugin
• Build Tool: Vite
• Real-time Communication: MQTT (via mqtt.js)

Build and Development

The project uses Vite as its build tool, providing fast hot module replacement (HMR) during development.

# Install dependencies
npm install

# Run development server
npm run dev

For Developer Setup, see Developer Setup Guide.

For Deployment Setup, see Deployment Setup Guide.

For Architecture Docs, see Architecture.