@littlepartytime/sdk 2.0.1 → 2.1.0

package/GAME_DEV_GUIDE.md

@@ -22,11 +22,16 @@ my-game/
 ├── vite.config.ts         # Build configuration
 ├── vitest.config.ts       # Test configuration
 ├── tsconfig.json
-├── assets/                # Required game images
+├── assets/                # Game images and custom assets
 │   ├── icon.png           # 1:1 (256x256+) - game list icon
 │   ├── banner.png         # 16:9 (640x360+) - lobby banner
 │   ├── cover.png          # 21:9 (840x360+) - store/featured cover
-│   └── splash.png         # 9:21 (360x840+) - loading screen
+│   ├── splash.png         # 9:21 (360x840+) - loading screen
+│   ├── cards/             # Custom game assets (optional)
+│   │   ├── king.png
+│   │   └── queen.png
+│   └── sounds/
+│       └── flip.mp3
 ├── src/
 │   ├── config.ts          # GameConfig - metadata
 │   ├── engine.ts          # GameEngine - server-side logic
@@ -592,7 +597,12 @@ The `.zip` upload package contains:
 ├── icon.png       # 1:1 game icon
 ├── banner.png     # 16:9 banner
 ├── cover.png      # 21:9 cover
-└── splash.png     # 9:21 splash screen
+├── splash.png     # 9:21 splash screen
+└── assets/        # Custom game assets (if any)
+    ├── cards/
+    │   └── king.png
+    └── sounds/
+        └── flip.mp3
 ```
 
 ### Configuration
@@ -663,18 +673,61 @@ Every game must include 4 images in the `assets/` directory. These are validated
 
 The `pack` command reads these images, validates them, and includes them in the zip with canonical names (`icon.png`, `banner.png`, etc.).
 
-### In-Game Assets (Audio, Fonts, etc.)
+### Custom Game Assets
 
-For assets used inside your game UI (not the 4 required images above), use one of these approaches:
+For assets used inside your game UI (card images, sound effects, fonts, etc.), place them in subdirectories under `assets/`:
+
+```
+assets/
+├── icon.png          # Platform display images (root level, required)
+├── banner.png
+├── cover.png
+├── splash.png
+├── cards/            # Custom game assets (subdirectories)
+│   ├── king.png
+│   └── queen.png
+└── sounds/
+    └── flip.mp3
+```
+
+Access custom assets in your renderer via `platform.getAssetUrl()`:
+
+```tsx
+export default function GameRenderer({ platform, state }: GameRendererProps) {
+  const cardImg = platform.getAssetUrl('cards/king.png');
+  const flipSound = platform.getAssetUrl('sounds/flip.mp3');
+
+  return (
+    <div>
+      <img src={cardImg} alt="King" />
+      <audio src={flipSound} />
+    </div>
+  );
+}
+```
+
+**How it works:**
+- During `lpt-dev-kit dev`: returns a local URL (e.g., `http://localhost:4000/assets/cards/king.png`)
+- In production: returns a CDN URL (the platform uploads assets to OSS automatically)
+
+**Validation rules (enforced by `pack` command):**
+
+| Rule | Limit |
+|------|-------|
+| Single file size | ≤ 10MB |
+| Total assets size | ≤ 50MB |
+| Allowed file types | `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg`, `.gif`, `.mp3`, `.wav`, `.ogg`, `.json`, `.woff2`, `.woff` |
+| Path rules | No `..`, no spaces |
+
+**Alternative approaches for small assets:**
 
 | Approach | When to Use | How |
 |----------|-------------|-----|
-| **Inline in bundle** | Small assets (icons, sounds < 100KB) | Vite automatically inlines assets below `assetsInlineLimit` (default 4KB) as data URLs. Increase the limit in `vite.config.ts` if needed: `build: { assetsInlineLimit: 100000 }` |
-| **External URL** | Large assets (images, audio, video) | Host on a CDN or external server, reference by absolute URL in your code |
-| **CSS/SVG** | UI elements, icons | Use Tailwind CSS utilities, inline SVG components, or CSS gradients/shapes |
-| **Emoji/Unicode** | Simple visual indicators | Use Unicode characters directly in JSX |
+| **Inline in bundle** | Tiny assets (< 4KB) | Vite automatically inlines as data URLs |
+| **CSS/SVG** | UI elements, icons | Tailwind CSS utilities or inline SVG components |
+| **Emoji/Unicode** | Simple visual indicators | Unicode characters directly in JSX |
 
-> **Tip:** Keep your bundle under 5MB. The `pack` command warns if `bundle.js` exceeds this limit.
+> **Tip:** Use `platform.getAssetUrl()` for assets 100KB+ instead of inlining them into the bundle.
 
 ### Submitting Your Game
 
@@ -695,6 +748,7 @@ For assets used inside your game UI (not the 4 required images above), use one o
 | `on(event, handler)` | Listens for events from the server |
 | `off(event, handler)` | Removes an event listener |
 | `reportResult(result)` | Reports game results (called by platform, not games) |
