Time Auction

Time Auction is a real-time party game for groups that challenges players to manage a shared "time bank" across a series of hold-to-win rounds. It is built with Node.js, Express, and Socket.IO, with lightweight static UIs for hosts and players.

How a Match Works

1. Lobby & Setup – The host starts the server, opens the /host dashboard, and shares the player join link or QR code that is generated from the server's LAN address.【F:server.js†L392-L396】【F:public/host.html†L40-L48】
2. Join & PINs – Players join from /player, enter a display name, and automatically receive a unique PIN that can be used later to reconnect if they disconnect.【F:public/player.html†L95-L142】【F:server.js†L588-L629】
3. Game Start – When the host chooses the number of rounds and per-player time bank minutes, the server resets everyone’s clock, generates a session code, and broadcasts the match rules to every client.【F:server.js†L343-L355】【F:server.js†L495-L520】
4. Round Loop – Each round advances through three synced phases:
   • Arming – Everyone presses and holds to signal readiness; the server waits until all required participants are holding before moving on.【F:server.js†L230-L247】【F:public/player.js†L213-L241】
   • Countdown – A fixed countdown (default 5s) warns players that releasing early will knock them out for the round.【F:server.js†L246-L255】【F:public/player.js†L277-L319】
   • Active Hold – Once the countdown completes, the clock starts draining each participant’s personal time bank until they release or run out, automatically tracking “auto-exhausted” players.【F:server.js†L273-L302】【F:public/player.js†L262-L275】
5. Scoring – The player who held the longest that round wins the victory tokens for that round. Rounds can optionally include bonus multipliers or a configurable final-round boost.【F:server.js†L303-L341】【F:server.js†L43-L65】
6. Game End – After the last round, the server announces the champion, lists eliminated players (lowest token count), and shares a final ranked table to all clients.【F:server.js†L326-L341】

Core Mechanics

• Time Bank Management – Each player begins with the full time bank selected by the host. Holding during an active round spends from that personal reserve, and hitting zero marks the player exhausted for the rest of the match.【F:server.js†L343-L355】【F:server.js†L256-L299】
• Victory Tokens & Ranking – Tokens accumulate per round; the scoreboard breaks ties by remaining time bank, rounds active, and recency of wins to produce consistent ranks.【F:server.js†L303-L341】【F:server.js†L116-L163】
• Bonus Systems – Hosts can enable scheduled bonus rounds, a final-round multiplier, streak rewards, and comeback assistance, all of which are pushed live to players.【F:server.js†L43-L65】【F:server.js†L479-L583】
• Automatic CSV Exports – The host dashboard exposes quick downloads for round history and the current scoreboard in CSV format for post-game analysis.【F:server.js†L373-L390】【F:public/host.html†L81-L102】

Host Experience

The host dashboard provides everything needed to run the match:

• Game Controls – Start/stop the match, begin/end rounds, and see a live phase and timer readout.【F:public/host.html†L51-L78】
• Lobby Management – Rename or remove players, clean up “ghost” connections, and toggle host/public scoreboards.【F:public/host.html†L81-L102】【F:server.js†L437-L478】
• Live Insights – Watch active hold progress bars, round history, and optional detailed scoreboards that include remaining time bank per player.【F:server.js†L185-L220】【F:public/host.html†L65-L102】
• Advanced Settings – Apply bonus rules, streak caps, comeback tokens, and cosmetic themes without restarting the session; acknowledgements appear as toasts in the UI.【F:public/host.html†L107-L153】【F:server.js†L479-L583】

Player Experience

Players interact through a touch-friendly layout focused on the hold mechanic:

• Join & Reconnect – Enter a name or supply a PIN to reclaim an existing seat, with the interface showing the assigned PIN for safe keeping.【F:public/player.html†L95-L142】
• Hold Button – A large central button changes states for idle, pressed, disabled, and bonus rounds, while the phase badge communicates whether players are arming, counting down, active, or exhausted.【F:public/player.html†L121-L141】【F:public/player.html†L33-L41】
• Round Feedback – Players see live timers, round results, exhaustion notices, optional public scoreboard tables, and an end-game modal summarizing rankings and the champion.【F:public/player.html†L128-L159】
• Accessibility – Visual countdown overlays, vibration hooks, and notification prompts keep mobile participants in sync even when the app is backgrounded.【F:public/player.js†L40-L115】【F:public/player.js†L213-L275】

Technology & Architecture

• Server – A single Express app serves static host/player pages and manages all game state in memory. Socket.IO channels synchronize timers, round transitions, and score updates in real time.【F:server.js†L11-L220】【F:server.js†L230-L341】
• Client Bundles – Static HTML/CSS/JS files under public/ provide the host and player UIs, avoiding build tooling while still offering responsive layouts.【F:public/host.html†L1-L155】【F:public/player.html†L1-L170】
• Utilities – The server generates LAN-aware join URLs, QR codes, and unique player PINs to streamline onboarding in local network settings.【F:server.js†L24-L41】【F:server.js†L392-L426】

Running Locally

1. Install Node.js 18 or later (the project declares an engines requirement).【F:package.json†L6-L11】
2. Install dependencies and start the server:

   npm install
   npm start

   The game runs on port 3000 by default and logs the host URL on startup.【F:package.json†L6-L8】【F:server.js†L19-L19】【F:server.js†L693-L693】
3. Open the host dashboard at http://localhost:3000/host, share the player link, and begin the auction.

Repository Structure

• server.js – Core game logic, routing, and Socket.IO coordination.【F:server.js†L11-L693】
• public/host.html & public/host.js – Host UI and controls.【F:public/host.html†L1-L155】【F:public/host.js†L1-L211】
• public/player.html & public/player.js – Player UI and hold interaction logic.【F:public/player.html†L1-L170】【F:public/player.js†L1-L319】
• package.json – Metadata and start script.

Enjoy hosting your own local Time Auction sessions!

Launching the game

Run the bundled launch script to install dependencies, start the server, and open the game in your default browser:

npm run launch

Set TIME_AUCTION_URL if you want the browser to open a different base URL (defaults to http://localhost:3000).

On Windows, you can also double-click launch-all.bat (or run it from a Command Prompt) to accomplish the same workflow. The batch file installs dependencies if needed, launches the server in a new window, and opens the host dashboard in your default browser. Set TIME_AUCTION_URL beforehand to override the default browser URL.