Party Games

A local-first party game collection for a Windows laptop, a shared TV, and player phones on the same Wi-Fi. The host chooses a game from the desktop launcher. Players join the party once and remain connected when the host returns to the launcher.

Included games

• Letter Lounge — a creative category game for 2–12 players.
• Consensus — a social prediction game for 3–10 players about finding—and sometimes avoiding—the room's common answer.
• Agent Average — a sourced statistics and social-wagering game for 3–8 players, presented as an unnecessarily serious intelligence operation.

The platform owns room identity, QR joining, reconnection, the player roster, host authority, and active-game lifecycle. Each game owns its complete host, TV, and phone interface along with its rules, settings, state, theme, audio, and assets.

Development

1. Install Node.js 20 or newer.
2. Run npm install.
3. Run npm run dev.
4. Open http://localhost:5173/host for the launcher.
5. Join from a phone using the displayed QR code or open http://localhost:5173/play locally.

Portable Windows app

• npm run electron builds and launches the desktop application.
• npm run package:portable creates a no-install executable and copy-ready kit in portable-release, then retains only the newest semantic release version.
• npm run package:win is an alias for the portable build.

Download and extract Party Games <version> Kit.zip, then double-click Setup and Play Party Games.cmd. This is the only supported setup entry point. The first run asks where to keep the single contained voice folder, defaulting to Party Games Voice inside the extracted kit, and later launches remember that choice. Setup detects NVIDIA CUDA or officially supported AMD Radeon hardware, installs full Chatterbox when that path passes a real speech test, and otherwise falls back automatically to CPU Chatterbox Nano. Remove Party Games Voice.cmd safely removes the contained narrator and obsolete test installations. Node.js, npm, system Python, and the source directory are not required. Full details are in the included TTS_SETUP.md.

If phones cannot connect, allow Party Games through Windows Firewall, make sure every device is on the same non-guest Wi-Fi, and disable client/AP isolation on the router. VPN and virtual adapters are ignored automatically. For an unusual network, set PARTY_GAMES_HOST to the laptop's LAN IPv4 address before launching. The former LETTER_LOUNGE_HOST name remains supported for compatibility.

Dynamic commentary

Round and final score screens use game-specific scripted commentary with optional local-model enhancement. The server supplies only verified player names, answers, score changes, statistics, and standings. Letter Lounge and Consensus have large deterministic pools; Agent Average adds its dry intelligence-handler fallbacks and may use the configured local commentary service for additional variety. No internet connection is required.

The selected line has a stable event ID and is spoken once by the local Chatterbox narrator. During play, prompts, letters, target instructions, sourced Agent Average questions and results, finale prompts, and commentary containing live player names use the same cached narration path. Commentary audio is not pregenerated.

This computer's isolated Chatterbox installation is detected automatically and kept warm while Party Games is open. Selecting a game shows a brief loading screen only when the model is not ready. Current narration is generated first, and upcoming prompts are queued during gameplay. Temporary narration WAVs are cleared at new-game start and shortly after the final screen. CPU Chatterbox Nano is the final fallback when a GPU runtime is unavailable. See documentation/TTS_SETUP.md for installation paths, supported hardware, overrides, and cache behavior.

An experimental external text model remains available but is disabled by default. It is unnecessary for normal play. To opt into an Ollama or OpenAI-compatible endpoint:

• PARTY_GAMES_LLM_ENABLED=true enables external rewriting.
• PARTY_GAMES_LLM_URL changes the chat endpoint.
• PARTY_GAMES_LLM_MODEL changes the model name.
• PARTY_GAMES_LLM_API_KEY supplies a bearer token for a configured remote endpoint.
• PARTY_GAMES_LLM_TIMEOUT_MS changes the 2.2-second commentary deadline.

Using a remote endpoint intentionally sends the displayed player names, revealed answers, and score facts to that provider. It is not part of the normal narration system. Leave the feature disabled to keep commentary completely scripted and local.

Adding a game

1. Add a stable game ID and manifest to src/shared/catalog.ts.
2. Define the game’s client-state and action union in src/shared/types.ts.
3. Add a server adapter to server/game-registry.ts.
4. Implement an isolated server engine with cleanup-safe timers.
5. Implement complete host, TV, and phone surfaces with game-scoped styles and assets.
6. Add registry, rules, lifecycle, and multiplayer integration tests.

Game implementations should not depend on Letter Lounge components, phases, styling, settings, answers, or scoring concepts.

Verification

Run:

npm test
npm run typecheck
npm run build