+| `getAssetUrl(path)` | Returns the runtime URL for a custom asset (e.g., `"cards/king.png"` → CDN URL) |
 
 ### Events the renderer should listen for
 
@@ -753,6 +807,113 @@ Use these CSS variables / Tailwind classes for consistent styling:
 | Display font | `--font-display` | `font-display` |
 | Body font | `--font-body` | `font-body` |
 
+## Platform Runtime Constraints
+
+The production platform runs game engines inside a Node.js `vm` sandbox. The dev-kit (`npm run dev`) automatically enforces key constraints so issues surface during local development, not after deployment.
+
+### Timer APIs Are Disabled
+
+The sandbox replaces `setTimeout`, `setInterval`, `clearTimeout`, and `clearInterval` with no-ops. Calling them inside engine code will:
+
+- **In production**: silently do nothing (the callback is never executed)
+- **In dev-kit**: print a warning to the console and return `0`
+
+```typescript
+// BAD - will not work in production
+handleAction(state, playerId, action) {
+  setTimeout(() => {
+    // This callback will NEVER run in the sandbox
+  }, 2000);
+  return { ...state, phase: 'animating' };
+}
+
+// GOOD - let the client handle timing
+handleAction(state, playerId, action) {
+  return { ...state, phase: 'animating' };
+}
+// In renderer: after animation completes, send a follow-up action:
+//   platform.send({ type: 'ANIMATION_DONE' })
+// Engine handles ANIMATION_DONE to advance to the next phase.
+```
+
+### State Must Be JSON-Serializable
+
+The platform stores game state in Redis via `JSON.stringify` / `JSON.parse` round-trips. Non-serializable types will silently lose data:
+
+| Type | After JSON Round-Trip | Result |
+|------|----------------------|--------|
+| `Map` | `{}` | Data lost |
+| `Set` | `{}` | Data lost |
+| `Date` | `"2026-02-10T..."` (string) | Type changed |
+| `undefined` | Removed | Field disappears |
+| `RegExp` | `{}` | Data lost |
+| Function | Removed | Lost |
+
+The dev-kit checks your state after every `init()` and `handleAction()` call and prints warnings if non-serializable types are detected.
+
+```typescript
+// BAD
+data: {
+  players: new Map([['p1', { score: 0 }]]),
+  seen: new Set(['card-1']),
+  createdAt: new Date(),
+}
+
+// GOOD
+data: {
+  players: { p1: { score: 0 } },
+  seen: ['card-1'],
+  createdAt: '2026-02-10T00:00:00.000Z',
+}
+```
+
+### Engine Instance Is Shared
+
+The platform loads your engine bundle once and reuses it across all game rooms. This means **module-level mutable variables are shared between games**:
+
+```typescript
+// BAD - shared across all rooms!
+let gameCounter = 0;
+
+const engine: GameEngine = {
+  init(players) {
+    gameCounter++; // Will increment across different rooms
+    // ...
+  },
+};
+
+// GOOD - all state lives in GameState
+const engine: GameEngine = {
+  init(players) {
+    return {
+      phase: 'playing',
+      players: players.map(p => ({ id: p.id })),
+      data: { roundNumber: 1 },  // State is per-room
+    };
+  },
+};
+```
+
+### Restricted Global Variables
+
+The following globals are `undefined` in the sandbox:
+
+| Global | Alternative |
+|--------|-------------|
+| `fetch` | Not available. Engines cannot make network calls. |
+| `process` | Not available. |
+| `globalThis` | Not available. |
+| `global` | Not available. |
+
+Available built-ins: `Math`, `JSON`, `Date`, `Array`, `Object`, `Map`, `Set`, `Number`, `String`, `Boolean`, `Error`, `TypeError`, `RangeError`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `console` (log/error/warn).
+
+### `require()` Whitelist
+
+Only the following modules can be required in engine code (all are stubs for compatibility):
+`react`, `react/jsx-runtime`, `react-dom`, `react-dom/client`
+
+Any other `require()` call will throw an error.
+
 ## Data Flow Diagram
 
 ```

package/dist/types.d.ts

@@ -24,5 +24,11 @@ export interface Platform {
     on(event: string, handler: (...args: unknown[]) => void): void;
     off(event: string, handler: (...args: unknown[]) => void): void;
     reportResult(result: GameResult): void;
+    /**
+     * 获取游戏资产的运行时 URL。
+     * @param path - 相对于游戏 assets/ 目录的路径，如 "cards/king.png"、"sounds/flip.mp3"
+     * @returns 可直接用于 <img src> / <audio src> / fetch() 的完整 URL
+     */
+    getAssetUrl(path: string): string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC;KACnB,EAAE,CAAC;IACJ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,IAAI,MAAM,EAAE,CAAC;IACvB,cAAc,IAAI,MAAM,CAAC;IACzB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAChE,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC;KACnB,EAAE,CAAC;IACJ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,IAAI,MAAM,EAAE,CAAC;IACvB,cAAc,IAAI,MAAM,CAAC;IACzB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAChE,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlepartytime/sdk",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Game SDK for Little Party Time platform - type definitions and testing utilities",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",