create-smore-game 2.2.0 → 2.4.0

package/README.md

@@ -0,0 +1,159 @@
+# create-smore-game
+
+Scaffold a multiplayer party game for the S'MORE platform.
+
+---
+
+## Quick Start
+
+```bash
+npx create-smore-game my-game
+cd my-game
+npm install
+npm run dev
+```
+
+The CLI prompts you for two choices:
+
+```
+  create-smore-game
+
+  Screen (TV) template:
+    React + Phaser
+    React only
+    Vanilla JS
+
+  Controller (phone) template:
+    React
+    Vanilla JS
+```
+
+After answering, your project is ready to run.
+
+---
+
+## What You Get
+
+```
+my-game/
+├── screen/                    # TV/display — game logic lives here
+│   ├── src/
+│   │   ├── App.tsx            # Main game component
+│   │   └── __tests__/         # Game tests with vitest
+│   ├── package.json
+│   └── vite.config.ts
+├── controller/                # Phone/player input — stateless display + input
+│   ├── src/
+│   │   ├── App.tsx            # Controller UI
+│   │   └── __tests__/         # Controller tests
+│   ├── package.json
+│   └── vite.config.ts
+├── dev/
+│   ├── server.js              # Local dev server with Socket.IO
+│   ├── harness.html           # Test screen + controllers together
+│   └── controller-page.html
+├── game.json                  # Game metadata (title, player count, etc.)
+├── .env.example
+└── package.json               # npm workspaces root
+```
+
+---
+
+## Development
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start dev server (screen + controller + harness) |
+| `npm run dev:screen` | Screen only |
+| `npm run dev:controller` | Controller only |
+| `npm run build` | Production build |
+| `npm run zip` | Build + package as `game.zip` for deployment |
+
+### Dev Harness
+
+Running `npm run dev` starts a local Socket.IO server and opens a harness page with the screen and one or more controller iframes side by side. You can add and remove players directly in the browser to test the full game flow without a real device.
+
+---
+
+## Architecture: Stateless Controller Pattern
+
+S'MORE games follow a strict separation of concerns:
+
+- **Screen (TV)** — owns all game state and logic. It is the single source of truth.
+- **Controller (Phone)** — a stateless input device. It only renders what the Screen tells it to render, and only sends raw user input back.
+
+```
+Screen  →  "Show vote UI with options A, B, C"  →  Controller renders buttons
+Controller  →  "Player tapped A"  →  Screen processes vote, updates state
+Screen  →  "Show results: A won"  →  Controller renders results
+```
+
+This pattern keeps game logic centralized and makes controllers trivially simple to implement. For full API details, see the `@smoregg/sdk` documentation.
+
+---
+
+## Templates
+
+### Screen Templates
+
+| Template | Best for |
+|---|---|
+| **React + Phaser** | Graphics-heavy games — sprites, animations, physics |
+| **React** | UI-based games — cards, voting, text prompts |
+| **Vanilla JS** | Minimal projects with no framework dependency |
+
+### Controller Templates
+
+| Template | Best for |
+|---|---|
+| **React** | Recommended for most games |
+| **Vanilla JS** | Lightweight alternative |
+
+---
+
+## Game Metadata
+
+`game.json` at the project root describes your game to the S'MORE platform:
+
+```json
+{
+  "id": "my-game",
+  "title": "My Game",
+  "description": "",
+  "version": "0.1.0",
+  "minPlayers": 2,
+  "maxPlayers": 8,
+  "categories": ["party"]
+}
+```
+
+Edit this file before submitting. The `id` must be unique and contain only lowercase letters, numbers, and hyphens.
+
+---
+
+## Building and Deploying
+
+```bash
+npm run zip
+```
+
+This builds both the screen and controller workspaces, copies `game.json` into the output, and packages everything as `game.zip`. Submit this file to the S'MORE platform to deploy your game.
+
+---
+
+## SDK Documentation
+
+The scaffolded project uses `@smoregg/sdk` for all platform communication. See the SDK package for the full API reference, including:
+
+- Connecting screen and controller
+- Sending and receiving typed events
+- Managing player sessions
+- Testing utilities (`createMockScreen`, `createMockController`)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-smore-game",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "bin": {
     "create-smore-game": "./index.js"

