RMHbox — Minigame Design Specifications (Part 2)¶
Version: 2.0
Last Updated: 2026-02-27
Status: Draft
Games Covered: Fact or Friction, Undercover Editor, Minimalist Masterpiece, Emoji Cinema
Parent Document: design-spec-core.md
Table of Contents¶
1. Fact or Friction¶
1.1 Overview¶
Field |
Value |
|---|---|
ID |
|
Display Name |
Fact or Friction |
Category |
|
Icon |
|
Min Players |
2 |
Max Players |
16 |
Estimated Duration |
120 seconds |
Supports Teams |
No |
Join-in-Progress |
|
Tags |
|
1.2 Game Concept¶
High-stakes trivia where answering wrong costs you. A question appears with a Point Pot that starts at a maximum value and rapidly ticks down. Answer correctly early for maximum points, but answer incorrectly and the current pot value is subtracted from your score. The tension between speed and caution creates the “friction.”
1.3 Detailed Mechanics¶
1.3.1 Round Structure¶
The game consists of 8 questions (configurable: FF_TOTAL_QUESTIONS). Each question is an independent sub-round.
Phase |
Duration |
Description |
|---|---|---|
Question Reveal |
2s |
Question text animates in |
Answer Phase |
15s |
Point Pot ticks down; players answer or pass |
Answer Reveal |
4s |
Correct answer shown, scores update |
Brief Pause |
1s |
Transition to next question |
Total game time: ~8 × 22s = ~176s ≈ 3 minutes.
1.3.2 Question Pool¶
Questions are stored in data/rmhbox/fact-or-friction/questions.json. Each question has:
interface TriviaQuestion {
id: string;
question: string;
options: string[]; // exactly 4 options (A, B, C, D)
correctIndex: number; // 0-3
category: string; // e.g., "Science", "History", "Pop Culture"
difficulty: 'easy' | 'medium' | 'hard';
source: string; // attribution / fact-check source
}
Question selection per game:
3 easy, 3 medium, 2 hard (configurable distribution).
No duplicate categories in consecutive questions when possible.
Questions used in the current lobby session are excluded from future rounds.
1.3.3 Point Pot Mechanics¶
The Point Pot is a server-authoritative counter that ticks down:
Starts at
FF_POT_START_VALUE(default: 1000).Decreases by
FF_POT_TICK_VALUE(default: 50) everyFF_POT_TICK_INTERVAL_MS(default: 500ms, i.e., 2 ticks/second).Minimum pot value:
FF_POT_MIN_VALUE(default: 100). The pot never drops below this.When a player submits an answer, the server records the pot value at the moment of server receipt (not client-side clock).
Time to min pot: (1000 − 100) / 50 = 18 ticks = 9 seconds. So the pot drains from 1000→100 over 9 seconds, then stays at 100 for the remaining 6 seconds.
1.3.4 Answering¶
Each question presents 4 multiple-choice options (A, B, C, D).
Answer: Player selects one option. Their answer is locked immediately (no changing).
Pass: Player explicitly clicks “Pass” to skip the question. Score unchanged.
No answer (timeout): If the 15-second timer expires without input, treated as a Pass.
After answering, the player’s UI shows a “Locked in at X points” indicator but does NOT reveal whether the answer is correct until the Answer Reveal phase.
1.3.5 Scoring¶
Outcome |
Score Change |
|---|---|
Correct answer |
|
Incorrect answer |
|
Pass |
0 |
Timeout |
0 |
Difficulty bonus: Hard questions multiply the pot value by FF_HARD_MULTIPLIER (default: 1.5). Medium questions use FF_MEDIUM_MULTIPLIER (default: 1.0, no change). Easy questions use FF_EASY_MULTIPLIER (default: 0.8).
The effective pot value = floor(basePotValue × difficultyMultiplier).
1.3.6 Score Floor¶
A player’s total score cannot drop below FF_SCORE_FLOOR (default: -500). This prevents a death spiral where a player is so far behind they can’t recover and just stops engaging.
1.4 Server-Side State Schema¶
interface FactOrFrictionState {
questions: TriviaQuestion[]; // all questions for this game (pre-selected)
currentQuestionIndex: number; // 0-indexed
totalQuestions: number;
phase: FFPhase;
// Point Pot (current question)
potValue: number; // current pot value
potStartedAt: number; // timestamp when pot started ticking
// Answers for current question
playerAnswers: Map<string, PlayerAnswer>; // userId → answer
// Cumulative scores
playerScores: Map<string, number>; // userId → total score
// History of all questions' results (for end-of-game review)
questionHistory: QuestionResult[];
// Timer
phaseStartedAt: number;
phaseEndsAt: number;
}
type FFPhase = 'QUESTION_REVEAL' | 'ANSWER' | 'ANSWER_REVEAL' | 'PAUSE';
interface PlayerAnswer {
userId: string;
selectedIndex: number | null; // null = pass
potValueAtSubmission: number; // pot value when answer was received
submittedAt: number;
isCorrect: boolean; // computed server-side
scoreChange: number; // +pot or -pot or 0
}
interface QuestionResult {
questionIndex: number;
question: TriviaQuestion;
playerAnswers: PlayerAnswer[];
fastestCorrectUserId: string | null;
correctCount: number;
incorrectCount: number;
passCount: number;
}
1.5 WebSocket Event Map¶
Client → Server¶
Action |
Payload |
Description |
|---|---|---|
|
|
Select A(0), B(1), C(2), or D(3) |
|
|
Explicitly pass on this question |
Zod schemas:
const SubmitAnswerSchema = z.object({
selectedIndex: z.number().int().min(0).max(3),
});
Server → Client (Game Actions)¶
Action Type |
Payload |
Sent To |
Description |
|---|---|---|---|
|
|
All (lobby) |
New question revealed |
|
|
All (lobby) |
Pot value update (every 500ms) |
|
|
Answering player only |
Confirm answer locked at this pot value |
|
|
All (lobby) |
Notification that a player has answered (not WHAT they answered) |
|
|
All (lobby) |
Correct answer + everyone’s results |
|
|
All (lobby) |
Updated leaderboard after each question |
|
|
All (lobby) |
Emitted at the start of each timed phase (ANSWER) via |
|
|
All (lobby) |
Standard timer (every 1s during all timed phases) via |
|
|
All (lobby) |
Sub-round counter update (e.g. “Question 3/8”) via |
FFPlayerQuestionResult:
interface FFPlayerQuestionResult {
userId: string;
userName: string;
selectedIndex: number | null; // null = pass
selectedAnswer: string | null;
isCorrect: boolean;
potValueAtSubmission: number;
scoreChange: number; // +X, -X, or 0
}
1.6 Information Masking¶
Data |
Player View |
Spectator View |
|---|---|---|
Question + options |
Visible |
Visible |
Current pot value |
Visible (real-time) |
Visible (real-time) |
Own answer (after locking) |
Visible (locked-in indicator) |
N/A |
Other players’ answers |
HIDDEN until reveal |
HIDDEN until reveal |
Whether other players have answered |
Visible (answered/not indicator) |
Visible |
Correct answer |
HIDDEN until reveal |
HIDDEN until reveal |
Scores |
Visible (updated after reveal) |
Visible |
getStateForPlayer(userId) during ANSWER phase:
interface FFPlayerState {
currentQuestionIndex: number;
totalQuestions: number;
question: string;
options: string[];
category: string;
difficulty: string;
phase: FFPhase;
potValue: number;
timeRemaining: number;
// My answer (null if not yet answered)
myAnswer: { selectedIndex: number; potValueAtLock: number } | null;
myHasPassed: boolean;
// Other players (masked)
playersAnswered: Array<{ userId: string; userName: string; hasAnswered: boolean }>;
// Scores (cumulative)
scores: Array<{ userId: string; userName: string; totalScore: number }>;
// Question history (revealed questions only)
questionHistory: QuestionResult[];
}
spectatorMode: 'shared-privileged'
getStateForSpectator() returns:
Same as player view. Since correct answers are hidden until reveal for everyone, spectators have no privileged information during the answer phase.
1.7 Join-in-Progress Logic¶
Policy: join_next_subround
Players who join mid-game are added to the player pool at the start of the next question. They start with 0 points and can earn points from that question onward. They miss previous questions’ scores.
Implementation: The game checks pendingPlayers at the transition from ANSWER_REVEAL → PAUSE → QUESTION_REVEAL. New players are initialized in playerScores with 0 and can interact starting from the next ANSWER phase.
1.8 Reconnection Behavior¶
On reconnect:
Player receives their full state including current question, pot value, their locked answer (if any), and score history.
If the ANSWER phase is still active and they haven’t answered, they can still answer.
If they missed an entire question (disconnected during the question), they score 0 for that question (treated as timeout/pass).
1.9 Awards¶
Award |
Condition |
Icon |
|---|---|---|
Pot Sniper |
Answered correctly at the highest pot value (fastest correct answer) |
|
Friction Burn |
Lost the most points from incorrect answers |
|
Cool Head |
Passed the most questions (risk-averse play) |
|
Perfect Score |
Answered every question correctly |
|
Comeback Kid |
Had the biggest single-question positive score swing from negative territory |
|
1.10 NPM Package Suggestions¶
No additional packages. The question pool is a static JSON file. The Point Pot is a simple server-side timer.
1.11 Client Component Structure¶
components/rmhbox/minigames/fact-or-friction/
FactOrFrictionGame.tsx # Main game component, phase router
PointPotDisplay.tsx # Animated pot value with fire/drain effect
QuestionCard.tsx # Question text + 4 option buttons
OptionButton.tsx # A/B/C/D button with lock/correct/wrong states
ScoreRibbon.tsx # Running score display with +/- animations
AnswerReveal.tsx # Correct answer highlight + player results
Mobile UI layout (ANSWER phase):
┌──────────────────────────────┐
│ Fact or Friction Q3/8 │
├──────────────────────────────┤
│ 🏆 Science │ ⭐ Medium │
├──────────────────────────────┤
│ │
│ "What is the chemical │
│ symbol for Gold?" │
│ │
├──────────────────────────────┤
│ 🔥 Point Pot: 750 🔥 │ ← Animated, pulsing, shrinking
├──────────────────────────────┤
│ ┌───────────────────────┐ │
│ │ A) Go │ │ ← Tap to lock in
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ B) Au ✓ LOCKED │ │ ← Locked state (green border)
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ C) Ag │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ D) Gd │ │
│ └───────────────────────┘ │
├──────────────────────────────┤
│ [Pass] ⏱ 0:08 │
│ Score: 1,250 │ 4/6 answered│
└──────────────────────────────┘
1.12 Constants¶
export const FF_TOTAL_QUESTIONS = 8;
export const FF_QUESTION_REVEAL_SECONDS = 2;
export const FF_ANSWER_DURATION_SECONDS = 15;
export const FF_ANSWER_REVEAL_SECONDS = 4;
export const FF_PAUSE_SECONDS = 1;
export const FF_POT_START_VALUE = 1000;
export const FF_POT_TICK_VALUE = 50;
export const FF_POT_TICK_INTERVAL_MS = 500;
export const FF_POT_MIN_VALUE = 100;
export const FF_EASY_MULTIPLIER = 0.8;
export const FF_MEDIUM_MULTIPLIER = 1.0;
export const FF_HARD_MULTIPLIER = 1.5;
export const FF_SCORE_FLOOR = -500;
export const FF_QUESTION_DISTRIBUTION = { easy: 3, medium: 3, hard: 2 };
1.13 Game Settings Schema (§12A)¶
Host-configurable settings for Fact or Friction. Defined in MinigameDefinition.settingsSchema.
Handlers read values via this.getSetting(key, CONSTANT_DEFAULT).
Key |
Type |
Label |
Description |
Default |
Constraints |
|---|---|---|---|---|---|
|
|
Number of Questions |
How many fact/fiction questions to play |
|
min: 4, max: 12, step: 1 |
|
|
Answer Duration (seconds) |
Time players have to lock in their answer each round |
|
min: 10, max: 45, step: 5 |
|
|
Starting Pot Value |
Points in the pot at the start of each question |
|
min: 50, max: 200, step: 25 |
|
|
Score Floor |
Prevent players from going below 0 points |
|
— |
|
|
Difficulty |
Difficulty of the fact/fiction statements |
|
options: |
Constant Mapping:
Setting Key |
Constant Override |
Usage |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
If |
|
|
Filters question set by difficulty tag |
1.14 Anti-Cheat Notes¶
The correct answer index is NEVER sent to clients until the
ANSWER_REVEALphase.The pot value is server-authoritative. The client displays the value from the latest
FF_POT_TICKaction and interpolates visually between ticks, but the score is always computed using the server’s pot value at receipt time.Answer submission time is server-stamped, not client-stamped.
Each player can only submit one answer per question. Duplicate submissions are silently ignored.
1.15 Game History¶
Game History Level: Summary Log
Per-question results are compact and self-explanatory — full action replay isn’t needed since the game has no spatial or creative state. The summary captures who answered what, how fast, and the pot dynamics.
initialState¶
interface FFInitialState {
totalQuestions: number;
potStartValue: number;
potDecayRate: number;
playerIds: string[];
categoryPool: string[]; // categories selected for this session
}
Actions Logged¶
Action Type |
Payload |
Recorded When |
|---|---|---|
|
|
Question is revealed |
|
|
Player locks in answer |
|
|
Player passes or timer expires |
|
|
Answer reveal phase |
Replay Value¶
Review who gambled on high pot values and lost, who was consistently fastest, and how the pot decayed across rounds. Useful for settling “I answered first!” disputes.
Note: The
GameLogalso includesgameSettings: GameSettingValuesat the top level (per core.md §12A.11), capturing the exact game settings used for this match.
1.16 History Display Configuration¶
Detail Component: FactOrFrictionHistoryDetail
Renders the expanded game log as a question-by-question breakdown:
Each question with its options, correct answer highlighted
Per-player answer indicators (correct/incorrect/timeout)
Point pot value at each player’s submission time
Running score graph across questions
Difficulty badge per question (easy/medium/hard)
Searchable Fields:
Field Key |
Label |
Extraction |
|---|---|---|
|
Questions |
Question text from |
|
Categories |
Question categories from |
Filterable Fields:
Field Key |
Label |
Type |
Details |
|---|---|---|---|
|
Difficulty |
select |
|
|
Questions Correct |
range |
Number of correct answers by user |
Summary Extractor:
getSummary: (log) => {
const questions = log.actions.filter(a => a.type === 'question_reveal');
return `${questions.length} questions — Trivia challenge`;
}
Component Structure:
FactOrFrictionHistoryDetail.tsx
├── QuestionCard (per question)
│ ├── QuestionText + DifficultyBadge
│ ├── AnswerOptions (correct highlighted, player selections shown)
│ ├── PotValueIndicator (point pot at submission time)
│ └── PlayerAnswerGrid (who answered what)
├── ScoreGraph (running score over questions)
└── Final scores summary
1.17 MinigameRenderer & Client-Server Wiring¶
MinigameRenderer Registration¶
The MinigameRenderer lazy-loads the Fact or Friction component so it is only bundled when the game is active:
const MINIGAME_COMPONENTS = {
'fact-or-friction': lazy(() => import('./minigames/fact-or-friction/FactOrFrictionGame')),
// …other minigames
};
Client-Side Store Integration¶
The client store listens for server-pushed actions and updates local state accordingly:
useEffect(() => {
const handlers: Record<string, (payload: unknown) => void> = {
FF_QUESTION: (p) => dispatch({ type: 'FF_QUESTION', payload: p }),
FF_POT_TICK: (p) => dispatch({ type: 'FF_POT_TICK', payload: p }),
FF_ANSWER_LOCKED: (p) => dispatch({ type: 'FF_ANSWER_LOCKED', payload: p }),
FF_PLAYER_ANSWERED: (p) => dispatch({ type: 'FF_PLAYER_ANSWERED', payload: p }),
FF_ANSWER_REVEAL: (p) => dispatch({ type: 'FF_ANSWER_REVEAL', payload: p }),
FF_SCORE_UPDATE: (p) => dispatch({ type: 'FF_SCORE_UPDATE', payload: p }),
TIMER_TICK: (p) => dispatch({ type: 'TIMER_TICK', payload: p }),
};
Object.entries(handlers).forEach(([ev, fn]) => socket.on(ev, fn));
return () => { Object.keys(handlers).forEach((ev) => socket.off(ev)); };
}, [socket, dispatch]);
Client-Side Input Dispatch¶
Players submit answers or pass via the socket:
// Lock in an answer
socket.emit('SUBMIT_ANSWER', { selectedIndex });
// Pass on the current question
socket.emit('PASS_QUESTION', {});
Server-Side Handler Registration¶
The server registers the game handler at startup:
import { FactOrFrictionGame } from './minigames/fact-or-friction/FactOrFrictionGame';
MINIGAME_SERVER_REGISTRY.set('fact-or-friction', FactOrFrictionGame);
Note: All server broadcasts use
this.broadcastGameAction()(theBaseMinigamewrapper), not rawcontext.broadcastToLobby.
Sound Effect Integration¶
Event |
Sound |
Notes |
|---|---|---|
Question revealed |
|
New question card flies in |
Pot ticking |
(visual only) |
Pot value decreases — no audio cue |
Answer locked |
|
Confirms the player’s selection |
Answer reveal (correct) |
|
Positive feedback |
Answer reveal (wrong) |
|
Negative feedback |
Score update |
|
Points awarded |
Timer warning |
|
Final seconds of the timer |
Spectator Rendering¶
Spectators see all player answer states (who has answered, but not which option until reveal), the current pot value, and the countdown timer. The component renders a read-only question card without clickable options.
2. Undercover Editor¶
2.1 Overview¶
Field |
Value |
|---|---|
ID |
|
Display Name |
Undercover Editor |
Category |
|
Icon |
|
Min Players |
4 |
Max Players |
10 |
Estimated Duration |
~variable (parallel writing, N rounds) |
Supports Teams |
No |
Join-in-Progress |
|
Tags |
|
2.2 Game Concept¶
All players write sentences for ALL stories simultaneously each round. Each player is secretly assigned as the “undercover editor” of exactly one other player’s story (cyclic assignment). After writing rounds, editors secretly edit their assigned story. Players then review all completed stories and try to match each story with its undercover editor.
2.3 Detailed Mechanics¶
2.3.1 Setup¶
Story Creation: One story is created per player (N stories in parallel). Each story has a unique prompt and keyword.
Editor Assignment: Cyclic assignment — player i edits player (i+1 mod N)’s story. Each player is the editor of exactly one story and the owner of exactly one story.
Keyword Assignment: Each story’s keyword is sent only to the assigned editor’s socket. Keywords are common English words that could plausibly appear in many stories.
Story Prompts: Each story receives a short prompt to set the theme (e.g., “A detective arrives at an abandoned mansion on a stormy night.”).
2.3.2 Phase Structure¶
Phase |
Duration |
Description |
|---|---|---|
SETUP |
instant |
Assign roles, create N stories (one per player) |
WRITE |
45s (configurable) |
ALL players write a sentence for each story simultaneously |
EDIT |
30s (configurable) |
ALL editors secretly edit their assigned story simultaneously |
(repeat WRITE → EDIT for N rounds) |
||
REVIEW |
infinite |
Players match stories to their editors (host or all-locked-in advances) |
REVEAL |
10s |
Editor assignments, keywords, edits revealed; scores shown |
2.3.3 Write Phase¶
All players write a sentence for each story simultaneously.
Sentence constraints: min 10 chars, max 200 chars.
Players can unsubmit and re-edit within the write timer.
Write phase ends early only when ALL players have submitted for ALL stories.
If the timer expires without input, the server auto-submits
"..."(an ellipsis sentence indicating a timeout).
2.3.4 Edit Phase¶
Each editor edits their ONE assigned story (one word swap per round).
The edit UI shows the story with each word as a clickable token. Selecting a word reveals an input field to replace it.
The edit is applied silently — no other player is notified that an edit occurred.
The editor can choose to skip editing (
SKIP_EDIT).Constraints:
Only one word can be changed per round.
The replacement word must be a single word (no spaces), maximum 30 characters.
Cannot edit a word already edited in a previous round.
2.3.5 Review Phase¶
Infinite time — the host advances or all players lock in.
Players use dropdowns to match each story to its suspected editor.
Players can save and update their guesses, then “Lock In.”
Host advance or all-locked-in triggers REVEAL.
2.3.6 Reveal Phase¶
Editor assignments are revealed.
Keywords are revealed.
All edits are highlighted (original → replacement).
Scores are calculated and displayed.
2.4 Server-Side State Schema¶
interface UndercoverEditorState {
playerIds: string[];
totalRounds: number;
currentRound: number;
phase: UEPhase;
stories: Map<string, ParallelStory>;
editorAssignments: Map<string, string>; // editorId → storyId
roundSubmissions: Map<string, Map<string, string>>; // storyId → userId → text
roundEditsDone: Map<string, boolean>; // storyId → done?
matchGuesses: Map<string, Map<string, string>>; // guesserId → (storyId → editorId)
matchLockedIn: Set<string>;
playerScores: Map<string, number>;
phaseStartedAt: number;
phaseEndsAt: number;
}
type UEPhase = 'SETUP' | 'WRITE' | 'EDIT' | 'REVIEW' | 'REVEAL';
interface ParallelStory {
storyId: string; // same as ownerUserId
prompt: string;
ownerUserId: string;
ownerName: string;
keyword: string;
editorUserId: string;
sentences: StorySentence[];
edits: WordEdit[];
editedWordPositions: Set<string>;
keywordInStory: boolean;
}
interface StorySentence {
authorUserId: string;
authorName: string;
text: string;
originalText: string;
turnNumber: number;
words: string[];
}
interface WordEdit {
sentenceIndex: number;
wordIndex: number;
originalWord: string;
newWord: string;
editedOnTurn: number;
}
2.5 WebSocket Event Map¶
Client → Server¶
Action |
Payload |
Description |
|---|---|---|
|
|
Submit a sentence for a specific story |
|
|
Retract a submitted sentence |
|
|
Secretly edit a word in assigned story |
|
|
Choose not to edit this round |
|
|
Save story-to-editor matching guesses |
|
|
Lock in matching guesses |
Zod schemas:
const WriteSentenceSchema = z.object({
storyId: z.string().min(1),
text: z.string().min(10).max(200),
});
const UnsubmitSentenceSchema = z.object({
storyId: z.string().min(1),
});
const EditWordSchema = z.object({
storyId: z.string().min(1),
sentenceIndex: z.number().int().min(0),
wordIndex: z.number().int().min(0),
newWord: z.string().min(1).max(30).regex(/^\S+$/),
});
const SubmitMatchingSchema = z.object({
guesses: z.record(z.string(), z.string()),
});
Server → Client (Game Actions)¶
Action Type |
Payload |
Sent To |
Description |
|---|---|---|---|
|
|
All (lobby) |
Stories list, players, totalRounds |
|
|
Individual |
Role, assignedStoryId, keyword, storyOwnerName (editor fields only for editors) |
|
|
All (lobby) |
Write phase begins |
|
|
Submitting player |
Confirms sentence submission |
|
|
Submitting player |
Confirms sentence retraction |
|
|
All (lobby) |
Per-story submission counts |
|
|
All (lobby) |
Edit phase begins |
|
|
Editor only |
Prompt editor to make their secret edit |
|
|
Editor |
Confirms edit or skip |
|
|
All (lobby) |
All story views after edits |
|
|
All (lobby) |
Review phase begins |
|
|
Submitting player |
Confirms guesses saved |
|
|
All (lobby) |
A player locked in their guesses |
|
|
All (lobby) |
Full reveal |
|
|
Individual |
Error message |
|
|
All (lobby) |
Emitted at the start of each timed phase (WRITE, EDIT) via |
|
|
All (lobby) |
Standard timer (every 1s during all timed phases) via |
|
|
All (lobby) |
Round counter update (e.g. “Round 1/2”) via |
Supporting types:
interface StoryInfo {
storyId: string;
prompt: string;
ownerUserId: string;
ownerName: string;
}
interface PlayerInfo {
userId: string;
userName: string;
}
interface StoryView {
storyId: string;
ownerName: string;
prompt: string;
sentences: StorySentenceView[];
}
interface StorySentenceView {
authorName: string;
text: string;
roundNumber: number;
}
interface EditableStory {
storyId: string;
ownerName: string;
sentences: Array<{
authorName: string;
words: Array<{
word: string;
index: number;
sentenceIndex: number;
isEditable: boolean; // false if already edited
}>;
}>;
}
interface StoryReveal {
storyId: string;
ownerUserId: string;
ownerName: string;
editorUserId: string;
editorName: string;
keyword: string;
keywordInStory: boolean;
sentences: StorySentenceView[];
edits: WordEditView[];
}
interface WordEditView {
sentenceIndex: number;
sentenceAuthor: string;
originalWord: string;
newWord: string;
editedOnRound: number;
}
interface MatchResult {
guesserId: string;
guesserName: string;
storyId: string;
guessedEditorId: string;
actualEditorId: string;
isCorrect: boolean;
}
interface ScoreResult {
userId: string;
userName: string;
score: number;
breakdown: Record<string, number>;
}
2.6 Information Masking¶
This game has critical masking requirements due to the parallel editor assignments.
Data |
Writer View |
Editor View |
Spectator View |
|---|---|---|---|
Keyword |
HIDDEN until REVEAL |
VISIBLE (own assigned story only) |
VISIBLE (all) |
Editor assignments |
HIDDEN until REVEAL |
Known (self only) |
VISIBLE (all) |
Edit history |
HIDDEN until REVEAL |
Own edits only |
VISIBLE (all) |
Other players’ submissions |
HIDDEN |
HIDDEN |
HIDDEN |
Match guesses |
Own only |
Own only |
HIDDEN |
spectatorMode: 'shared-privileged'
getStateForPlayer(userId) during WRITE phase:
interface UEPlayerWriteState {
phase: UEPhase;
currentRound: number;
totalRounds: number;
stories: StoryView[];
timeRemaining: number;
mySubmissions: Record<string, string>; // storyId → submitted text (or absent)
submissionProgress: Record<string, number>;
}
getStateForPlayer(userId) for an Editor during EDIT phase:
interface UEEditorEditState extends UEPlayerWriteState {
editableStory: EditableStory;
myEdits: WordEdit[];
keyword: string;
}
getStateForSpectator() returns:
Omniscient view: sees all editor assignments, keywords, edits as they happen, and submission progress. This creates an exciting viewing experience for the audience.
2.7 Join-in-Progress Logic¶
Policy: spectate_only
Roles, story assignments, and the parallel writing structure are established at game start. Adding a player mid-game would disrupt the editor assignment cycle and story balance.
2.8 Reconnection Behavior¶
On reconnect:
Player receives their role, current stories, what round it is, and phase.
Editors receive the keyword and their edit history.
If the WRITE or EDIT phase is still active, they can still submit.
If their turn was auto-completed (timeout), they cannot redo it.
2.9 Player Disconnect Mid-Game¶
During EDIT: Auto-completes the editor’s edit (marked as done).
During WRITE: Unanswered defaults to
"..."at phase end.During REVIEW: Player’s guesses treated as empty.
If the Editor fully disconnects (grace period expires): the game continues. The editor’s edit phases are auto-skipped.
Minimum players: If players drop below
minPlayers(4), the game force-ends.
2.10 Awards¶
Award |
Condition |
Icon |
|---|---|---|
Best Detective 🔍 |
Most correct editor identifications |
|
Sneakiest Editor 🥷 |
Fooled the most players |
|
2.11 Client Component Structure¶
components/rmhbox/minigames/undercover-editor/
UndercoverEditorGame.tsx # Main game component, phase router
StoryDisplay.tsx # Read-only story text
WriteInput.tsx # Sentence composition (10-200 chars)
StoryEditor.tsx # Word tokens for editor
MatchingPanel.tsx # Review phase — story-to-editor matching
RevealScreen.tsx # Available but inline reveal used for parallel
RoleBadge.tsx # Editor keyword badge
TurnIndicator.tsx # Available for future use
Mobile UI layout (WRITE phase):
┌──────────────────────────────┐
│ Undercover Editor Round 1/2 │
├──────────────────────────────┤
│ ✏️ Writing for all stories │
│ ⏱ 0:32 │
├──────────────────────────────┤
│ │
│ 📖 Story: Alice's Tale │
│ Prompt: "A detective..." │
│ │
│ > "He found the door ajar │
│ and stepped inside." │
│ — Bob (Round 1) │
│ │
│ ┌───────────────────────┐ │
│ │ Write your sentence...│ │
│ └───────────────────────┘ │
│ [Submit] [Unsubmit] │
│ │
├──────────────────────────────┤
│ Stories: 2/4 done │
│ 🔎 You are a Writer │
│ Score: 0 │
└──────────────────────────────┘
2.12 Constants¶
export const UE_MIN_PLAYERS = 4;
export const UE_MAX_PLAYERS = 10;
export const UE_ROTATIONS = 2; // number of write-edit rounds
export const UE_WRITE_TIMEOUT_SECONDS = 45;
export const UE_EDIT_TIMEOUT_SECONDS = 30;
export const UE_REVEAL_DURATION = 10;
export const UE_DISCONNECT_WAIT = 15;
export const UE_MIN_SENTENCE_LENGTH = 10;
export const UE_MAX_SENTENCE_LENGTH = 200;
export const UE_MAX_EDIT_WORD_LENGTH = 30;
export const UE_CORRECT_VOTE_BONUS = 100; // each correct editor match
export const UE_KEYWORD_PROXIMITY_BONUS = 50; // editor whose keyword appears in story
export const UE_EDITOR_MAJOR_WIN = 600; // editor not caught
export const UE_EDITOR_LOSS = 50; // editor caught
export const UE_WRITER_MAJOR_WIN = 400; // story owner whose editor fooled people
export const UE_WRITER_LOSS = 50; // story owner whose editor was easily caught
2.13 Game Settings Schema (§12A)¶
Host-configurable settings for Undercover Editor. Defined in MinigameDefinition.settingsSchema.
Handlers read values via this.getSetting(key, CONSTANT_DEFAULT).
Key |
Type |
Label |
Description |
Default |
Constraints |
|---|---|---|---|---|---|
|
|
Rotations |
Number of write-edit rounds |
|
min: 1, max: 3, step: 1 |
|
|
Write Duration (seconds) |
Time to write sentences each round |
|
min: 30, max: 90, step: 5 |
|
|
Edit Duration (seconds) |
Time to edit assigned story each round |
|
min: 15, max: 60, step: 5 |
Note: The old
accusationDurationsetting is removed since the REVIEW phase is infinite (host or all-locked-in advances).
Constant Mapping:
Setting Key |
Constant Override |
Usage |
|---|---|---|
|
|
|
|
|
|
|
|
|
2.14 Scoring¶
Scoring is based on matching accuracy during the REVIEW phase:
Condition |
Constant |
Points |
|---|---|---|
Each correct editor match |
|
100 |
Editor whose keyword appears in story |
|
50 |
Editor not caught (majority didn’t guess correctly) |
|
600 |
Editor caught |
|
50 |
Story owner whose editor was sneaky (fooled people) |
|
400 |
Story owner whose editor was easily caught |
|
50 |
2.15 Game History¶
Game History Level: Full Action Log
Undercover Editor is one of the most replay-worthy games — watching the stories evolve and spotting where each editor’s subtle word swaps were hidden is endlessly entertaining. The full action log preserves every submission, edit, and matching result.
initialState¶
interface UEInitialState {
stories: Array<{ storyId: string, prompt: string, ownerUserId: string }>;
editorAssignments: Record<string, string>; // editorId → storyId
keywords: Record<string, string>; // storyId → keyword
playerIds: string[];
totalRounds: number;
}
Actions Logged¶
Action Type |
Payload |
Recorded When |
|---|---|---|
|
|
Write phase begins |
|
|
Player submits sentence |
|
|
Editor makes a substitution |
|
|
Editor passes on editing |
|
|
End of each round — full story state |
|
|
Player submits matching guesses |
|
|
Player locks in |
|
|
Post-game reveal |
Replay Value¶
Step through the stories’ evolution round by round. See every word each editor swapped, how the matching guesses compared to reality, and which editors were sneakiest. The EDITOR_SWAP entries are especially fun — compare original vs. replacement and judge how subtle each edit was.
Note: The
GameLogalso includesgameSettings: GameSettingValuesat the top level (per core.md §12A.11), capturing the exact game settings used for this match.
2.16 History Display Configuration¶
Detail Component: UndercoverEditorHistoryDetail
Renders the expanded game log as a story review:
All stories with editor word swaps highlighted
Round-by-round timeline showing who wrote what
Editor assignment reveal with matching results
Keyword reveal and whether each keyword appeared in its story
Score breakdown per player
Searchable Fields:
Field Key |
Label |
Extraction |
|---|---|---|
|
Story Sentences |
All sentences from |
|
Keywords |
The secret keywords from |
Filterable Fields:
Field Key |
Label |
Type |
Details |
|---|---|---|---|
|
Your Role |
select |
|
|
Correct Matches |
range |
Number of correct editor identifications |
Summary Extractor:
getSummary: (log) => {
const endAction = log.actions.find(a => a.type === 'final_reveal');
const correct = endAction?.payload.matchResults?.filter((r: any) => r.isCorrect).length ?? 0;
const total = endAction?.payload.matchResults?.length ?? 0;
return `${correct}/${total} editors identified — Parallel writing mystery`;
}
Component Structure:
UndercoverEditorHistoryDetail.tsx
├── StoryView (per story with highlighted edits)
├── RoundTimeline (who wrote each sentence per round)
├── MatchingResults (editor identification accuracy)
├── KeywordReveal (keywords + whether they appeared)
└── Final scores summary
2.17 MinigameRenderer & Client-Server Wiring¶
MinigameRenderer Registration¶
The MinigameRenderer lazy-loads the Undercover Editor component:
const MINIGAME_COMPONENTS = {
'undercover-editor': lazy(() => import('./minigames/undercover-editor/UndercoverEditorGame')),
// …other minigames
};
Client-Side Store Integration¶
The client store listens for server-pushed actions and updates local state accordingly:
useEffect(() => {
const handlers: Record<string, (payload: unknown) => void> = {
UE_GAME_START: (p) => dispatch({ type: 'UE_GAME_START', payload: p }),
UE_ROLE_ASSIGNED: (p) => dispatch({ type: 'UE_ROLE_ASSIGNED', payload: p }),
UE_WRITE_START: (p) => dispatch({ type: 'UE_WRITE_START', payload: p }),
UE_SENTENCE_CONFIRMED: (p) => dispatch({ type: 'UE_SENTENCE_CONFIRMED', payload: p }),
UE_SENTENCE_UNSUBMITTED: (p) => dispatch({ type: 'UE_SENTENCE_UNSUBMITTED', payload: p }),
UE_SUBMISSION_PROGRESS: (p) => dispatch({ type: 'UE_SUBMISSION_PROGRESS', payload: p }),
UE_EDIT_START: (p) => dispatch({ type: 'UE_EDIT_START', payload: p }),
UE_EDIT_PROMPT: (p) => dispatch({ type: 'UE_EDIT_PROMPT', payload: p }),
UE_EDIT_CONFIRMED: (p) => dispatch({ type: 'UE_EDIT_CONFIRMED', payload: p }),
UE_STORIES_UPDATED: (p) => dispatch({ type: 'UE_STORIES_UPDATED', payload: p }),
UE_REVIEW_START: (p) => dispatch({ type: 'UE_REVIEW_START', payload: p }),
UE_MATCHING_SAVED: (p) => dispatch({ type: 'UE_MATCHING_SAVED', payload: p }),
UE_PLAYER_LOCKED_IN: (p) => dispatch({ type: 'UE_PLAYER_LOCKED_IN', payload: p }),
UE_REVEAL: (p) => dispatch({ type: 'UE_REVEAL', payload: p }),
UE_ERROR: (p) => dispatch({ type: 'UE_ERROR', payload: p }),
TIMER_TICK: (p) => dispatch({ type: 'TIMER_TICK', payload: p }),
};
Object.entries(handlers).forEach(([ev, fn]) => socket.on(ev, fn));
return () => { Object.keys(handlers).forEach((ev) => socket.off(ev)); };
}, [socket, dispatch]);
Client-Side Input Dispatch¶
Players write sentences, editors edit words or skip, and everyone submits matching guesses:
// Writer submits a sentence for a story
socket.emit('WRITE_SENTENCE', { storyId, text });
// Writer retracts a submitted sentence
socket.emit('UNSUBMIT_SENTENCE', { storyId });
// Editor swaps a word (Editor only)
socket.emit('EDIT_WORD', { storyId, sentenceIndex, wordIndex, newWord });
// Editor skips editing (Editor only)
socket.emit('SKIP_EDIT', {});
// Save matching guesses
socket.emit('SUBMIT_MATCHING', { guesses });
// Lock in matching guesses
socket.emit('LOCK_IN_MATCHING', {});
Server-Side Handler Registration¶
The server registers the game handler at startup:
import { UndercoverEditorGame } from './minigames/undercover-editor/UndercoverEditorGame';
MINIGAME_SERVER_REGISTRY.set('undercover-editor', UndercoverEditorGame);
Note: All server broadcasts use
this.broadcastGameAction()(theBaseMinigamewrapper), not rawcontext.broadcastToLobby.
Sound Effect Integration¶
Event |
Sound |
Notes |
|---|---|---|
Game start |
|
Intro transition |
Role assigned |
|
Role reveal |
Write start |
|
Writing phase begins |
Sentence confirmed |
|
Confirms submission |
Edit prompt |
|
Editor’s turn to edit |
Edit confirmed |
|
Confirms edit or skip |
Review start |
|
Review phase begins |
Player locked in |
|
Confirms lock-in |
Reveal |
|
Editor identities and edits unveiled |
Countdown (≤3s) |
|
Final seconds of timed phases |
Spectator Rendering¶
Spectators have an omniscient view — they see all editor assignments, keywords, edits as they happen, and submission progress. The component checks privateState.isSpectator and shows full info with RoleBadge indicators.
3. Minimalist Masterpiece¶
3.1 Overview¶
Field |
Value |
|---|---|
ID |
|
Display Name |
Minimalist Masterpiece |
Category |
|
Icon |
|
Min Players |
3 |
Max Players |
12 |
Estimated Duration |
180 seconds |
Supports Teams |
No |
Join-in-Progress |
|
Tags |
|
3.2 Game Concept¶
Restricted drawing followed by peer valuation. All players receive the same drawing prompt but are limited to exactly 5 strokes. After drawing, an Auction Phase follows where players use fake currency to bid on the pieces they think are the best. The artist whose work fetches the highest total “Market Value” wins.
3.3 Detailed Mechanics¶
3.3.1 Game Flow¶
Phase |
Duration |
Description |
|---|---|---|
Prompt Reveal |
3s |
Drawing prompt appears |
Drawing Phase |
60s |
Players draw with 5 strokes |
Gallery Walk |
15s |
View all drawings side by side |
Auction Phase |
60s |
Bid on other players’ drawings |
Results |
10s |
Show market values, winner |
Total game time: ~148s ≈ 2.5 minutes.
3.3.2 Drawing Prompt¶
The server selects a prompt from data/rmhbox/minimalist-masterpiece/prompts.json:
interface DrawingPrompt {
id: string;
text: string; // e.g., "A house on a hill"
category: string; // e.g., "Landscape", "Animal", "Object"
difficulty: 'easy' | 'medium' | 'hard';
}
All players receive the same prompt for fair comparison.
3.3.3 Drawing Constraints¶
Exactly 5 strokes. A stroke is a continuous path from pen-down to pen-up (or finger-down to finger-up on mobile).
Players can undo a stroke (replaces it, doesn’t add a new one — total stays ≤ 5).
Canvas size: 400×400 logical pixels (scaled for display). Coordinate system is 0–400 on both axes.
Stroke data: Each stroke is represented as a polyline with sampled points.
Color: Players can choose from
MM_COLOR_PALETTE(8 predefined colors). Default: black.Stroke width: Fixed at
MM_STROKE_WIDTH(default: 4px). No variation — keeps it minimalist.No fill, no text, no shapes — freehand strokes only.
interface Stroke {
id: string; // unique stroke identifier
points: Point[]; // sampled points along the stroke
color: string; // hex color from palette
width: number; // stroke width in px
timestamp: number; // when the stroke was completed
}
interface Point {
x: number; // 0–400
y: number; // 0–400
pressure: number; // 0–1 (from pressure-sensitive input; 1 if unavailable)
}
Anti-bot validation:
Each stroke must have at least
MM_MIN_POINTS_PER_STROKE(default: 5) points.Time between first and last point of a stroke must be ≥
MM_MIN_STROKE_DURATION(default: 100ms).Maximum points per stroke:
MM_MAX_POINTS_PER_STROKE(default: 500, to prevent DoS).
3.3.4 Drawing Submission¶
Players’ strokes are buffered client-side and submitted as a batch when:
All 5 strokes are completed, OR
The timer expires (whatever strokes exist are submitted).
The client sends SUBMIT_DRAWING with the full stroke data. The server validates and stores it.
Players who disconnect or don’t submit anything have an empty drawing (0 strokes). They are still entered into the auction but are unlikely to receive bids.
3.3.5 Gallery Walk¶
All drawings are displayed in a scrollable gallery. Each drawing is attributed to an anonymous label (“Artist 1,” “Artist 2,” etc.) — NOT player names. The mapping is randomized.
Players browse the gallery to decide where to bid. On mobile, drawings are shown one at a time in a swipeable carousel.
3.3.6 Auction Phase¶
Each player receives MM_STARTING_CURRENCY (default: 1000 coins) of fake auction currency.
Bidding rules:
Players can bid on any drawing except their own. Self-bidding is impossible (the server knows the mapping).
A player can distribute their coins across multiple drawings (partial bids).
Bids are placed in increments of
MM_BID_INCREMENT(default: 50 coins).Players can increase their bid on a drawing multiple times (additive).
Players can retract a bid (get coins back) and reallocate.
Bids are visible in real-time to all players. Each drawing shows its current total bid value. This creates competitive bidding dynamics.
When the timer expires, all bids are finalized.
Bid action:
interface BidAction {
drawingId: string; // anonymous drawing identifier
amount: number; // positive = add bid, negative = retract (limited to what you've already bid)
}
3.3.7 Scoring¶
After the auction:
Market Value = total coins bid on a drawing by ALL other players.
Artist ranking is by Market Value (descending).
Score conversion:
Rank 1:
MM_RANK_1(default: 500)Rank 2:
MM_RANK_2(default: 350)Rank 3:
MM_RANK_3(default: 250)Remaining:
MM_PARTICIPATION(default: 100)
Investment bonus: Players who bid on the highest-valued drawing (correct market prediction) receive
MM_INVESTMENT_BONUS(default: 50 bonus points) proportional to how much they invested as a fraction of the drawing’s total value.Formula:
investmentBonus = floor(MM_INVESTMENT_BONUS * (playerBid / totalBid))
3.4 Server-Side State Schema¶
interface MinimalistMasterpieceState {
prompt: DrawingPrompt;
phase: MMPhase;
// Drawing data
drawings: Map<string, PlayerDrawing>; // keyed by anonymous drawingId
drawingIdToUserId: Map<string, string>; // reverse mapping (server-only)
userIdToDrawingId: Map<string, string>; // forward mapping (server-only)
// Auction data
playerCurrencies: Map<string, number>; // userId → remaining coins
bids: Map<string, DrawingBids>; // drawingId → all bids on it
// Results
marketValues: Map<string, number>; // drawingId → total bid value
rankings: MMRanking[] | null;
// Timer
phaseStartedAt: number;
phaseEndsAt: number;
}
type MMPhase = 'PROMPT_REVEAL' | 'DRAWING' | 'GALLERY' | 'AUCTION' | 'RESULTS';
interface PlayerDrawing {
drawingId: string; // anonymous identifier
strokes: Stroke[];
submittedAt: number | null; // null if not yet submitted
strokeCount: number;
}
interface DrawingBids {
drawingId: string;
totalValue: number;
bidders: Map<string, number>; // userId → amount they bid
}
interface MMRanking {
drawingId: string;
artistUserId: string;
artistUserName: string;
marketValue: number;
rank: number;
points: number;
strokes: Stroke[]; // included for results display
}
3.5 WebSocket Event Map¶
Client → Server¶
Action |
Payload |
Description |
|---|---|---|
|
|
Submit completed drawing (max 5 strokes) |
|
|
Bid on a drawing (positive = add, negative = retract) |
Zod schemas:
const StrokeSchema = z.object({
id: z.string().min(1).max(36),
points: z.array(z.object({
x: z.number().min(0).max(400),
y: z.number().min(0).max(400),
pressure: z.number().min(0).max(1),
})).min(5).max(500),
color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
width: z.number().positive(),
timestamp: z.number(),
});
const SubmitDrawingSchema = z.object({
strokes: z.array(StrokeSchema).max(5),
});
const PlaceBidSchema = z.object({
drawingId: z.string().min(1).max(36),
amount: z.number().int().multipleOf(50), // must be in increments of 50
});
Server → Client (Game Actions)¶
Action Type |
Payload |
Sent To |
Description |
|---|---|---|---|
|
|
All (lobby) |
Prompt revealed, drawing begins |
|
|
All (lobby) |
A player finished their drawing |
|
|
All (lobby) |
Gallery walk begins |
|
|
All (lobby) |
Auction begins |
|
|
Each player individually |
Bid state updated |
|
|
All (lobby) |
Public bid total update |
|
|
All (lobby) |
Final results |
|
|
All (lobby) |
Emitted at the start of each timed phase (DRAWING, GALLERY, AUCTION) via |
|
|
All (lobby) |
Standard timer (every 1s during all timed phases) via |
Supporting types:
interface GalleryDrawing {
drawingId: string;
label: string; // "Artist 1", "Artist 2", etc.
strokes: Stroke[];
}
interface AuctionDrawing extends GalleryDrawing {
currentBidTotal: number;
myBidAmount: number; // per-player (0 if not bid yet)
isMine: boolean; // true if this is the player's own drawing (can't bid)
}
interface InvestmentBonus {
userId: string;
userName: string;
bonusPoints: number;
investedIn: string; // drawingId of the highest-valued drawing they invested in
}
3.6 Information Masking¶
Data |
Player View |
Spectator View |
|---|---|---|
Drawing prompt |
Visible |
Visible |
Own drawing (during drawing) |
Visible |
N/A (see all drawings) |
Other drawings (during drawing) |
HIDDEN |
VISIBLE (spectators see all canvases live) |
Gallery (all drawings, anonymous) |
Visible |
Visible |
Which drawing is whose |
HIDDEN until results |
VISIBLE |
Bid totals per drawing |
Visible (real-time) |
Visible |
Who bid what |
HIDDEN (only see totals) |
VISIBLE (see all individual bids) |
Own remaining currency |
Visible |
N/A |
getStateForPlayer(userId) during AUCTION:
interface MMPlayerAuctionState {
prompt: DrawingPrompt;
phase: 'AUCTION';
drawings: AuctionDrawing[];
myCurrency: number;
timeRemaining: number;
}
3.7 Join-in-Progress Logic¶
Policy: spectate_only
Drawings are created during the drawing phase. New players can’t draw after the fact, so they spectate from the gallery phase onward. They can enjoy the auction as spectators but cannot bid.
3.8 Reconnection Behavior¶
On reconnect:
During DRAWING: Player receives their stroke-in-progress (server has any previously submitted strokes; client re-renders).
During GALLERY/AUCTION: Player receives the gallery data and their current bid state.
Stroke data is preserved server-side even if the client disconnects mid-draw.
3.9 Awards¶
Award |
Condition |
Icon |
|---|---|---|
Minimalist Master |
Highest market value (winner) |
|
Patron of the Arts |
Player who spent the most total coins across all drawings |
|
One Stroke Wonder |
The drawing with the single highest-value stroke (subjective — highest market value with ≤ 3 strokes used) |
|
Undervalued Gem |
Drawing that received bids from the most different players |
|
Shrewd Investor |
Player who earned the highest investment bonus |
|
3.10 NPM Package Suggestions¶
Package |
Purpose |
Notes |
|---|---|---|
|
Convert stroke point data into beautiful SVG path commands with variable width and pressure sensitivity |
Lightweight (~5KB gzipped), used by Tldraw. Produces smooth, natural-looking strokes from raw point data. Client-side only — used to render strokes. |
|
Confetti animation on winner reveal |
Already in core spec dependencies. |
Drawing tech approach:
Client uses an HTML5
<canvas>element for the drawing surface.Raw input events (pointer/touch) are sampled into
Point[]arrays.perfect-freehandprocesses the points into smooth outline paths for rendering.The raw point data (not the rendered path) is sent to the server for storage and replication.
Other clients (gallery walk, spectator view) receive the raw points and render them identically using
perfect-freehand.
3.11 Client Component Structure¶
components/rmhbox/minigames/minimalist-masterpiece/
MinimalistMasterpieceGame.tsx # Main game component, phase router
DrawingCanvas.tsx # 5-stroke canvas with undo, color picker
ColorPalette.tsx # 8-color selection strip
StrokeCounter.tsx # "3/5 strokes used" indicator
GalleryCarousel.tsx # Swipeable gallery of all drawings
DrawingCard.tsx # Single drawing display with bid info
AuctionPanel.tsx # Bidding interface per drawing
BidControls.tsx # +/- bid buttons with currency display
MarketResultsScreen.tsx # Final rankings with drawing reveals
Mobile UI layout (DRAWING phase):
┌──────────────────────────────┐
│ Minimalist Masterpiece ⏱ 0:42│
├──────────────────────────────┤
│ "Draw: A house on a hill" │
├──────────────────────────────┤
│ ┌──────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ [Drawing Canvas] │ │ ← Touch/pointer drawing area
│ │ 400×400 │ │
│ │ │ │
│ │ │ │
│ └──────────────────────────┘ │
├──────────────────────────────┤
│ 🎨 ⚫⬜🔴🟢🔵🟡🟠🟣 │ ← Color palette
│ Strokes: 3/5 [↩ Undo] │
└──────────────────────────────┘
3.12 Constants¶
export const MM_PROMPT_REVEAL = 3;
export const MM_DRAWING_DURATION = 60;
export const MM_GALLERY_DURATION = 15;
export const MM_AUCTION_DURATION = 60;
export const MM_RESULTS_DURATION = 10;
export const MM_MAX_STROKES = 5;
export const MM_CANVAS_SIZE = 400;
export const MM_STROKE_WIDTH = 4;
export const MM_MIN_POINTS_PER_STROKE = 5;
export const MM_MAX_POINTS_PER_STROKE = 500;
export const MM_MIN_STROKE_DURATION = 100;
export const MM_COLOR_PALETTE = [
'#1a1a2e', // dark navy (near-black)
'#e0e0f0', // off-white
'#f87171', // red
'#4ade80', // green
'#60a5fa', // blue
'#fbbf24', // yellow
'#fb923c', // orange
'#c084fc', // purple
];
export const MM_STARTING_CURRENCY = 1000;
export const MM_BID_INCREMENT = 50;
export const MM_RANK_1 = 500;
export const MM_RANK_2 = 350;
export const MM_RANK_3 = 250;
export const MM_PARTICIPATION = 100;
export const MM_INVESTMENT_BONUS = 50;
3.13 Game Settings Schema (§12A)¶
Host-configurable settings for Minimalist Masterpiece. Defined in MinigameDefinition.settingsSchema.
Handlers read values via this.getSetting(key, CONSTANT_DEFAULT).
Key |
Type |
Label |
Description |
Default |
Constraints |
|---|---|---|---|---|---|
|
|
Drawing Duration (seconds) |
Time the artist has to draw a single prompt |
|
min: 20, max: 90, step: 5 |
|
|
Max Strokes |
Maximum number of brush strokes allowed per drawing |
|
min: 5, max: 30, step: 5 |
|
|
Auction Duration (seconds) |
Time for the bidding phase on each artwork |
|
min: 15, max: 60, step: 5 |
|
|
Starting Currency |
Amount of currency each player starts with |
|
min: 200, max: 1000, step: 50 |
|
|
Minimum Bid Increment |
Minimum amount above the current bid |
|
min: 10, max: 100, step: 5 |
Constant Mapping:
Setting Key |
Constant Override |
Usage |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.14 Game History¶
Game History Level: Full Asset Log
The stroke data and auction bids are the heart of Minimalist Masterpiece — revisiting the 5-stroke gallery and seeing who paid what for which artwork makes this log worth keeping in full.
initialState¶
interface MMInitialState {
prompt: string;
maxStrokes: number;
canvasSize: { width: number; height: number };
playerIds: string[];
startingCurrency: number;
auctionTimeLimitMs: number;
}
Actions Logged¶
Action Type |
Payload |
Recorded When |
|---|---|---|
|
|
Player completes a stroke |
|
|
Player undoes a stroke |
|
|
Player submits final drawing |
|
|
Gallery walk begins |
|
|
Player places a bid |
|
|
Bidding closes on a piece |
|
|
Final valuations computed |
Replay Value¶
Browse the gallery of 5-stroke creations for each prompt. The auction history shows who valued which art and how bidding wars played out. Compare the minimalist interpretations side-by-side — the constraint makes every stroke meaningful.
Note: The
GameLogalso includesgameSettings: GameSettingValuesat the top level (per core.md §12A.11), capturing the exact game settings used for this match.
3.15 History Display Configuration¶
Detail Component: MinimalistMasterpieceHistoryDetail
Renders the expanded game log as a gallery view:
Thumbnail previews of each player’s drawing (rendered from stroke data)
Prompt text shown alongside each drawing
Gallery vote results (who voted for whom)
Auction results with final bid amounts
Per-player score breakdown (gallery votes + auction bids)
Searchable Fields:
Field Key |
Label |
Extraction |
|---|---|---|
|
Drawing Prompts |
All prompt texts from |
Filterable Fields:
Field Key |
Label |
Type |
Details |
|---|---|---|---|
|
Won Auction |
boolean |
Whether user won any auction bids |
|
Gallery Votes Received |
range |
Number of votes user’s drawing received |
Summary Extractor:
getSummary: (log) => {
const prompt = log.actions.find(a => a.type === 'drawing_start');
return `Prompt: "${prompt?.payload.prompt ?? 'Unknown'}"`;
}
Component Structure:
MinimalistMasterpieceHistoryDetail.tsx
├── GalleryGrid (drawing thumbnails)
│ ├── DrawingCard (stroke render + prompt)
│ └── VoteBadge (gallery votes count)
├── AuctionResults (bids + winners)
└── Final scores summary
3.16 MinigameRenderer & Client-Server Wiring¶
MinigameRenderer Registration¶
The MinigameRenderer lazy-loads the Minimalist Masterpiece component:
const MINIGAME_COMPONENTS = {
'minimalist-masterpiece': lazy(() => import('./minigames/minimalist-masterpiece/MinimalistMasterpieceGame')),
// …other minigames
};
Client-Side Store Integration¶
The client store listens for server-pushed actions and updates local state accordingly:
useEffect(() => {
const handlers: Record<string, (payload: unknown) => void> = {
MM_PROMPT: (p) => dispatch({ type: 'MM_PROMPT', payload: p }),
MM_DRAWING_SUBMITTED: (p) => dispatch({ type: 'MM_DRAWING_SUBMITTED', payload: p }),
MM_GALLERY: (p) => dispatch({ type: 'MM_GALLERY', payload: p }),
MM_AUCTION_START: (p) => dispatch({ type: 'MM_AUCTION_START', payload: p }),
MM_BID_UPDATE: (p) => dispatch({ type: 'MM_BID_UPDATE', payload: p }),
MM_BID_BROADCAST: (p) => dispatch({ type: 'MM_BID_BROADCAST', payload: p }),
MM_RESULTS: (p) => dispatch({ type: 'MM_RESULTS', payload: p }),
TIMER_TICK: (p) => dispatch({ type: 'TIMER_TICK', payload: p }),
};
Object.entries(handlers).forEach(([ev, fn]) => socket.on(ev, fn));
return () => { Object.keys(handlers).forEach((ev) => socket.off(ev)); };
}, [socket, dispatch]);
Client-Side Input Dispatch¶
Players submit drawings and place bids:
// Submit a completed drawing
socket.emit('SUBMIT_DRAWING', { strokes }); // strokes: Stroke[]
// Place a bid during the auction
socket.emit('PLACE_BID', { drawingId, amount });
Server-Side Handler Registration¶
The server registers the game handler at startup:
import { MinimalistMasterpieceGame } from './minigames/minimalist-masterpiece/MinimalistMasterpieceGame';
MINIGAME_SERVER_REGISTRY.set('minimalist-masterpiece', MinimalistMasterpieceGame);
Sound Effect Integration¶
Event |
Sound |
Notes |
|---|---|---|
Prompt revealed |
|
Drawing phase begins |
Drawing submitted |
|
Confirms submission |
Gallery shown |
|
Gallery walk transition |
Auction start |
|
Bidding phase begins |
Bid placed |
|
Confirms the bid |
Bid broadcast (high value) |
|
Highlights a significant bid |
Results |
|
Final rankings revealed |
Spectator Rendering¶
During the drawing phase, spectators see all players’ canvases live. During the auction, they see all bids. The component checks spectator status and renders a multi-canvas gallery view during the drawing phase.
4. Emoji Cinema¶
4.1 Overview¶
Field |
Value |
|---|---|
ID |
|
Display Name |
Emoji Cinema |
Category |
|
Icon |
|
Min Players |
3 |
Max Players |
12 |
Estimated Duration |
180 seconds |
Supports Teams |
No (rotating Producer role) |
Join-in-Progress |
|
Tags |
|
4.2 Game Concept¶
“Reverse Charades” using only emojis. One player (the Producer) receives a movie title and must describe it using a restricted emoji-only keyboard. The other players (Audience) race to guess the movie title. The Producer earns points based on how quickly the Audience guesses. Roles rotate so each player gets a turn as Producer.
4.3 Detailed Mechanics¶
4.3.1 Round Structure¶
The game cycles through each player as the Producer. Total rounds = number of players (each player is Producer once).
Phase |
Duration |
Description |
|---|---|---|
Producer Assignment |
2s |
Show who the new Producer is |
Emoji Construction |
45s |
Producer places emojis; Audience guesses |
Round Results |
5s |
Reveal answer, show who guessed first |
Transition |
1s |
Next Producer |
Total game time: ~players × 53s. For 6 players: ~318s ≈ 5.3 minutes (consider capping at EC_MAX_ROUNDS, default: 6 or player count, whichever is smaller).
4.3.2 Movie Selection¶
Movies come from a curated database (data/rmhbox/emoji-cinema/movies.json):
interface MovieEntry {
id: string;
title: string; // exact title for matching
titleNormalized: string; // lowercase, no articles, for fuzzy matching
alternativeTitles: string[]; // accepted alternate titles
year: number;
genre: string[];
difficulty: 'easy' | 'medium' | 'hard';
popularity: number; // 1-100 (higher = more well-known)
}
The server selects movies with:
Popularity ≥
EC_MIN_POPULARITY(default: 40) so players are likely to know the movie.A mix of difficulties across rounds.
No repeats within the lobby session.
For each round, the Producer is shown the movie title. The Audience never sees it until the answer reveal.
4.3.3 Emoji Keyboard¶
The Producer’s input is restricted to an emoji-only keyboard. No text input.
The emoji palette contains approximately 200 curated emojis organized into categories (People, Animals, Nature, Food, Objects, Symbols, Activities, Travel).
The emoji palette is searchable via a text filter (Producer types a keyword to filter emojis, e.g., typing “fire” shows 🔥).
The keyboard is identical to the search filter used in many emoji pickers — the Producer does NOT type text that the Audience sees. The Audience only sees emojis.
Producer’s display area:
A horizontal “emoji sentence” bar at the top where selected emojis appear in order.
Maximum
EC_MAX_EMOJIS(default: 12) emojis per round.Emojis can be reordered via drag-and-drop.
Emojis can be removed (tap to deselect from the sentence).
As the Producer adds emojis, they are broadcast live to the Audience in real-time (the Audience sees emojis appearing one by one as the Producer selects them).
4.3.4 Guessing¶
The Audience types text guesses in a standard text input:
Each guess is submitted by pressing Enter.
The server validates guesses using fuzzy matching (
fuse.jsfrom core spec) against the movie title and alternative titles.Match threshold:
EC_FUZZY_MATCH_THRESHOLD(default: 0.80).A guess that fuzzy-matches is accepted as correct.
The server responds to each guess with:
✅ Correct — the round ends immediately.
🔥 Close — fuzzy score is between
EC_CLOSE_THRESHOLD(0.60) andEC_FUZZY_MATCH_THRESHOLD(0.80). Player sees “Close!!” hint but the round continues.❌ Wrong — no match.
Maximum guesses per player per round:
EC_MAX_GUESSES_PER_PLAYER(default: 15).Guesses are case-insensitive and trimmed.
“The” and “A” articles are stripped for matching purposes.
4.3.5 Scoring¶
Who |
Score |
Condition |
|---|---|---|
Producer |
|
Someone guesses correctly |
Producer |
0 |
No one guesses correctly (timeout) |
First correct guesser |
|
First to guess correctly |
Second correct guesser |
|
Second to guess correctly (if multiple guess on the same tick, server uses submission timestamp) |
Other correct guessers |
|
|
Wrong guessers |
0 |
No penalty for wrong guesses |
Producer scoring defaults:
EC_PRODUCER_BASE= 100 (guaranteed if someone guesses correctly).EC_PRODUCER_SPEED_BONUS= 10 points × seconds remaining when the first correct guess arrives.Maximum Producer score per round: 100 + 10 × 45 = 550.
4.3.6 Close Guess Broadcast¶
When any player submits a “Close” guess, the server broadcasts EC_CLOSE_GUESS to all players (including the guesser’s name but NOT their guess text). This creates tension, “someone is close!” moments.
After the round ends, all guesses are revealed in the round results.
4.4 Server-Side State Schema¶
interface EmojiCinemaState {
rounds: ECRoundData[]; // pre-selected movies for all rounds
currentRound: number; // 0-indexed
totalRounds: number;
producerOrder: string[]; // userIds in Producer rotation order
phase: ECPhase;
// Current round state
currentProducerUserId: string;
currentMovie: MovieEntry;
emojiSequence: string[]; // emojis placed by Producer (live-updated)
// Guesses
guesses: Map<string, ECPlayerGuesses>; // userId → their guesses
correctGuessers: CorrectGuesser[]; // ordered by time
closeGuessCount: number;
// Cumulative
playerScores: Map<string, number>;
// Timer
phaseStartedAt: number;
phaseEndsAt: number;
}
type ECPhase = 'PRODUCER_ASSIGNMENT' | 'EMOJI_CONSTRUCTION' | 'ROUND_RESULTS' | 'TRANSITION';
interface ECRoundData {
movie: MovieEntry;
producerUserId: string;
}
interface ECPlayerGuesses {
userId: string;
guesses: Array<{
text: string;
result: 'correct' | 'close' | 'wrong';
timestamp: number;
}>;
}
interface CorrectGuesser {
userId: string;
userName: string;
guessText: string;
timestamp: number;
rank: number; // 1 = first, 2 = second, etc.
}
4.5 WebSocket Event Map¶
Client → Server¶
Action |
Payload |
Who Can Send |
Description |
|---|---|---|---|
|
|
Producer only |
Add an emoji at a position in the sequence |
|
|
Producer only |
Remove an emoji from the sequence |
|
|
Producer only |
Drag-reorder emojis |
|
|
Audience only |
Submit a movie title guess |
Zod schemas:
const AddEmojiSchema = z.object({
emoji: z.string().min(1).max(10), // emoji can be multi-codepoint
position: z.number().int().min(0).max(11), // max 12 emojis, 0-indexed
});
const RemoveEmojiSchema = z.object({
position: z.number().int().min(0).max(11),
});
const ReorderEmojiSchema = z.object({
fromIndex: z.number().int().min(0).max(11),
toIndex: z.number().int().min(0).max(11),
});
const SubmitGuessSchema = z.object({
guess: z.string().min(1).max(200).transform(s => s.trim()),
});
Server → Client (Game Actions)¶
Action Type |
Payload |
Sent To |
Description |
|---|---|---|---|
|
|
All (lobby) |
New Producer announced |
|
|
Producer only |
Secret movie title revealed to Producer |
|
|
All (lobby) |
Emoji sequence changed (live) |
|
|
Guessing player only |
Guess feedback |
|
|
All (lobby) |
Someone’s guess was close (not the guess text) |
|
|
All (lobby) |
Someone guessed correctly |
|
|
All (lobby) |
Round ended (correct guess or timeout) |
|
|
All (lobby) |
How many guesses a player has made (not the content) |
|
|
All (lobby) |
Emitted at the start of each timed phase (CONSTRUCTION) via |
|
|
All (lobby) |
Standard timer (every 1s during all timed phases) via |
|
|
All (lobby) |
Sub-round counter update (e.g. “Round 2/6”) via |
4.6 Information Masking¶
Data |
Producer View |
Audience View |
Spectator View |
|---|---|---|---|
Movie title |
VISIBLE |
HIDDEN until round ends |
VISIBLE |
Emoji sequence (live) |
Visible (they’re building it) |
Visible (appears live) |
Visible |
Own guesses |
N/A (can’t guess) |
Visible |
N/A |
Other players’ guess text |
N/A |
HIDDEN |
VISIBLE |
Close/correct notifications |
Visible (notification) |
Visible (notification) |
Visible |
Guess counts per player |
Visible |
Visible |
Visible |
getStateForPlayer(userId) when userId is the Producer:
interface ECProducerState {
phase: ECPhase;
currentRound: number;
totalRounds: number;
movieTitle: string; // the secret!
movieYear: number;
emojiSequence: string[];
timeRemaining: number;
correctGuessers: CorrectGuesser[];
closeGuessCount: number;
guessCountsPerPlayer: Array<{ userId: string; userName: string; count: number }>;
scores: Array<{ userId: string; userName: string; totalScore: number }>;
}
getStateForPlayer(userId) when userId is in the Audience:
interface ECAudienceState {
phase: ECPhase;
currentRound: number;
totalRounds: number;
producerUserId: string;
producerName: string;
emojiSequence: string[];
timeRemaining: number;
myGuesses: Array<{ text: string; result: 'correct' | 'close' | 'wrong' }>;
correctGuessers: CorrectGuesser[];
closeGuessCount: number;
guessCountsPerPlayer: Array<{ userId: string; userName: string; count: number }>;
scores: Array<{ userId: string; userName: string; totalScore: number }>;
}
getStateForSpectator() returns:
Full state including movie title, all guesses from all players, and the emoji sequence. Spectators get the “omniscient director” experience.
4.7 Join-in-Progress Logic¶
Policy: join_next_subround
Players who join mid-game become spectators until the current round ends. At the start of the next round, they join the Audience pool. They do NOT get a Producer turn unless the game hasn’t rotated to them yet and additional rounds remain. If all original players have been Producer, late joiners just participate as Audience for remaining rounds.
4.8 Reconnection Behavior¶
On reconnect:
Producer receives the movie title, current emoji sequence, and guess status.
Audience receives the emoji sequence, their own guesses so far, and timer.
All state is preserved server-side; the client just needs to re-render.
4.9 Player Disconnect Mid-Game¶
If the Producer disconnects: Wait
EC_PRODUCER_DISCONNECT_WAIT(default: 10s). If they don’t reconnect, the round is skipped (no points awarded for that round). Move to the next round.If an Audience member disconnects: No impact on the round. They miss their chance to guess.
4.10 Awards¶
Award |
Condition |
Icon |
|---|---|---|
Movie Buff |
Most correct guesses across all rounds |
|
Emoji Picasso |
Producer whose round was guessed the fastest (best emoji description) |
|
Stumper |
Producer whose movie was never guessed |
|
Speed Guesser |
Fastest correct guess (earliest in any round) |
|
Close but No Cigar |
Player with the most “Close” guesses that never converted to correct |
|
4.11 NPM Package Suggestions¶
Package |
Purpose |
Notes |
|---|---|---|
|
Fuzzy string matching for movie title guesses |
Already in core spec. Used with threshold 0.80 for correct, 0.60–0.80 for “close.” |
|
Feature-rich emoji picker component with search, categories, and skin tone support |
Well-maintained, React-friendly, used by Slack. ~30KB gzipped. Client-side only. The Producer’s emoji keyboard should use this. |
Alternative to emoji-mart: If bundle size is a concern, use a minimal custom emoji picker with the curated 200-emoji subset. The emojis can be stored as a static JSON array with category labels, and a simple text filter replaces the search functionality. This avoids the full emoji-mart bundle.
4.12 Client Component Structure¶
components/rmhbox/minigames/emoji-cinema/
EmojiCinemaGame.tsx # Main game component, phase router
EmojiKeyboard.tsx # Emoji picker (searchable, categorized)
EmojiSentence.tsx # Display bar for the emoji sequence (draggable)
GuessInput.tsx # Text input for Audience guesses
GuessHistory.tsx # Scrollable list of own guesses with result indicators
ProducerView.tsx # Producer's full interface (movie + emoji builder)
AudienceView.tsx # Audience's interface (emoji display + guess input)
RoundResults.tsx # Movie reveal + scores
MovieReveal.tsx # Animated movie title reveal with emoji recap
Mobile UI layout (EMOJI_CONSTRUCTION phase, Audience view):
┌──────────────────────────────┐
│ Emoji Cinema Round 3/6 │
├──────────────────────────────┤
│ 🎬 Alice is the Producer │
├──────────────────────────────┤
│ │
│ 🦁 👑 🌍 🎵 │ ← Live emoji sequence (grows as Producer adds)
│ │
├──────────────────────────────┤
│ Your guesses: │
│ "The Lion King" ✅ │ ← Guess history
│ "Simba" ❌ │
│ "Madagascar" ❌ │
├──────────────────────────────┤
│ ┌────────────────────┬─────┐ │
│ │ Guess the movie... │ → │ │ ← Text input
│ └────────────────────┴─────┘ │
│ ⏱ 0:28 │ Score: 450 │
└──────────────────────────────┘
Mobile UI layout (EMOJI_CONSTRUCTION phase, Producer view):
┌──────────────────────────────┐
│ Emoji Cinema ⏱ 0:35 │
├──────────────────────────────┤
│ 🎥 Your Movie: │
│ "The Lion King" (1994) │
├──────────────────────────────┤
│ Your emojis: │
│ 🦁 👑 🌍 🎵 [max 12] │ ← Draggable, tap to remove
├──────────────────────────────┤
│ 🔍 Search emojis... │
│ ┌──────────────────────────┐ │
│ │ 🦁 🐯 🐱 🐺 🦊 🐻 │ │ ← Emoji grid (scrollable)
│ │ 🐼 🐨 🐵 🐸 🐔 🐧 │ │
│ │ 🐠 🐳 🦈 🐙 🐛 🦋 │ │
│ └──────────────────────────┘ │
├──────────────────────────────┤
│ 2 guesses so far │ 0 close │
└──────────────────────────────┘
4.13 Constants¶
export const EC_MAX_ROUNDS = 6; // cap even if more players
export const EC_PRODUCER_ASSIGNMENT = 2;
export const EC_ROUND_DURATION = 45;
export const EC_ROUND_RESULTS = 5;
export const EC_TRANSITION = 1;
export const EC_MAX_EMOJIS = 12;
export const EC_MAX_GUESSES_PER_PLAYER = 15;
export const EC_MAX_GUESS_LENGTH = 200;
export const EC_FUZZY_MATCH_THRESHOLD = 0.80; // correct guess
export const EC_CLOSE_THRESHOLD = 0.60; // "close" hint
export const EC_MIN_POPULARITY = 40;
export const EC_PRODUCER_BASE = 100;
export const EC_PRODUCER_SPEED_BONUS = 10;
export const EC_FIRST_GUESS = 300;
export const EC_SECOND_GUESS = 150;
export const EC_OTHER_GUESS = 75;
export const EC_PRODUCER_DISCONNECT_WAIT = 10;
export const EC_EMOJI_PALETTE_SIZE = 200;
4.14 Game Settings Schema (§12A)¶
Host-configurable settings for Emoji Cinema. Defined in MinigameDefinition.settingsSchema.
Handlers read values via this.getSetting(key, CONSTANT_DEFAULT).
Key |
Type |
Label |
Description |
Default |
Constraints |
|---|---|---|---|---|---|
|
|
Number of Rounds |
Number of emoji-encoding rounds to play |
|
min: 2, max: 6, step: 1 |
|
|
Encoding Duration (seconds) |
Time the encoder has to build their emoji sequence |
|
min: 20, max: 90, step: 5 |
|
|
Max Emojis |
Maximum number of emojis the encoder can use |
|
min: 3, max: 8, step: 1 |
|
|
Guesses Per Player |
Maximum guesses each player can submit per round |
|
min: 1, max: 5, step: 1 |
Constant Mapping:
Setting Key |
Constant Override |
Usage |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
4.15 Anti-Cheat Notes¶
The movie title is ONLY sent to the Producer’s socket. Audience players never receive it until
EC_ROUND_OVER.Guess text from other players is never sent to anyone during the guessing phase (only the count and close/correct notifications without the actual text).
The emoji sequence is broadcast live — no way for the Producer to communicate text, only emojis.
The curated emoji palette prevents the Producer from using flag emojis or letter emojis (🅰️ 🅱️ etc.) to spell out the title. These are excluded from the palette.
Maximum
EC_MAX_EMOJISprevents emoji spam.Maximum
EC_MAX_GUESSES_PER_PLAYERprevents brute-force guessing.
4.16 Game History¶
Game History Level: Summary Log
The emoji sequences and guess highlights are the memorable moments — full keystroke logs of every guess attempt aren’t needed. The summary captures each round’s composition and the key guessing moments.
initialState¶
interface ECInitialState {
totalRounds: number;
maxEmojis: number;
maxGuessesPerPlayer: number;
playerIds: string[];
moviePool: string[]; // candidate titles for this session
}
Actions Logged¶
Action Type |
Payload |
Recorded When |
|---|---|---|
|
|
Round begins (title logged server-side) |
|
|
Producer places an emoji |
|
|
A guess is flagged as close |
|
|
Someone guesses correctly |
|
|
Round ends with no correct guess |
|
|
Round scoring summary |
Replay Value¶
See each round’s emoji composition alongside the movie title and marvel at how creative (or cryptic) the Producer was. The close-guess log is comedy gold — near-misses and creative interpretations are half the fun.
Note: The
GameLogalso includesgameSettings: GameSettingValuesat the top level (per core.md §12A.11), capturing the exact game settings used for this match.
4.17 History Display Configuration¶
Detail Component: EmojiCinemaHistoryDetail
Renders the expanded game log as a round-by-round review:
Emoji sequence displayed with the target movie title
Guessing timeline showing each player’s guesses and correctness
Difficulty rating per round
Creator identity for each emoji sequence
Score breakdown per round
Searchable Fields:
Field Key |
Label |
Extraction |
|---|---|---|
|
Movie Titles |
All movie titles from |
|
Guesses |
All player guesses from |
|
Emoji Sequences |
Emoji strings from |
Filterable Fields:
Field Key |
Label |
Type |
Details |
|---|---|---|---|
|
Was Emoji Creator |
boolean |
Whether user created the emoji sequence |
|
Guessed Correctly |
boolean |
Whether user guessed the movie |
|
Difficulty |
select |
|
Summary Extractor:
getSummary: (log) => {
const rounds = log.actions.filter(a => a.type === 'round_start');
return `${rounds.length} rounds — Movie emoji challenge`;
}
Component Structure:
EmojiCinemaHistoryDetail.tsx
├── RoundCard (per round)
│ ├── EmojiSequence (the emoji clue)
│ ├── MovieTitle (correct answer reveal)
│ ├── GuessTimeline (player guesses + timing)
│ └── CreatorBadge (who made the sequence)
└── Final scores summary
4.18 MinigameRenderer & Client-Server Wiring¶
MinigameRenderer Registration¶
The MinigameRenderer lazy-loads the Emoji Cinema component:
const MINIGAME_COMPONENTS = {
'emoji-cinema': lazy(() => import('./minigames/emoji-cinema/EmojiCinemaGame')),
// …other minigames
};
Client-Side Store Integration¶
The client store listens for server-pushed actions and updates local state accordingly:
useEffect(() => {
const handlers: Record<string, (payload: unknown) => void> = {
EC_PRODUCER_ASSIGNED: (p) => dispatch({ type: 'EC_PRODUCER_ASSIGNED', payload: p }),
EC_MOVIE_ASSIGNED: (p) => dispatch({ type: 'EC_MOVIE_ASSIGNED', payload: p }),
EC_EMOJI_UPDATED: (p) => dispatch({ type: 'EC_EMOJI_UPDATED', payload: p }),
EC_GUESS_RESULT: (p) => dispatch({ type: 'EC_GUESS_RESULT', payload: p }),
EC_CLOSE_GUESS: (p) => dispatch({ type: 'EC_CLOSE_GUESS', payload: p }),
EC_CORRECT_GUESS: (p) => dispatch({ type: 'EC_CORRECT_GUESS', payload: p }),
EC_ROUND_OVER: (p) => dispatch({ type: 'EC_ROUND_OVER', payload: p }),
EC_GUESS_COUNT: (p) => dispatch({ type: 'EC_GUESS_COUNT', payload: p }),
TIMER_TICK: (p) => dispatch({ type: 'TIMER_TICK', payload: p }),
};
Object.entries(handlers).forEach(([ev, fn]) => socket.on(ev, fn));
return () => { Object.keys(handlers).forEach((ev) => socket.off(ev)); };
}, [socket, dispatch]);
Client-Side Input Dispatch¶
The Producer manages the emoji sequence while the Audience submits guesses:
// Producer adds an emoji (Producer only)
socket.emit('ADD_EMOJI', { emoji, position });
// Producer removes an emoji (Producer only)
socket.emit('REMOVE_EMOJI', { position });
// Producer reorders emojis (Producer only)
socket.emit('REORDER_EMOJI', { fromIndex, toIndex });
// Audience member submits a guess (Audience only)
socket.emit('SUBMIT_GUESS', { guess });
Server-Side Handler Registration¶
The server registers the game handler at startup:
import { EmojiCinemaGame } from './minigames/emoji-cinema/EmojiCinemaGame';
MINIGAME_SERVER_REGISTRY.set('emoji-cinema', EmojiCinemaGame);
Sound Effect Integration¶
Event |
Sound |
Notes |
|---|---|---|
Producer assigned |
|
New round begins |
Emoji updated |
|
Emoji placed or removed |
Close guess |
|
A guess was close but not correct |
Correct guess |
|
Someone guessed the movie |
Round over |
|
Round scoring summary |
Timer warning |
|
Final seconds of the timer |
Spectator Rendering¶
Spectators have an omniscient view — they see the movie title, all guesses from all players, and the emoji composition in real-time. The component renders a split view showing the title, the emoji sequence, and a scrolling guess feed.
End of Minigame Specifications Part 2