create-usion-game 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# create-usion-game
+
+Scaffold a new multiplayer game for the [Usion](https://usions.com) platform.
+
+## Usage
+
+```bash
+npx create-usion-game my-game
+```
+
+Follow the interactive prompts to choose:
+
+1. **Game type** — Turn-based (platform mode) or Real-time (direct mode)
+2. **Max players** — 2, 2-4, or 2-8
+3. **Server port**
+
+## What You Get
+
+### Turn-based template (platform mode)
+
+```
+my-game/
+├── app/page.tsx      # Game UI (tic-tac-toe starter)
+├── lib/types.ts      # Game state types
+├── lib/constants.ts  # Board size, win conditions
+├── package.json      # Next.js + @usion/sdk
+└── README.md
+```
+
+Games relay through Usion's backend via Socket.IO. No server needed.
+
+```bash
+cd my-game && npm install && npm run dev
+```
+
+### Real-time template (direct mode)
+
+```
+my-game/
+├── server.js              # Game server (UsionGameServer)
+├── server/game-logic.js   # Pure game rules (testable)
+├── app/page.tsx           # Canvas client
+├── lib/types.ts
+├── lib/constants.ts
+├── .env.example
+├── package.json           # Next.js + @usion/game-server
+└── README.md
+```
+
+You run your own WebSocket server. Token validation and result submission are handled by `@usion/game-server`.
+
+```bash
+cd my-game && npm install
+cp .env.example .env       # Add your SERVICE_ID and secret
+npm run dev:server          # Start game server
+npm run dev                 # Start client (in another terminal)
+```
+
+## Related Packages
+
+- [`@usion/sdk`](https://www.npmjs.com/package/@usion/sdk) — Client SDK for mini-apps and games
+- [`@usion/game-server`](https://www.npmjs.com/package/@usion/game-server) — Server SDK for direct-mode games
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * create-usion-game — Scaffold a new Usion multiplayer game project.
+ *
+ * Usage:
+ *   npx create-usion-game my-game
+ *   node packages/create-usion-game/index.js my-game
+ */
+
+import { createInterface } from 'readline';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync, copyFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, 'templates');
+
+// ─── Helpers ───────────────────────────────────────────────────
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function choose(rl, question, options) {
+  console.log(`\n${question}`);
+  options.forEach((opt, i) => {
+    console.log(`  ${i + 1}) ${opt.label}${opt.description ? ` — ${opt.description}` : ''}`);
+  });
+
+  while (true) {
+    const answer = await prompt(rl, `\nChoice (1-${options.length}): `);
+    const idx = parseInt(answer, 10) - 1;
+    if (idx >= 0 && idx < options.length) return options[idx].value;
+    console.log(`  Please enter a number between 1 and ${options.length}`);
+  }
+}
+
+function copyDirRecursive(src, dest, replacements) {
+  if (!existsSync(dest)) mkdirSync(dest, { recursive: true });
+
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, replacements);
+    } else {
+      let content = readFileSync(srcPath, 'utf-8');
+      for (const [key, value] of Object.entries(replacements)) {
+        content = content.replaceAll(key, value);
+      }
+      writeFileSync(destPath, content);
+    }
+  }
+}
+
+// ─── Main ──────────────────────────────────────────────────────
+
+async function main() {
+  const projectName = process.argv[2];
+
+  if (!projectName) {
+    console.log('\nUsage: create-usion-game <project-name>\n');
+    console.log('Example:');
+    console.log('  npx create-usion-game my-game\n');
+    process.exit(1);
+  }
+
+  const projectDir = resolve(process.cwd(), projectName);
+
+  if (existsSync(projectDir)) {
+    console.error(`\nError: Directory "${projectName}" already exists.\n`);
+    process.exit(1);
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log(`\n  Creating a new Usion game: ${projectName}\n`);
+
+  const gameType = await choose(rl, 'What type of game?', [
+    { label: 'Turn-based', value: 'turn-based', description: 'Board games, card games (platform mode)' },
+    { label: 'Real-time', value: 'real-time', description: 'Arena, racing, action (direct mode + server)' },
+  ]);
+
+  const maxPlayers = await choose(rl, 'Max players per room?', [
+    { label: '2 players', value: '2' },
+    { label: '2-4 players', value: '4' },
+    { label: '2-8 players', value: '8' },
+  ]);
+
+  const port = await prompt(rl, '\nServer port (default 3005): ');
+  const finalPort = port.trim() || '3005';
+
+  rl.close();
+
+  console.log(`\n  Scaffolding project...\n`);
+
+  const replacements = {
+    '{{PROJECT_NAME}}': projectName,
+    '{{MAX_PLAYERS}}': maxPlayers,
+    '{{PORT}}': finalPort,
+  };
+
+  // Copy base files first
+  const baseDir = join(TEMPLATES_DIR, 'base');
+  if (existsSync(baseDir)) {
+    copyDirRecursive(baseDir, projectDir, replacements);
+  }
+
+  // Copy template-specific files (overrides base if conflict)
+  const templateDir = join(TEMPLATES_DIR, gameType);
+  copyDirRecursive(templateDir, projectDir, replacements);
+
+  // Success message
+  console.log(`  Done! Created ${projectName}\n`);
+  console.log('  Next steps:\n');
+  console.log(`    cd ${projectName}`);
+  console.log('    npm install');
+  if (gameType === 'real-time') {
+    console.log('    # Configure .env with your USION_SHARED_SECRET and SERVICE_ID');
+    console.log('    npm run dev:server  # Start game server');
+    console.log('    npm run dev         # Start Next.js client (in another terminal)');
+  } else {
+    console.log('    npm run dev         # Start Next.js dev server');
+  }
+  console.log('\n  Open your game in the Usion app to test.\n');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-usion-game",
+  "version": "1.0.0",
+  "description": "Create a new Usion multiplayer game project",
+  "type": "module",
+  "bin": {
+    "create-usion-game": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "templates/"
+  ],
+  "keywords": [
+    "usion",
+    "game",
+    "multiplayer",
+    "create",
+    "scaffold",
+    "template"
+  ],
+  "homepage": "https://github.com/usion-platform/create-usion-game#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usion-platform/create-usion-game.git"
+  },
+  "bugs": {
+    "url": "https://github.com/usion-platform/create-usion-game/issues"
+  },
+  "license": "MIT"
+}