package/templates.js

@@ -3,7 +3,7 @@
 // pnpm-workspace.yaml is no longer generated.
 // npm workspaces are configured in root package.json instead.
 
-const SDK_VERSION = '^2.2.0';
+const SDK_VERSION = '^2.3.0';
 
 export function rootPackageJson(name) {
   return JSON.stringify(
@@ -35,6 +35,160 @@ export function envExample() {
 `;
 }
 
+// ─── Test file templates ───
+
+export function screenTestFile() {
+  return `import { describe, it, expect, beforeEach } from 'vitest';
+import { createMockScreen } from '@smoregg/sdk/testing';
+import type { GameEvents } from '../App';
+
+describe('Game Screen', () => {
+  let screen: ReturnType<typeof createMockScreen<GameEvents>>;
+
+  beforeEach(() => {
+    screen = createMockScreen<GameEvents>({ autoReady: true });
+  });
+
+  it('should broadcast score-update when player taps', async () => {
+    await screen.ready;
+
+    // Simulate a tap from player 0
+    screen.simulateEvent('tap', 0, { timestamp: Date.now() });
+
+    // Verify the screen would broadcast the score
+    // (Your game logic goes here)
+  });
+
+  it('should handle player reconnection', async () => {
+    await screen.ready;
+
+    // Simulate player reconnect
+    screen.simulateControllerReconnect(0);
+
+    // In a stateless controller pattern, Screen should re-push
+    // the current view state to the reconnecting controller
+  });
+});
+`;
+}
+
+export function controllerTestFile() {
+  return `import { describe, it, expect, beforeEach } from 'vitest';
+import { createMockController } from '@smoregg/sdk/testing';
+import type { GameEvents } from '../App';
+
+describe('Game Controller', () => {
+  let controller: ReturnType<typeof createMockController<GameEvents>>;
+
+  beforeEach(() => {
+    controller = createMockController<GameEvents>({ autoReady: true });
+  });
+
+  it('should send tap event on user input', async () => {
+    await controller.ready;
+
+    controller.send('tap', { timestamp: Date.now() });
+
+    const sends = controller.getSends();
+    expect(sends).toHaveLength(1);
+    expect(sends[0].event).toBe('tap');
+  });
+
+  it('should update display when Screen pushes score', async () => {
+    await controller.ready;
+
+    // Simulate Screen pushing a score update
+    controller.simulateEvent('score-update', { score: 42 });
+
+    // Your rendering logic would update based on this event
+  });
+});
+`;
+}
+
+export function screenTestFileVanilla() {
+  return `import { describe, it, beforeEach } from 'vitest';
+import { createMockScreen } from '@smoregg/sdk/testing';
+
+interface GameEvents {
+  // Screen → Controller (view state)
+  'score-update': { score: number };
+  'personal-message': { text: string };
+  // Controller → Screen (input)
+  'tap': { timestamp: number };
+}
+
+describe('Game Screen', () => {
+  let screen: ReturnType<typeof createMockScreen<GameEvents>>;
+
+  beforeEach(() => {
+    screen = createMockScreen<GameEvents>({ autoReady: true });
+  });
+
+  it('should broadcast score-update when player taps', async () => {
+    await screen.ready;
+
+    // Simulate a tap from player 0
+    screen.simulateEvent('tap', 0, { timestamp: Date.now() });
+
+    // Verify the screen would broadcast the score
+    // (Your game logic goes here)
+  });
+
+  it('should handle player reconnection', async () => {
+    await screen.ready;
+
+    // Simulate player reconnect
+    screen.simulateControllerReconnect(0);
+
+    // In a stateless controller pattern, Screen should re-push
+    // the current view state to the reconnecting controller
+  });
+});
+`;
+}
+
+export function controllerTestFileVanilla() {
+  return `import { describe, it, expect, beforeEach } from 'vitest';
+import { createMockController } from '@smoregg/sdk/testing';
+
+interface GameEvents {
+  // Screen → Controller (view state)
+  'score-update': { score: number };
+  'personal-message': { text: string };
+  // Controller → Screen (input)
+  'tap': { timestamp: number };
+}
+
+describe('Game Controller', () => {
+  let controller: ReturnType<typeof createMockController<GameEvents>>;
+
+  beforeEach(() => {
+    controller = createMockController<GameEvents>({ autoReady: true });
+  });
+
+  it('should send tap event on user input', async () => {
+    await controller.ready;
+
+    controller.send('tap', { timestamp: Date.now() });
+
+    const sends = controller.getSends();
+    expect(sends).toHaveLength(1);
+    expect(sends[0].event).toBe('tap');
+  });
+
+  it('should update display when Screen pushes score', async () => {
+    await controller.ready;
+
+    // Simulate Screen pushing a score update
+    controller.simulateEvent('score-update', { score: 42 });
+
+    // Your rendering logic would update based on this event
+  });
+});
+`;
+}
+
 // ─── Screen templates ───
 
 const screenTsconfig = JSON.stringify(
@@ -130,6 +284,7 @@ export function screenReactPhaser(gameId) {
         scripts: {
           dev: "vite",
           build: "tsc && vite build",
+          test: "vitest run",
         },
         dependencies: {
           react: "^18.3.1",
@@ -143,6 +298,7 @@ export function screenReactPhaser(gameId) {
           "@vitejs/plugin-react": "^4.3.0",
           typescript: "^5.5.0",
           vite: "^5.4.0",
+          vitest: "^1.6.0",
         },
       },
       null,
@@ -163,8 +319,10 @@ import Phaser from 'phaser';
 import { GameScene } from './scenes/GameScene';
 
 interface GameEvents {
+  // Screen → Controller (view state)
   'score-update': { score: number };
   'personal-message': { text: string };
+  // Controller → Screen (input)
   'tap': { timestamp: number };
 }
 
@@ -185,6 +343,7 @@ export function App() {
   const gameRef = useRef<Phaser.Game | null>(null);
   const [roomCode, setRoomCode] = useState('');
   const [controllers, setControllers] = useState<ControllerInfo[]>([]);
+  const [tapCount, setTapCount] = useState(0);
 
   useEffect(() => {
     let mounted = true;
@@ -238,6 +397,12 @@ export function App() {
       console.log('Player', playerIndex, 'tapped:', data);
       // Forward input to Phaser scene
       gameRef.current?.events.emit('player-tap', { playerIndex, ...data });
+      // Broadcast updated score back to controllers (Screen is source of truth)
+      setTapCount((prev) => {
+        const newCount = prev + 1;
+        screen.broadcast('score-update', { score: newCount });
+        return newCount;
+      });
     });
 
     return () => {
@@ -305,6 +470,7 @@ export class GameScene extends Phaser.Scene {
   }
 }
 `,
+    "src/__tests__/game.test.ts": screenTestFile(),
   };
 }
 
@@ -321,6 +487,7 @@ export function screenReact(gameId) {
         scripts: {
           dev: "vite",
           build: "tsc && vite build",
+          test: "vitest run",
         },
         dependencies: {
           react: "^18.3.1",
@@ -333,6 +500,7 @@ export function screenReact(gameId) {
           "@vitejs/plugin-react": "^4.3.0",
           typescript: "^5.5.0",
           vite: "^5.4.0",
+          vitest: "^1.6.0",
         },
       },
       null,
@@ -351,8 +519,10 @@ import type { Screen, ControllerInfo, GameResults } from '@smoregg/sdk';
 import { useEffect, useRef, useState } from 'react';
 
 interface GameEvents {
+  // Screen → Controller (view state)
   'score-update': { score: number };
   'personal-message': { text: string };
+  // Controller → Screen (input)
   'tap': { timestamp: number };
 }
 
@@ -373,7 +543,7 @@ export function App() {
   const [roomCode, setRoomCode] = useState('');
   const [controllers, setControllers] = useState<ControllerInfo[]>([]);
   const [taps, setTaps] = useState<{ playerIndex: number; time: number }[]>([]);
-  const [customStates, setCustomStates] = useState<Record<number, Record<string, unknown>>>({});
+  const [tapCount, setTapCount] = useState(0);
 
   useEffect(() => {
     let mounted = true;
@@ -413,11 +583,6 @@ export function App() {
       setControllers([...screen.controllers]);
     });
 
-    screen.onCustomStateChange((playerIndex, state) => {
-      if (!mounted) return;
-      setCustomStates((prev) => ({ ...prev, [playerIndex]: state }));
-    });
-
     screenRef.current = screen;
 
     // Use screen.on(event, handler) / screen.off(event, handler) for dynamic event listeners.
@@ -425,6 +590,12 @@ export function App() {
     screen.on('tap', (playerIndex, data) => {
       if (!mounted) return;
       setTaps((prev) => [...prev.slice(-9), { playerIndex, time: Date.now() }]);
+      // Broadcast updated score back to controllers (Screen is source of truth)
+      setTapCount((prev) => {
+        const newCount = prev + 1;
+        screen.broadcast('score-update', { score: newCount });
+        return newCount;
+      });
     });
 
     return () => {
@@ -434,11 +605,6 @@ export function App() {
     };
   }, []);
 
-  // Example: send score update to all players
-  const handleBroadcastScore = () => {
-    screenRef.current?.broadcast('score-update', { score: 100 });
-  };
-
   // Example: send to specific player
   const handleSendToPlayer = (playerIndex: number) => {
     screenRef.current?.sendToController(playerIndex, 'personal-message', { text: 'Hello!' });
@@ -476,6 +642,7 @@ export function App() {
   );
 }
 `,
+    "src/__tests__/game.test.ts": screenTestFile(),
   };
 }
 
@@ -492,6 +659,7 @@ export function screenVanilla(gameId) {
         scripts: {
           dev: "vite",
           build: "tsc && vite build",
+          test: "vitest run",
         },
         dependencies: {
           "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
@@ -499,6 +667,7 @@ export function screenVanilla(gameId) {
         devDependencies: {
           typescript: "^5.5.0",
           vite: "^5.4.0",
+          vitest: "^1.6.0",
         },
       },
       null,
@@ -535,8 +704,10 @@ export function screenVanilla(gameId) {
 import type { GameResults } from '@smoregg/sdk';
 
 interface GameEvents {
+  // Screen → Controller (view state)
   'score-update': { score: number };
   'personal-message': { text: string };
+  // Controller → Screen (input)
   'tap': { timestamp: number };
 }
 
@@ -590,6 +761,8 @@ screen.onAllReady(() => {
 
 // Use screen.on(event, handler) / screen.off(event, handler) for dynamic event listeners.
 // destroy() automatically removes all listeners, so explicit off() cleanup is not needed.
+let tapCount = 0;
+
 screen.on('tap', (playerIndex, data) => {
   const line = document.createElement('div');
   line.textContent = \`Player \${playerIndex} tapped\`;
@@ -598,6 +771,9 @@ screen.on('tap', (playerIndex, data) => {
   while (logEl.children.length > 10) {
     logEl.removeChild(logEl.firstChild!);
   }
+  // Broadcast updated score back to controllers (Screen is source of truth)
+  tapCount++;
+  screen.broadcast('score-update', { score: tapCount });
 });
 
 function updateStatus() {
@@ -606,8 +782,7 @@ function updateStatus() {
 }
 
 // Example functions (can be called from console for testing):
-// screen.broadcast('score-update', { score: 100 });
-// screen.sendToController(0, 'message', { text: 'Hello!' });
+// screen.sendToController(0, 'personal-message', { text: 'Hello!' });
 // const results: GameResults = {
 //   scores: { 0: 50, 1: 75 },
 //   // winner: 0,
@@ -615,6 +790,7 @@ function updateStatus() {
 // };
 // screen.gameOver(results);
 `,
+    "src/__tests__/game.test.ts": screenTestFileVanilla(),
   };
 }
 
@@ -666,6 +842,7 @@ export function controllerReact(gameId) {
         scripts: {
           dev: "vite",
           build: "tsc && vite build",
+          test: "vitest run",
         },
         dependencies: {
           react: "^18.3.1",
@@ -678,6 +855,7 @@ export function controllerReact(gameId) {
           "@vitejs/plugin-react": "^4.3.0",
           typescript: "^5.5.0",
           vite: "^5.4.0",
+          vitest: "^1.6.0",
         },
       },
       null,
@@ -725,11 +903,27 @@ import type { Controller, ControllerInfo } from '@smoregg/sdk';
 import { useEffect, useRef, useState } from 'react';
 
 interface GameEvents {
+  // Screen → Controller (view state)
   'score-update': { score: number };
   'personal-message': { text: string };
+  // Controller → Screen (input)
   'tap': { timestamp: number };
 }
 
+/**
+ * ARCHITECTURE: Stateless Controller Pattern
+ *
+ * The controller is a stateless display + input device:
+ * - Render ONLY what the Screen sends (via controller.on())
+ * - Send ONLY user input to Screen (via controller.send())
+ * - Do NOT store or compute game state here
+ *
+ * Data flow:
+ *   Controller → Screen: controller.send('tap', { timestamp })  (input only)
+ *   Screen → Controller: 'score-update' { score }               (view state)
+ *   Controller renders: score from Screen (source of truth)
+ */
+
 export function App() {
   const controllerRef = useRef<Controller | null>(null);
   const [myIndex, setMyIndex] = useState(-1);
@@ -776,7 +970,6 @@ export function App() {
 
   const handleTap = () => {
     controllerRef.current?.send('tap', { timestamp: Date.now() });
-    setCount((c) => c + 1);
   };
 
   return (
@@ -787,7 +980,7 @@ export function App() {
       touchAction: 'manipulation', userSelect: 'none',
     }}>
       {isReady && (
-        <div style={{ fontSize: '16px', opacity: 0.6 }}>{me?.name ?? \`Player \${myIndex}\`}</div>
+        <div style={{ fontSize: '16px', opacity: 0.6 }}>{me?.nickname ?? \`Player \${myIndex}\`}</div>
       )}
       <div style={{ fontSize: '48px', fontWeight: 'bold' }}>{count}</div>
       <button
@@ -805,6 +998,7 @@ export function App() {
   );
 }
 `,
+    "src/__tests__/game.test.ts": controllerTestFile(),
   };
 }
 
@@ -819,6 +1013,7 @@ export function controllerVanilla(gameId) {
         scripts: {
           dev: "vite",
           build: "tsc && vite build",
+          test: "vitest run",
         },
         dependencies: {
           "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
@@ -826,6 +1021,7 @@ export function controllerVanilla(gameId) {
         devDependencies: {
           typescript: "^5.5.0",
           vite: "^5.4.0",
+          vitest: "^1.6.0",
         },
       },
       null,
@@ -884,12 +1080,26 @@ export default defineConfig({
     "src/main.ts": `import { createController } from '@smoregg/sdk';
 
 interface GameEvents {
+  // Screen → Controller (view state)
   'score-update': { score: number };
   'personal-message': { text: string };
+  // Controller → Screen (input)
   'tap': { timestamp: number };
 }
 
-let count = 0;
+/**
+ * ARCHITECTURE: Stateless Controller Pattern
+ *
+ * The controller is a stateless display + input device:
+ * - Render ONLY what the Screen sends (via controller.on())
+ * - Send ONLY user input to Screen (via controller.send())
+ * - Do NOT store or compute game state here
+ *
+ * Data flow:
+ *   Controller → Screen: controller.send('tap', { timestamp })  (input only)
+ *   Screen → Controller: 'score-update' { score }               (view state)
+ *   Controller renders: score from Screen (source of truth)
+ */
 
 const playerInfoEl = document.getElementById('player-info')!;
 const countEl = document.getElementById('count')!;
@@ -905,12 +1115,11 @@ const controller = createController<GameEvents>({ debug: true });
 // To control autoReady: createScreen({ autoReady: false }) or createController({ autoReady: false })
 
 controller.onAllReady(() => {
-  playerInfoEl.textContent = controller.me?.name ?? \`Player \${controller.myPlayerIndex}\`;
+  playerInfoEl.textContent = controller.me?.nickname ?? \`Player \${controller.myPlayerIndex}\`;
 });
 
 controller.on('score-update', (data) => {
-  count = data.score;
-  countEl.textContent = String(count);
+  countEl.textContent = String(data.score);
 });
 
 controller.on('personal-message', (data) => {
@@ -919,10 +1128,9 @@ controller.on('personal-message', (data) => {
 
 tapBtn.addEventListener('pointerdown', () => {
   controller.send('tap', { timestamp: Date.now() });
-  count++;
-  countEl.textContent = String(count);
 });
 `,
+    "src/__tests__/game.test.ts": controllerTestFileVanilla(),
   };
 }
 
@@ -1004,7 +1212,6 @@ const room = {
   gameId: '',
   status: 'waiting',
   readyIds: new Set(),
-  customStates: new Map(), // playerIndex -> state object
 };
 
 function toPlayerDTO(p) {
@@ -1055,6 +1262,16 @@ async function main() {
   app.get('/', servePage(join(__dirname, 'index.html')));
   app.get('/controller', servePage(join(__dirname, 'controller.html')));
 
+  // Serve game.json for dev harness (minPlayers, maxPlayers, title, etc.)
+  app.get('/game.json', (_req, res) => {
+    try {
+      const gameJson = JSON.parse(readFileSync(join(__dirname, '..', 'game.json'), 'utf-8'));
+      res.json(gameJson);
+    } catch (e) {
+      res.json({ id: 'dev-game', title: 'Dev Game', minPlayers: 1, maxPlayers: 8 });
+    }
+  });
+
   // ── Socket handling ──
 
   io.on('connection', (socket) => {
@@ -1151,20 +1368,6 @@ async function main() {
       io.to(room.code).emit('smore:game-over', data);
     });
 
-    socket.on('smore:set-custom-state', (data) => {
-      if (socket.role !== 'player') return;
-      const prev = room.customStates.get(socket.playerIndex) || {};
-      const next = Object.assign({}, prev, data && typeof data === 'object' ? data : {});
-      room.customStates.set(socket.playerIndex, next);
-      io.to(room.code).emit('smore:custom-state-changed', { playerIndex: socket.playerIndex, state: next });
-    });
-
-    socket.on('smore:get-custom-states', () => {
-      const states = {};
-      room.customStates.forEach((state, playerIndex) => { states[playerIndex] = state; });
-      socket.emit('smore:custom-states', { states });
-    });
-
     socket.on('smore:return-to-selection', () => {
       room.status = 'waiting';
       room.gameId = '';
@@ -1186,7 +1389,6 @@ async function main() {
       room.gameId = '';
       room.status = 'waiting';
       room.readyIds = new Set();
-      room.customStates = new Map();
       console.log('  [reset] Room reset by host');
       if (typeof callback === 'function') callback({ success: true });
     });
@@ -1343,6 +1545,10 @@ export function devHarness(gameId) {
     .btn-primary:disabled:hover { background: #4f46e5; }
     .btn-danger { background: #dc2626; border-color: #dc2626; color: #fff; }
     .btn-danger:hover { background: #b91c1c; }
+    .btn-start { background: #16a34a; border-color: #16a34a; color: #fff; font-size: 13px; padding: 5px 16px; }
+    .btn-start:hover { background: #15803d; }
+    .btn-start:disabled { opacity: 0.35; cursor: not-allowed; }
+    .btn-start:disabled:hover { background: #16a34a; }
 
     /* Main layout */
     .main { display: flex; height: calc(100% - 48px); }
@@ -1418,6 +1624,7 @@ export function devHarness(gameId) {
   <div class="badge-muted" id="playerCount">0 players</div>
   <div class="phase-badge phase-lobby" id="phaseBadge">Lobby</div>
   <div class="topbar-spacer"></div>
+  <button class="btn btn-start" id="startGameBtn" disabled>▶ Start</button>
   <button class="btn btn-danger" id="endGameBtn" style="display:none;">End Game</button>
   <button class="btn" id="resetBtn">Reset</button>
   <button class="btn btn-primary" id="addPlayerBtn">+ Player</button>
@@ -1456,6 +1663,10 @@ export function devHarness(gameId) {
   var screenIframe = null;
   var screenReady = false;
   var gamePhase = 'lobby';
+  var gameStarted = false;
+  var pendingGameReady = [];  // { socket, data }
+  var minPlayers = 1;
+  var gameConfig = {};
 
   // ── DOM refs ──
   var roomCodeEl = document.getElementById('roomCode');
@@ -1467,6 +1678,7 @@ export function devHarness(gameId) {
   var controllerGrid = document.getElementById('controllerGrid');
   var emptyState = document.getElementById('emptyState');
   var addPlayerBtn = document.getElementById('addPlayerBtn');
+  var startGameBtn = document.getElementById('startGameBtn');
   var endGameBtn = document.getElementById('endGameBtn');
   var resetBtn = document.getElementById('resetBtn');
 
@@ -1478,12 +1690,19 @@ export function devHarness(gameId) {
     phaseBadgeEl.className = 'phase-badge phase-' + phase;
     addPlayerBtn.disabled = (phase === 'playing');
     endGameBtn.style.display = (phase === 'playing') ? 'inline-block' : 'none';
+    startGameBtn.style.display = (phase === 'lobby') ? 'inline-block' : 'none';
+    updateStartButton();
+  }
+
+  function updateStartButton() {
+    startGameBtn.disabled = gameStarted || serverPlayers.length < minPlayers;
   }
 
   // ── Helpers ──
   function updatePlayerCount() {
     var count = serverPlayers.length;
     playerCountEl.textContent = count + ' player' + (count !== 1 ? 's' : '');
+    updateStartButton();
   }
 
   function updateEmptyState() {
@@ -1561,7 +1780,7 @@ export function devHarness(gameId) {
     var screenSysEvents = [
       'smore:player-joined', 'smore:player-left', 'smore:player-disconnected', 'smore:player-reconnected',
       'smore:player-character-updated', 'smore:rate-limited', 'smore:game-over', 'smore:all-ready',
-      'smore:self-disconnected', 'smore:self-reconnected', 'smore:custom-state-changed', 'smore:custom-states'
+      'smore:self-disconnected', 'smore:self-reconnected'
     ];
     screenSysEvents.forEach(function(sysEvent) {
       screenSocket.on(sysEvent, function(data) {
@@ -1643,7 +1862,7 @@ export function devHarness(gameId) {
       'smore:game-over',
       'smore:player-joined', 'smore:player-left', 'smore:player-disconnected', 'smore:player-reconnected',
       'smore:player-character-updated', 'smore:rate-limited', 'smore:all-ready',
-      'smore:self-disconnected', 'smore:self-reconnected', 'smore:custom-state-changed', 'smore:custom-states'
+      'smore:self-disconnected', 'smore:self-reconnected'
     ];
     ctrlSysEvents.forEach(function(sysEvent) {
       controllerSocket.on(sysEvent, function(data) {
@@ -1705,9 +1924,13 @@ export function devHarness(gameId) {
         return;
       }
 
-      // Relay game-ready to server for ready/start sync
+      // Buffer game-ready until game is started (prevents auto-start)
       if (event === 'smore:game-ready') {
-        screenSocket.emit('smore:game-ready', data || {});
+        if (gameStarted) {
+          screenSocket.emit('smore:game-ready', data || {});
+        } else {
+          pendingGameReady.push({ socket: screenSocket, data: data });
+        }
         return;
       }
 
@@ -1753,19 +1976,13 @@ export function devHarness(gameId) {
         setPhase('lobby');
       }
 
-      // Relay game-ready to server for ready/start sync
+      // Buffer game-ready until game is started (prevents auto-start)
       if (event === 'smore:game-ready') {
-        player.socket.emit('smore:game-ready', data || {});
-        return;
-      }
-
-      // Relay custom state events to server
-      if (event === 'smore:set-custom-state') {
-        player.socket.emit('smore:set-custom-state', data || {});
-        return;
-      }
-      if (event === 'smore:get-custom-states') {
-        player.socket.emit('smore:get-custom-states');
+        if (gameStarted) {
+          player.socket.emit('smore:game-ready', data || {});
+        } else {
+          pendingGameReady.push({ socket: player.socket, data: data });
+        }
         return;
       }
 
@@ -1784,6 +2001,9 @@ export function devHarness(gameId) {
 
   // ── End Game ──
   function endGame() {
+    gameStarted = false;
+    pendingGameReady = [];
+
     // Broadcast phase-change to ALL controllers (including phone) via server relay
     screenSocket.emit('phase-change', { phase: 'lobby' });
 
@@ -1804,6 +2024,9 @@ export function devHarness(gameId) {
 
   // ── Reset ──
   function resetAll() {
+    gameStarted = false;
+    pendingGameReady = [];
+
     // 1. Disconnect all local iframe player sockets
     players.forEach(function(p) {
       if (p.socket) p.socket.disconnect();
@@ -1852,6 +2075,24 @@ export function devHarness(gameId) {
     if (!addPlayerBtn.disabled) addController();
   });
 
+  startGameBtn.addEventListener('click', function() {
+    if (gameStarted || serverPlayers.length < minPlayers) return;
+    gameStarted = true;
+
+    // Tell server to start the game (triggers smore:game-selected + smore:game-started)
+    screenSocket.emit('smore:select-game', { gameId: gameConfig.id || 'dev-game' });
+
+    // Flush all buffered game-ready messages after server processes select-game
+    setTimeout(function() {
+      pendingGameReady.forEach(function(entry) {
+        entry.socket.emit('smore:game-ready', entry.data || {});
+      });
+      pendingGameReady = [];
+    }, 50);
+
+    setPhase('playing');
+  });
+
   endGameBtn.addEventListener('click', endGame);
   resetBtn.addEventListener('click', resetAll);
 
@@ -1871,6 +2112,13 @@ export function devHarness(gameId) {
   });
 
   // ── Boot ──
+  // Fetch game.json for minPlayers config
+  fetch('/game.json').then(function(r) { return r.json(); }).then(function(cfg) {
+    gameConfig = cfg;
+    minPlayers = cfg.minPlayers || 1;
+    updateStartButton();
+  }).catch(function() {});
+
   initScreen();
   setTimeout(function() { addController(); }, 500);
 })();
@@ -1945,6 +2193,8 @@ export function devControllerPage(gameId) {
   var roomCode = '';
   var players = [];
   var iframeReady = false;
+  var gameStarted = false;
+  var pendingGameReady = null;
 
   // Connect and join room
   socket = io();
@@ -1977,12 +2227,21 @@ export function devControllerPage(gameId) {
     }
   });
 
+  // Listen for game-started to flush pending game-ready
+  socket.on('smore:game-started', function() {
+    gameStarted = true;
+    if (pendingGameReady !== null) {
+      socket.emit('smore:game-ready', pendingGameReady);
+      pendingGameReady = null;
+    }
+  });
+
   // Forward system events to iframe
   var sysEvents = [
     'smore:game-over',
     'smore:player-joined', 'smore:player-left', 'smore:player-disconnected', 'smore:player-reconnected',
     'smore:player-character-updated', 'smore:rate-limited', 'smore:all-ready',
-    'smore:self-disconnected', 'smore:self-reconnected', 'smore:custom-state-changed', 'smore:custom-states'
+    'smore:self-disconnected', 'smore:self-reconnected'
   ];
   sysEvents.forEach(function(sysEvent) {
     socket.on(sysEvent, function(data) {
@@ -2038,19 +2297,13 @@ export function devControllerPage(gameId) {
       var data = msg.payload.data;
       var ackId = msg.payload.ackId;
 
-      // Relay game-ready to server for ready/start sync
+      // Buffer game-ready until game is started (prevents auto-start)
       if (event === 'smore:game-ready') {
-        socket.emit('smore:game-ready', data || {});
-        return;
-      }
-
-      // Relay custom state events to server
-      if (event === 'smore:set-custom-state') {
-        socket.emit('smore:set-custom-state', data || {});
-        return;
-      }
-      if (event === 'smore:get-custom-states') {
-        socket.emit('smore:get-custom-states');
+        if (gameStarted) {
+          socket.emit('smore:game-ready', data || {});
+        } else {
+          pendingGameReady = data || {};
+        }
         return;
       }