@littlepartytime/sdk 2.0.1 → 2.2.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 | ≤ 20MB |
+| Total assets size | ≤ 100MB |
+| 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,47 @@ 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) |
+| `getDeviceCapabilities()` | Returns `{ haptics: boolean, motion: boolean }` indicating available device features |
+| `haptic(type, option?)` | Triggers haptic feedback. `type`: `'impact'` / `'notification'` / `'selection'`. Silent no-op if unsupported |
+| `onShake(handler)` | Listens for device shake events. Returns an unsubscribe function |
+| `onTilt(handler)` | Streams device tilt data (`{ alpha, beta, gamma }`) at ~60fps. Returns an unsubscribe function |
+
+#### Device Capabilities & Graceful Degradation
+
+Games can query runtime capabilities via `getDeviceCapabilities()` and provide fallback UI:
+
+```tsx
+const caps = platform.getDeviceCapabilities();
+
+// Shake: use motion sensor or fall back to a button
+useEffect(() => {
+  if (!caps.motion) return;
+  return platform.onShake(() => {
+    platform.haptic('impact', 'heavy');
+    platform.send({ type: 'ROLL_DICE' });
+  });
+}, [platform, caps.motion]);
+
+// Tilt: stream orientation data for motion-controlled games
+useEffect(() => {
+  if (!caps.motion) return;
+  return platform.onTilt((tilt) => {
+    // tilt.beta = front/back (-180~180), tilt.gamma = left/right (-90~90)
+    updateBallPosition(tilt.gamma, tilt.beta);
+  });
+}, [platform, caps.motion]);
+
+// Haptic feedback on user action (silent no-op if unsupported)
+platform.haptic('impact', 'light');
+```
+
+| Environment | Haptics | Motion (Shake/Tilt) |
+|---|---|---|
+| Native App (iOS/Android) | Full support (Impact/Notification/Selection) | Full support |
+| Web (Android Chrome) | Basic vibration | Supported |
+| Web (iOS Safari) | Not supported (silent) | Requires permission (handled by platform) |
+| Dev-kit preview | Not supported (silent) | Not supported |
 
 ### Events the renderer should listen for
 
@@ -753,6 +847,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/index.d.ts

@@ -1,3 +1,3 @@
-export type { Player, GameAction, GameResult, Platform } from './types';
+export type { Player, GameAction, GameResult, Platform, HapticImpactStyle, HapticNotificationType, DeviceTilt, DeviceCapabilities, } from './types';
 export type { PlayerState, GameState, GameAssets, GameConfig, GameEngine, GameRendererProps } from './interfaces';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,MAAM,EACN,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GACnB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -17,6 +17,20 @@ export interface GameResult {
     }[];
     data?: Record<string, unknown>;
 }
+export type HapticImpactStyle = 'light' | 'medium' | 'heavy';
+export type HapticNotificationType = 'success' | 'warning' | 'error';
+export interface DeviceTilt {
+    /** 绕 z 轴旋转 (0~360) —— 指南针方向 */
+    alpha: number;
+    /** 绕 x 轴旋转 (-180~180) —— 前后倾斜 */
+    beta: number;
+    /** 绕 y 轴旋转 (-90~90) —— 左右倾斜 */
+    gamma: number;
+}
+export interface DeviceCapabilities {
+    haptics: boolean;
+    motion: boolean;
+}
 export interface Platform {
     getPlayers(): Player[];
     getLocalPlayer(): Player;
@@ -24,5 +38,31 @@ 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;
+    /**
+     * 查询当前运行环境的设备能力。
+     * 游戏可据此决定是否启用某些交互，或提供视觉降级方案。
+     */
+    getDeviceCapabilities(): DeviceCapabilities;
+    /**
+     * 触发震动反馈。不支持时静默忽略。
+     */
+    haptic(type: 'impact' | 'notification' | 'selection', option?: HapticImpactStyle | HapticNotificationType): void;
+    /**
+     * 监听摇晃事件。平台负责处理权限请求和加速度阈值判定。
+     * @returns 取消监听的函数
+     */
+    onShake(handler: () => void): () => void;
+    /**
+     * 监听设备倾斜数据流。平台负责处理权限请求。
+     * @param handler 约 60fps 回调
+     * @returns 取消监听的函数
+     */
+    onTilt(handler: (tilt: DeviceTilt) => void): () => void;
 }
 //# 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,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC7D,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAErE,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;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;IAElC;;;OAGG;IACH,qBAAqB,IAAI,kBAAkB,CAAC;IAE5C;;OAEG;IACH,MAAM,CACJ,IAAI,EAAE,QAAQ,GAAG,cAAc,GAAG,WAAW,EAC7C,MAAM,CAAC,EAAE,iBAAiB,GAAG,sBAAsB,GAClD,IAAI,CAAC;IAER;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAEzC;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACzD"}

package/package.json

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