package/templates/base/next.config.js

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: false,
+  output: 'export',
+};
+
+export default nextConfig;

package/templates/base/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "server", "server.js"]
+}

package/templates/real-time/.env.example

@@ -0,0 +1,14 @@
+# Usion API URL
+API_URL=http://localhost:8089
+
+# Your service ID from the Usion platform
+SERVICE_ID=your-service-id
+
+# HMAC shared secret (from service registration)
+USION_SHARED_SECRET=your-shared-secret
+
+# Signing key ID (from service realtime.signing.key_id)
+USION_KEY_ID=default
+
+# Server port
+PORT={{PORT}}

package/templates/real-time/README.md

@@ -0,0 +1,68 @@
+# {{PROJECT_NAME}}
+
+A real-time multiplayer game built on the Usion platform with direct-mode connection.
+
+## Quick Start
+
+```bash
+npm install
+
+# Configure your environment
+cp .env.example .env
+# Edit .env with your SERVICE_ID and USION_SHARED_SECRET
+
+# Start the game server (WebSocket)
+npm run dev:server
+
+# In another terminal, start the Next.js client
+npm run dev
+```
+
+## Architecture
+
+```
+Usion App ──token──> Your Server (server.js)
+    │                    │
+    └── WebSocket ───────┘
+         (direct mode)
+```
+
+- **Server** (`server.js`): Runs `@usion/game-server`, validates RS256 tokens, manages rooms
+- **Game Logic** (`server/game-logic.js`): Pure game rules — no networking, testable
+- **Client** (`app/page.tsx`): Canvas rendering, input handling, SDK connection
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `server.js` | UsionGameServer setup with event handlers |
+| `server/game-logic.js` | Pure game logic (movement, collision, scoring) |
+| `app/page.tsx` | Client-side rendering and input |
+| `lib/types.ts` | Shared type definitions |
+| `lib/constants.ts` | Arena size, speed, colors |
+
+## How It Works
+
+1. Player opens game in Usion app
+2. Usion backend issues RS256 access token
+3. Client connects to your server via WebSocket with token
+4. `@usion/game-server` validates token automatically
+5. Server manages room lifecycle and broadcasts state
+6. Client sends real-time input, server validates and relays
+
+## Customization
+
+1. **Game rules**: Edit `server/game-logic.js` — add your own `createPlayer`, `applyInput`, scoring
+2. **Server events**: Edit `server.js` — add `onAction('your-action', ...)` handlers
+3. **Client rendering**: Edit `app/page.tsx` — replace canvas drawing with your visuals
+4. **Constants**: Edit `lib/constants.ts` — arena size, speed, colors
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SERVICE_ID` | Your game's service ID on Usion |
+| `USION_SHARED_SECRET` | HMAC secret for result submission |
+| `USION_KEY_ID` | Signing key ID (default: 'default') |
+| `API_URL` | Usion backend URL |
+| `PORT` | Server port |

package/templates/real-time/app/layout.tsx

@@ -0,0 +1,12 @@
+export const metadata = {
+  title: '{{PROJECT_NAME}}',
+  description: 'Usion real-time multiplayer game',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/real-time/app/page.tsx

@@ -0,0 +1,255 @@
+'use client';
+
+/**
+ * {{PROJECT_NAME}} — Real-Time Game Client (Direct Mode)
+ *
+ * This client connects directly to your game server's WebSocket.
+ * The Usion SDK handles token acquisition and connection setup.
+ *
+ * Flow: Usion.init → game.connectDirect → game.join → game.realtime → game.onRealtime
+ *
+ * Replace the canvas rendering with your own game visuals.
+ */
+
+import Script from 'next/script';
+
+export default function GamePage() {
+  return (
+    <>
+      <Script src="/usion-sdk.js" strategy="beforeInteractive" />
+
+      <Script id="game-logic" strategy="afterInteractive">{`
+(function() {
+  'use strict';
+
+  const ARENA_W = 800;
+  const ARENA_H = 600;
+  const PLAYER_R = 15;
+  const MOVE_SPEED = 5;
+  const INPUT_RATE_MS = 50;
+  const COLORS = ['#4FC3F7','#FF7043','#66BB6A','#AB47BC','#FFCA28','#EF5350'];
+
+  const state = {
+    phase: 'connecting',
+    myId: null,
+    players: {},
+    keys: { up: false, down: false, left: false, right: false },
+    error: null,
+  };
+
+  let canvas, ctx;
+  let lastInputSent = 0;
+
+  // ─── Input ───────────────────────────────────────────────
+  const KEY_MAP = {
+    ArrowUp: 'up', ArrowDown: 'down', ArrowLeft: 'left', ArrowRight: 'right',
+    w: 'up', s: 'down', a: 'left', d: 'right',
+    W: 'up', S: 'down', A: 'left', D: 'right',
+  };
+
+  window.addEventListener('keydown', function(e) {
+    const dir = KEY_MAP[e.key];
+    if (dir) { state.keys[dir] = true; e.preventDefault(); }
+  });
+  window.addEventListener('keyup', function(e) {
+    const dir = KEY_MAP[e.key];
+    if (dir) { state.keys[dir] = false; e.preventDefault(); }
+  });
+
+  // ─── Render Loop ─────────────────────────────────────────
+  function render() {
+    if (!ctx) return;
+    ctx.fillStyle = '#0a0a0a';
+    ctx.fillRect(0, 0, ARENA_W, ARENA_H);
+
+    // Draw grid
+    ctx.strokeStyle = '#1a1a1a';
+    ctx.lineWidth = 1;
+    for (let x = 0; x < ARENA_W; x += 40) {
+      ctx.beginPath(); ctx.moveTo(x, 0); ctx.lineTo(x, ARENA_H); ctx.stroke();
+    }
+    for (let y = 0; y < ARENA_H; y += 40) {
+      ctx.beginPath(); ctx.moveTo(0, y); ctx.lineTo(ARENA_W, y); ctx.stroke();
+    }
+
+    // Draw players
+    const players = Object.values(state.players);
+    players.forEach(function(p, i) {
+      ctx.fillStyle = p.color || COLORS[i % COLORS.length];
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, PLAYER_R, 0, Math.PI * 2);
+      ctx.fill();
+
+      // Name label
+      ctx.fillStyle = '#fff';
+      ctx.font = '11px system-ui';
+      ctx.textAlign = 'center';
+      ctx.fillText(p.name || 'Player', p.x, p.y - PLAYER_R - 6);
+
+      // "You" indicator
+      if (p.id === state.myId) {
+        ctx.strokeStyle = '#fff';
+        ctx.lineWidth = 2;
+        ctx.beginPath();
+        ctx.arc(p.x, p.y, PLAYER_R + 4, 0, Math.PI * 2);
+        ctx.stroke();
+      }
+    });
+
+    // Phase overlay
+    if (state.phase === 'waiting') {
+      ctx.fillStyle = 'rgba(0,0,0,0.7)';
+      ctx.fillRect(0, 0, ARENA_W, ARENA_H);
+      ctx.fillStyle = '#fff';
+      ctx.font = '24px system-ui';
+      ctx.textAlign = 'center';
+      ctx.fillText('Waiting for opponent...', ARENA_W / 2, ARENA_H / 2);
+    } else if (state.phase === 'finished') {
+      ctx.fillStyle = 'rgba(0,0,0,0.7)';
+      ctx.fillRect(0, 0, ARENA_W, ARENA_H);
+      ctx.fillStyle = '#fff';
+      ctx.font = '28px system-ui';
+      ctx.textAlign = 'center';
+      ctx.fillText('Game Over', ARENA_W / 2, ARENA_H / 2 - 20);
+      ctx.font = '16px system-ui';
+      ctx.fillText('Tap rematch to play again', ARENA_W / 2, ARENA_H / 2 + 20);
+    }
+
+    // Error
+    if (state.error) {
+      ctx.fillStyle = '#ff4444';
+      ctx.font = '13px system-ui';
+      ctx.textAlign = 'center';
+      ctx.fillText(state.error, ARENA_W / 2, 20);
+    }
+  }
+
+  // ─── Game Loop ───────────────────────────────────────────
+  function gameLoop() {
+    const now = Date.now();
+
+    // Send input at fixed rate
+    if (state.phase === 'playing' && now - lastInputSent >= INPUT_RATE_MS) {
+      const dx = (state.keys.right ? 1 : 0) - (state.keys.left ? 1 : 0);
+      const dy = (state.keys.down ? 1 : 0) - (state.keys.up ? 1 : 0);
+
+      if (dx !== 0 || dy !== 0) {
+        Usion.game.realtime('move', { dx: dx, dy: dy });
+
+        // Local prediction
+        var me = state.players[state.myId];
+        if (me) {
+          var len = Math.sqrt(dx*dx + dy*dy);
+          me.x = Math.max(PLAYER_R, Math.min(ARENA_W - PLAYER_R, me.x + (dx/len)*MOVE_SPEED));
+          me.y = Math.max(PLAYER_R, Math.min(ARENA_H - PLAYER_R, me.y + (dy/len)*MOVE_SPEED));
+        }
+
+        lastInputSent = now;
+      }
+    }
+
+    render();
+    requestAnimationFrame(gameLoop);
+  }
+
+  // ─── SDK Init ────────────────────────────────────────────
+  Usion.init(function(config) {
+    state.myId = config.userId;
+
+    Usion.game.connectDirect()
+      .then(function() { return Usion.game.join(config.roomId); })
+      .then(function(joinData) {
+        state.phase = 'waiting';
+        render();
+      })
+      .catch(function(err) {
+        state.error = 'Connection failed: ' + err.message;
+        render();
+      });
+
+    // Another player joined
+    Usion.game.onPlayerJoined(function(data) {
+      state.phase = 'playing';
+      render();
+    });
+
+    // State snapshot from server
+    Usion.game.onStateUpdate(function(data) {
+      var gs = data.game_state || data.payload?.game_state || data;
+      if (gs.players) state.players = gs.players;
+      if (gs.phase) state.phase = gs.phase;
+      render();
+    });
+
+    // Real-time position update from another player
+    Usion.game.onRealtime(function(data) {
+      var d = data.action_data || data;
+      if (d.player_id && d.x !== undefined) {
+        if (state.players[d.player_id]) {
+          state.players[d.player_id].x = d.x;
+          state.players[d.player_id].y = d.y;
+        }
+      }
+    });
+
+    Usion.game.onGameFinished(function(data) {
+      state.phase = 'finished';
+      render();
+    });
+
+    Usion.game.onPlayerLeft(function(data) {
+      delete state.players[data.player_id];
+      render();
+    });
+
+    Usion.game.onError(function(data) {
+      state.error = data.message || 'Error occurred';
+      render();
+    });
+
+    Usion.game.onDisconnect(function() {
+      state.error = 'Disconnected';
+      render();
+    });
+
+    Usion.game.onReconnect(function() {
+      state.error = null;
+      render();
+    });
+  });
+
+  // ─── Canvas Setup ────────────────────────────────────────
+  document.addEventListener('DOMContentLoaded', function() {
+    var app = document.getElementById('app');
+    app.innerHTML =
+      '<canvas id="game-canvas" width="' + ARENA_W + '" height="' + ARENA_H + '"></canvas>';
+    canvas = document.getElementById('game-canvas');
+    ctx = canvas.getContext('2d');
+    gameLoop();
+  });
+})();
+      `}</Script>
+
+      <div id="app" />
+
+      <style jsx global>{`
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        html, body { height: 100%; background: #000; overflow: hidden; }
+
+        #app {
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          min-height: 100vh;
+        }
+
+        canvas {
+          max-width: 100vw;
+          max-height: 100vh;
+          border: 1px solid #222;
+          border-radius: 4px;
+        }
+      `}</style>
+    </>
+  );
+}

package/templates/real-time/lib/constants.ts

@@ -0,0 +1,8 @@
+/** Game constants */
+
+export const ARENA_WIDTH = 800;
+export const ARENA_HEIGHT = 600;
+export const PLAYER_RADIUS = 15;
+export const MOVE_SPEED = 5;
+export const MAX_PLAYERS = {{MAX_PLAYERS}};
+export const COLORS = ['#4FC3F7', '#FF7043', '#66BB6A', '#AB47BC', '#FFCA28', '#EF5350', '#26C6DA', '#8D6E63'];

package/templates/real-time/lib/types.ts

@@ -0,0 +1,23 @@
+/** Game-specific types */
+
+export interface PlayerState {
+  id: string;
+  name: string;
+  x: number;
+  y: number;
+  score: number;
+  color: string;
+}
+
+export interface GameState {
+  players: Record<string, PlayerState>;
+  phase: 'waiting' | 'playing' | 'finished';
+  winner: string | null;
+}
+
+export type InputData = {
+  x: number;
+  y: number;
+  dx: number;
+  dy: number;
+};

package/templates/real-time/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev -p {{PORT}} -H 0.0.0.0",
+    "dev:server": "node server.js",
+    "build": "next build",
+    "start": "node server.js",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@usion/game-server": "^1.0.0",
+    "next": "^14.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "typescript": "^5.3.0"
+  }
+}

package/templates/real-time/server/game-logic.js

@@ -0,0 +1,55 @@
+/**
+ * Pure game logic — no networking, no side effects.
+ *
+ * This file is importable and testable independently.
+ * Replace these functions with your own game rules.
+ */
+
+const ARENA_WIDTH = 800;
+const ARENA_HEIGHT = 600;
+const PLAYER_RADIUS = 15;
+const MOVE_SPEED = 5;
+const COLORS = ['#4FC3F7', '#FF7043', '#66BB6A', '#AB47BC', '#FFCA28', '#EF5350', '#26C6DA', '#8D6E63'];
+
+/**
+ * Create initial state for a new player.
+ */
+export function createPlayer(userId, name, index) {
+  return {
+    id: userId,
+    name: name,
+    x: 100 + (index * 150) % (ARENA_WIDTH - 200),
+    y: 100 + Math.floor(index / 4) * 150,
+    score: 0,
+    color: COLORS[index % COLORS.length],
+  };
+}
+
+/**
+ * Apply a movement input to a player.
+ * Returns the updated player object.
+ */
+export function applyInput(player, input) {
+  const dx = typeof input.dx === 'number' ? input.dx : 0;
+  const dy = typeof input.dy === 'number' ? input.dy : 0;
+
+  // Normalize diagonal movement
+  const len = Math.sqrt(dx * dx + dy * dy);
+  const ndx = len > 0 ? (dx / len) * MOVE_SPEED : 0;
+  const ndy = len > 0 ? (dy / len) * MOVE_SPEED : 0;
+
+  return {
+    ...player,
+    x: Math.max(PLAYER_RADIUS, Math.min(ARENA_WIDTH - PLAYER_RADIUS, player.x + ndx)),
+    y: Math.max(PLAYER_RADIUS, Math.min(ARENA_HEIGHT - PLAYER_RADIUS, player.y + ndy)),
+  };
+}
+
+/**
+ * Check if two players are colliding.
+ */
+export function checkCollision(p1, p2) {
+  const dx = p1.x - p2.x;
+  const dy = p1.y - p2.y;
+  return Math.sqrt(dx * dx + dy * dy) < PLAYER_RADIUS * 2;
+}

package/templates/real-time/server.js

@@ -0,0 +1,146 @@
+/**
+ * {{PROJECT_NAME}} — Game Server (Direct Mode)
+ *
+ * This server handles WebSocket connections from Usion game clients.
+ * Token validation and result submission are handled automatically
+ * by @usion/game-server.
+ *
+ * Start: node server.js
+ */
+import { UsionGameServer } from '@usion/game-server';
+import { createPlayer, applyInput } from './server/game-logic.js';
+
+const PORT = Number(process.env.PORT || {{PORT}});
+const MAX_PLAYERS = {{MAX_PLAYERS}};
+
+const server = new UsionGameServer({
+  serviceId: process.env.SERVICE_ID || 'my-game',
+  sharedSecret: process.env.USION_SHARED_SECRET || 'dev-secret',
+  keyId: process.env.USION_KEY_ID || 'default',
+  apiUrl: process.env.API_URL || 'http://localhost:8089',
+  port: PORT,
+  maxPlayersPerRoom: MAX_PLAYERS,
+});
+
+// ─── Player Join ─────────────────────────────────────────────
+
+server.onPlayerJoin((player, room) => {
+  console.log(`[${room.id}] Player joined: ${player.name} (${player.id})`);
+
+  // Create game player state
+  const playerState = createPlayer(player.id, player.name, room.playerCount - 1);
+
+  // Add to game state
+  const players = room.getState().players || {};
+  players[player.id] = playerState;
+  room.setState({ players, phase: 'waiting' });
+
+  // Start game when enough players join
+  if (room.playerCount >= 2) {
+    room.setState({ phase: 'playing' });
+    room.broadcast('state_snapshot', {
+      room_id: room.id,
+      game_state: room.getState(),
+    });
+  }
+});
+
+// ─── Player Leave ────────────────────────────────────────────
+
+server.onPlayerLeave((player, room) => {
+  console.log(`[${room.id}] Player left: ${player.name}`);
+
+  const state = room.getState();
+  if (state.players) {
+    delete state.players[player.id];
+    room.setState({ players: state.players });
+  }
+
+  // If only one player left, they win
+  if (room.playerCount === 1 && state.phase === 'playing') {
+    const winnerId = room.playerIds[0];
+    room.setState({ phase: 'finished', winner: winnerId });
+    room.broadcast('match_end', {
+      room_id: room.id,
+      winner_ids: [winnerId],
+      reason: 'opponent_left',
+    });
+
+    // Submit result to Usion backend
+    server.submitResult(room.id, {
+      winnerIds: [winnerId],
+      reason: 'opponent_left',
+    }).catch(err => console.error('Result submission failed:', err.message));
+  }
+});
+
+// ─── Real-time Input (fire-and-forget, high frequency) ───────
+
+server.onRealtime('move', (data, player, room) => {
+  const state = room.getState();
+  if (!state.players || state.phase !== 'playing') return;
+
+  const playerState = state.players[player.id];
+  if (!playerState) return;
+
+  // Apply movement with server-side validation
+  state.players[player.id] = applyInput(playerState, data);
+  room.setState({ players: state.players });
+
+  // Broadcast updated position to other players
+  room.broadcastExcept(player.id, 'player_position', {
+    player_id: player.id,
+    x: state.players[player.id].x,
+    y: state.players[player.id].y,
+  });
+});
+
+// ─── Turn-based Actions (validated, stored) ──────────────────
+
+server.onAction('attack', (data, player, room) => {
+  const state = room.getState();
+  if (!state.players || state.phase !== 'playing') return;
+
+  // Example: handle an attack action
+  console.log(`[${room.id}] ${player.name} attacks!`);
+
+  // Broadcast to all players
+  room.broadcast('state_snapshot', {
+    room_id: room.id,
+    game_state: state,
+  });
+});
+
+// ─── Forfeit ─────────────────────────────────────────────────
+
+server.onForfeit((player, room) => {
+  console.log(`[${room.id}] ${player.name} forfeited`);
+
+  const winnerIds = room.playerIds.filter(id => id !== player.id);
+  room.setState({ phase: 'finished', winner: winnerIds[0] || null });
+
+  room.broadcast('match_end', {
+    room_id: room.id,
+    winner_ids: winnerIds,
+    reason: 'forfeit',
+  });
+
+  server.submitResult(room.id, {
+    winnerIds,
+    reason: 'forfeit',
+  }).catch(err => console.error('Result submission failed:', err.message));
+});
+
+// ─── Rematch ─────────────────────────────────────────────────
+
+server.onRematch((player, room) => {
+  console.log(`[${room.id}] ${player.name} requests rematch`);
+  // The SDK already broadcasts rematch_request to other players.
+  // You can add custom logic here (e.g., reset game state when both agree).
+});
+
+// ─── Start Server ────────────────────────────────────────────
+
+server.listen(() => {
+  console.log(`Game server ready on port ${PORT}`);
+});

package/templates/turn-based/.env.example

@@ -0,0 +1,5 @@
+# Usion API URL (backend server)
+# In development, this is typically http://localhost:8089
+# The game loads the SDK from the parent app, so this is only needed
+# if you're testing standalone.
+NEXT_PUBLIC_API_URL=http://localhost:8089

package/templates/turn-based/README.md

@@ -0,0 +1,41 @@
+# {{PROJECT_NAME}}
+
+A turn-based multiplayer game built on the Usion platform.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+Open the game inside the Usion app (mobile or web) to test with other players.
+
+## Architecture
+
+- **Connection**: Platform mode — game relays through Usion's Socket.IO backend
+- **Actions**: `Usion.game.action('move', { cell })` sends validated, sequenced moves
+- **State**: Listen to `onAction` and `onStateUpdate` for opponent moves
+
+## Key Files
+
+- `app/page.tsx` — Game UI and logic
+- `lib/types.ts` — Game state types
+- `lib/constants.ts` — Board size, win conditions, etc.
+
+## How It Works
+
+1. SDK initializes with player info from the parent Usion app
+2. Connects to Usion's Socket.IO server
+3. Joins the game room
+4. Players take turns sending actions
+5. Each client validates moves locally and updates the board
+
+## Customization
+
+Replace the tic-tac-toe logic with your own game:
+
+1. Change `BOARD_SIZE` and `WIN_LINES` in `lib/constants.ts`
+2. Update the board rendering in `page.tsx`
+3. Modify the `_cellClick` handler for your game's input
+4. Update `checkWinner` with your win conditions

package/templates/turn-based/app/layout.tsx

@@ -0,0 +1,12 @@
+export const metadata = {
+  title: '{{PROJECT_NAME}}',
+  description: 'Usion multiplayer game',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/turn-based/app/page.tsx

@@ -0,0 +1,322 @@
+'use client';
+
+/**
+ * {{PROJECT_NAME}} — Turn-Based Game (Platform Mode)
+ *
+ * This is a starter template for a turn-based multiplayer game.
+ * It connects through the Usion platform via Socket.IO.
+ *
+ * Flow: Usion.init → game.connect → game.join → game.action → game.onStateUpdate
+ *
+ * Replace the board rendering and game logic with your own game.
+ */
+
+import Script from 'next/script';
+
+export default function GamePage() {
+  return (
+    <>
+      {/* Load Usion SDK from the shared design system server */}
+      <Script src="/usion-sdk.js" strategy="beforeInteractive" />
+
+      <Script id="game-logic" strategy="afterInteractive">{`
+(function() {
+  'use strict';
+
+  // ─── Game State ────────────────────────────────────────────
+  const BOARD_SIZE = 9;
+  const WIN_LINES = [
+    [0,1,2],[3,4,5],[6,7,8],
+    [0,3,6],[1,4,7],[2,5,8],
+    [0,4,8],[2,4,6],
+  ];
+
+  const state = {
+    phase: 'connecting',  // connecting | waiting | playing | finished
+    board: Array(BOARD_SIZE).fill(null),
+    myId: null,
+    roomId: null,
+    playerIds: [],
+    currentTurn: null,
+    winner: null,
+    error: null,
+  };
+
+  // ─── DOM Refs ──────────────────────────────────────────────
+  const $ = (sel) => document.querySelector(sel);
+
+  // ─── Rendering ─────────────────────────────────────────────
+  function render() {
+    // Phase display
+    const statusEl = $('#status');
+    const boardEl = $('#board');
+    const errorEl = $('#error');
+    const overlayEl = $('#overlay');
+
+    if (!statusEl) return; // DOM not ready
+
+    // Error banner
+    if (state.error) {
+      errorEl.textContent = state.error;
+      errorEl.style.display = 'block';
+      setTimeout(() => { errorEl.style.display = 'none'; state.error = null; }, 4000);
+    }
+
+    // Status text
+    if (state.phase === 'connecting') {
+      statusEl.textContent = 'Connecting...';
+    } else if (state.phase === 'waiting') {
+      statusEl.textContent = 'Waiting for opponent...';
+    } else if (state.phase === 'finished') {
+      statusEl.textContent = state.winner === state.myId ? 'You win!' :
+                             state.winner === 'draw' ? 'Draw!' : 'You lose!';
+    } else {
+      const isMyTurn = state.currentTurn === state.myId;
+      statusEl.textContent = isMyTurn ? 'Your turn' : "Opponent's turn";
+    }
+
+    // Board cells
+    const cells = boardEl.querySelectorAll('.cell');
+    state.board.forEach((val, i) => {
+      const cell = cells[i];
+      if (!cell) return;
+      cell.textContent = val || '';
+      cell.className = 'cell' + (val ? ' taken' : '') +
+        (state.phase === 'playing' && !val && state.currentTurn === state.myId ? ' clickable' : '');
+    });
+
+    // Overlay for waiting/finished
+    if (state.phase === 'waiting') {
+      overlayEl.style.display = 'flex';
+      overlayEl.innerHTML = '<div class="overlay-text">Waiting for opponent...</div>';
+    } else if (state.phase === 'finished') {
+      overlayEl.style.display = 'flex';
+      const msg = state.winner === state.myId ? 'You Win!' :
+                  state.winner === 'draw' ? "It's a Draw!" : 'You Lose!';
+      overlayEl.innerHTML =
+        '<div class="overlay-text">' + msg + '</div>' +
+        '<button class="rematch-btn" onclick="window._requestRematch()">Rematch</button>';
+    } else {
+      overlayEl.style.display = 'none';
+    }
+  }
+
+  // ─── Game Logic ────────────────────────────────────────────
+  function checkWinner(board) {
+    for (const [a, b, c] of WIN_LINES) {
+      if (board[a] && board[a] === board[b] && board[b] === board[c]) {
+        return board[a]; // 'X' or 'O'
+      }
+    }
+    if (board.every(cell => cell !== null)) return 'draw';
+    return null;
+  }
+
+  function getSymbol(playerId) {
+    const idx = state.playerIds.indexOf(playerId);
+    return idx === 0 ? 'X' : 'O';
+  }
+
+  // ─── Cell Click Handler ────────────────────────────────────
+  window._cellClick = function(index) {
+    if (state.phase !== 'playing') return;
+    if (state.currentTurn !== state.myId) return;
+    if (state.board[index] !== null) return;
+
+    Usion.game.action('move', { cell: index }).catch(function(err) {
+      state.error = 'Failed to send move: ' + err.message;
+      render();
+    });
+  };
+
+  window._requestRematch = function() {
+    Usion.game.requestRematch();
+  };
+
+  // ─── SDK Init & Connection ─────────────────────────────────
+  Usion.init(function(config) {
+    state.myId = config.userId;
+    state.roomId = config.roomId;
+
+    Usion.game.connect()
+      .then(function() { return Usion.game.join(config.roomId); })
+      .then(function(joinData) {
+        state.playerIds = joinData.player_ids || [];
+        state.phase = state.playerIds.length >= 2 ? 'playing' : 'waiting';
+
+        if (joinData.game_state) {
+          state.board = joinData.game_state.board || Array(BOARD_SIZE).fill(null);
+          state.currentTurn = joinData.game_state.currentTurn || state.playerIds[0];
+        } else {
+          state.currentTurn = state.playerIds[0];
+        }
+
+        render();
+      })
+      .catch(function(err) {
+        state.error = 'Connection failed: ' + err.message;
+        render();
+      });
+
+    // ─── Event Handlers ────────────────────────────────────
+    Usion.game.onPlayerJoined(function(data) {
+      state.playerIds = data.player_ids || state.playerIds;
+      if (state.playerIds.length >= 2 && state.phase === 'waiting') {
+        state.phase = 'playing';
+        if (!state.currentTurn) state.currentTurn = state.playerIds[0];
+      }
+      render();
+    });
+
+    Usion.game.onStateUpdate(function(data) {
+      if (data.game_state) {
+        state.board = data.game_state.board || state.board;
+        state.currentTurn = data.game_state.currentTurn || state.currentTurn;
+      }
+      render();
+    });
+
+    Usion.game.onAction(function(data) {
+      if (data.action_type === 'move' && data.action_data) {
+        const cell = data.action_data.cell;
+        const symbol = getSymbol(data.player_id);
+        state.board[cell] = symbol;
+
+        // Check for winner
+        const result = checkWinner(state.board);
+        if (result) {
+          state.phase = 'finished';
+          state.winner = result === 'draw' ? 'draw' :
+            state.playerIds.find(function(id) { return getSymbol(id) === result; });
+        } else {
+          // Switch turn
+          const currentIdx = state.playerIds.indexOf(data.player_id);
+          state.currentTurn = state.playerIds[(currentIdx + 1) % state.playerIds.length];
+        }
+      }
+      render();
+    });
+
+    Usion.game.onGameFinished(function(data) {
+      state.phase = 'finished';
+      state.winner = data.winner_ids && data.winner_ids[0] ? data.winner_ids[0] : 'draw';
+      render();
+    });
+
+    Usion.game.onGameRestarted(function() {
+      state.board = Array(BOARD_SIZE).fill(null);
+      state.winner = null;
+      state.currentTurn = state.playerIds[0];
+      state.phase = 'playing';
+      render();
+    });
+
+    Usion.game.onError(function(data) {
+      state.error = data.message || 'An error occurred';
+      render();
+    });
+
+    Usion.game.onDisconnect(function() {
+      state.error = 'Disconnected from server';
+      render();
+    });
+
+    Usion.game.onReconnect(function() {
+      state.error = null;
+      Usion.game.requestSync();
+      render();
+    });
+  });
+
+  // ─── Build DOM ─────────────────────────────────────────────
+  document.addEventListener('DOMContentLoaded', function() {
+    const app = document.getElementById('app');
+    if (!app) return;
+
+    app.innerHTML =
+      '<div id="error" class="error-banner" style="display:none"></div>' +
+      '<div id="status" class="status">Connecting...</div>' +
+      '<div id="board" class="board">' +
+        Array(BOARD_SIZE).fill(0).map(function(_, i) {
+          return '<div class="cell" onclick="window._cellClick(' + i + ')"></div>';
+        }).join('') +
+      '</div>' +
+      '<div id="overlay" class="overlay" style="display:none"></div>';
+
+    render();
+  });
+})();
+      `}</Script>
+
+      <div id="app" />
+
+      <style jsx global>{`
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        html, body { height: 100%; background: #000; color: #fff; font-family: -apple-system, system-ui, sans-serif; }
+
+        #app {
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          min-height: 100vh;
+          padding: 20px;
+        }
+
+        .error-banner {
+          position: fixed; top: 12px; left: 50%; transform: translateX(-50%);
+          background: #ff4444; color: #fff; padding: 8px 16px; border-radius: 8px;
+          font-size: 13px; z-index: 100; max-width: 90%;
+        }
+
+        .status {
+          font-size: 18px; font-weight: 600; margin-bottom: 24px;
+          color: #aaa; letter-spacing: 0.5px;
+        }
+
+        .board {
+          display: grid;
+          grid-template-columns: repeat(3, 1fr);
+          gap: 4px;
+          width: min(80vw, 300px);
+          aspect-ratio: 1;
+        }
+
+        .cell {
+          background: #111;
+          border-radius: 8px;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          font-size: 36px;
+          font-weight: 700;
+          color: #fff;
+          transition: background 0.15s;
+          cursor: default;
+          user-select: none;
+        }
+
+        .cell.clickable { cursor: pointer; background: #1a1a1a; }
+        .cell.clickable:hover { background: #222; }
+        .cell.taken { color: #fff; }
+
+        .overlay {
+          position: fixed; inset: 0;
+          background: rgba(0,0,0,0.85);
+          display: flex; flex-direction: column;
+          align-items: center; justify-content: center;
+          z-index: 50;
+        }
+
+        .overlay-text { font-size: 28px; font-weight: 700; margin-bottom: 20px; }
+
+        .rematch-btn {
+          background: #fff; color: #000; border: none;
+          padding: 12px 32px; border-radius: 8px;
+          font-size: 16px; font-weight: 600; cursor: pointer;
+        }
+        .rematch-btn:hover { background: #ddd; }
+      `}</style>
+    </>
+  );
+}

package/templates/turn-based/lib/constants.ts

@@ -0,0 +1,13 @@
+/** Game constants — tune these for your game */
+
+export const BOARD_SIZE = 9;
+
+export const WIN_LINES = [
+  [0, 1, 2], [3, 4, 5], [6, 7, 8], // rows
+  [0, 3, 6], [1, 4, 7], [2, 5, 8], // columns
+  [0, 4, 8], [2, 4, 6],             // diagonals
+];
+
+export const SYMBOLS = ['X', 'O', '△', '□'];
+
+export const MAX_PLAYERS = {{MAX_PLAYERS}};

package/templates/turn-based/lib/types.ts

@@ -0,0 +1,16 @@
+/** Game-specific types */
+
+export interface GameState {
+  board: (string | null)[];
+  currentTurn: string | null;
+  winner: string | null;
+  isDraw: boolean;
+}
+
+export interface PlayerInfo {
+  id: string;
+  name: string;
+  symbol: string;
+}
+
+export type GamePhase = 'connecting' | 'waiting' | 'playing' | 'finished';

package/templates/turn-based/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p {{PORT}} -H 0.0.0.0",
+    "build": "next build",
+    "start": "next start -p {{PORT}}",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "^14.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "typescript": "^5.3.0"
+  }
+}