create-smore-game

Scaffold a multiplayer party game for the S'MORE platform.

Quick Start

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:

{
  "id": "my-game",
  "title": "My Game",
  "description": "",
  "version": "0.1.0",
  "players": [2, 3, 4, 5, 6, 7, 8],
  "categories": ["party"]
}

Edit this file before submitting. The id must be unique and contain only lowercase letters, numbers, and hyphens.

Building and Deploying

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