Headgame

A mobile-first heads-up guessing game built with four decks:

How to play	Gameplay	Where to play

• Events: history/current event cards with hints.
• Friends: add friend names, then guess who is on the card.
• People: pop culture, sports, music, creator, and public figure cards.
• Memes: Automatic meme mode from KnowYourMeme

The front screen offers two play styles:

• Ask yes/no questions: the guesser can ask yes-or-no questions.
• Charades: players act out the answer, and nobody can talk.

Event and people decks default to custom-only cards. Switch the deck source to Wikipedia to generate a random round from Wikipedia summaries and images. Wikipedia rounds can be scoped by period: Mixed, Recent, 2000s, 1900s, or Historical.

Custom event and people cards can include temporary images:

• Upload: stored in browser memory and synced through the temporary room state.
• Search: pulls image URLs from Wikimedia Commons through /api/images/search.

Run

npm start

Open the local URL printed by the server:

http://localhost:5173

For phone multiplayer, keep every phone on the same Wi-Fi/network and open one of the printed Phone URL addresses. The host creates a room, shares the code or link, and other players join from their phones.

Docker

Copy this into a docker-compose.yml file:

services:
  headgame:
    image: ghcr.io/ad-archer/headgame:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      PORT: 3000

Then run:

docker compose up -d

The server will be available at http://localhost:3000. To update to the latest build:

docker compose pull && docker compose up -d

Docker (local dev)

Build and run from source using just:

just build       # build the image
just docker-run  # build + run on :3000
just clean       # stop container and remove image

Modes

• Single phone: one device shows the card and tracks score.
• Room sync: multiple devices join the same room code and share the round state.
• Round time: choose 30, 45, 60, 90, or 120 seconds before starting.
• Card count: play a fixed number of cards instead of using a timer.
• Timed rounds keep dealing cards until time expires and report how many cards were played.
• Card-count rounds stop when the selected number of correct guesses is reached and report how long the round took.
• Skips do not count toward the card-count goal.
• Wikipedia rounds fetch more cards during play, especially after skips; custom and friends rounds loop through the available cards.

Room sync is intentionally lightweight and runs from the local Node server. Rooms are kept in memory and expire after a few hours, so there is no account system or database yet. Hosts get a QR code in the lobby so other phones can scan directly into the room. For internet-wide multiplayer or saved decks later, the same API shape can be moved behind a hosted server and database.

The current image search is not Google Images scraping. It uses a no-key Wikimedia Commons endpoint so the prototype stays simple. A later version can swap /api/images/search to Google Custom Search, Bing Image Search, or another licensed provider without changing the card editor.