SecretEmbeddingSanta is a local multiplayer party game that puts a nerdy AI twist on Secret Santa. Players bring gifts (descriptions), then compete to attract gifts toward themselves by typing guesses that semantically match the hidden gift descriptions. The game uses text embeddings and cosine similarity to create a dynamic, real-time "tug of war" for gifts.
- Everyone joins a room and submits their gift description (kept secret)
- During gameplay, all gifts appear in the center of a circular arena
- Players sit around the circle and type guesses into their text box
- Gifts move toward players based on how semantically similar their guess is to the gift's description
- The closer your guess matches a gift's meaning, the stronger it's pulled toward you
- Game ends on a timer; each player receives the gift closest to them
- Primary: Mobile browsers (phones/tablets on same WiFi)
- Secondary: Desktop browsers
- Multiplayer: Local WiFi only (no internet required after initial load)
- Player opens the app URL (shared by host)
- Sees list of available game rooms
- Can create a new room or join an existing one
- Players see who has joined (displayed in expanding circle)
- Each player enters their name and gift description
- Gift descriptions are private (not shown to others)
- Host can see when all players have submitted
- Host clicks "Start Game" when ready
- All gifts appear as wrapped boxes in center of arena
- Players positioned around the circle perimeter
- Each player has a text input for their guess
- As players type, their guess embedding is computed
- Gifts move toward players based on cosine similarity
- Timer counts down (configurable, default 5 minutes)
- Players can use special powers (see below)
- Timer ends, positions freeze
- Each player assigned closest gift (greedy algorithm by distance)
- Gift descriptions revealed
- Show who gave each gift
- Effect: Freeze a gift in place for 10 seconds
- Uses: Configurable per game (default: 1 per player)
- Activation: Tap power button, then tap target gift
- Visual: Frozen gifts turn blue/icy, show countdown timer
- Effect: See another player's current guess text
- Uses: Configurable per game (default: 2 per player)
- Activation: Tap power button, then tap target player
- Visual: Modal popup showing target's guess
- Local embedding server:
qwen3-embeddings-mlxon port 8000 - Model: Qwen3-Embedding-0.6B-4bit-DWQ (1024 dimensions)
- Gift embeddings: Pre-computed when game starts
- Player guess embeddings: Computed on-the-fly (debounced 200ms)
- Similarity: Cosine similarity, range [-1, 1]
- Runtime: Bun
- Transport: WebSocket for real-time sync
- Static files: Served via HTTP
- Game loop: 20fps (50ms tick) for physics updates
For each gift:
attraction_vector = (0, 0)
for each player:
similarity = cosine(gift.embedding, player.guess_embedding)
if similarity > 0:
direction = normalize(player.position - gift.position)
attraction_vector += direction * similarity
gift.position += attraction_vector * SPEED * deltaTime
- Host runs server on their machine
- Players connect via local IP (e.g.,
192.168.1.42:3000) - All game state managed server-side
- Clients receive state updates, send actions
| Setting | Default | Range | Description |
|---|---|---|---|
| Game Duration | 5 min | 1-30 min | How long the game phase lasts |
| Petrificus Uses | 1 | 0-10 | Uses per player per game |
| Spy Uses | 2 | 0-10 | Uses per player per game |
- Click "Create Room"
- Enter room name
- Adjust settings (optional)
- Enter your name
- Share the URL with friends
- Open URL shared by host
- See room in list
- Click "Join"
- Enter your name
- Enter your gift description
- Wait for host to start
- Type guesses to attract gifts
- Watch gifts move in real-time
- Use Petrificus to freeze a gift you want
- Use Spy to see what others are guessing
- Adjust strategy based on gift movements
- Simplicity: Minimal UI, focus on the arena
- Real-time feedback: Gifts move smoothly as you type
- Social: See other players, their positions, their remaining powers
- Fair: Everyone has same powers, same time
- Fun chaos: Multiple gifts moving creates hectic energy
- Players understand the concept within 1 minute
- Average game feels engaging (not too slow, not too fast)
- Powers feel impactful but not overpowered
- Gift movement is visible and responsive to guesses
- Works smoothly on 4+ players on same WiFi
- Online multiplayer (beyond local WiFi)
- Persistent accounts/history
- Custom themes/skins
- Additional powers
- Tournament mode
- Spectator mode
- Audio/sound effects
SecretEmbeddingSanta/
├── src/
│ ├── server.ts # Bun HTTP + WebSocket server
│ ├── game-state.ts # Room/player/gift state management
│ ├── embeddings.ts # Embedding server client
│ └── types.ts # TypeScript type definitions
├── public/
│ ├── index.html # Single-page app
│ ├── styles.css # Dark theme styling
│ └── game.js # Frontend logic + canvas rendering
├── qwen3-embeddings-mlx/ # (external) Local embedding server
├── PRD.md # This document
├── UI_SPEC.md # Detailed UI/UX specification
└── README.md # Setup instructions