@littlepartytime/sdk 2.1.0 → 2.2.1

package/GAME_DEV_GUIDE.md

@@ -714,8 +714,8 @@ export default function GameRenderer({ platform, state }: GameRendererProps) {
 
 | Rule | Limit |
 |------|-------|
-| Single file size | ≤ 10MB |
-| Total assets size | ≤ 50MB |
+| 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 |
 
@@ -749,6 +749,46 @@ export default function GameRenderer({ platform, state }: GameRendererProps) {
 | `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
 
@@ -942,6 +982,101 @@ Renderer receives "stateUpdate" event with filtered state
 React re-renders with new state
 ```
 
+## Game Settlement Lifecycle
+
+When `isGameOver()` returns `true`, the platform **immediately** takes over: it sends `game:result` to all clients, transitions to the settlement screen, and **unloads the game renderer**. This happens in the same tick as the final `game:state` broadcast:
+
+```
+engine.handleAction(state, playerId, action) → newState
+broadcastPlayerViews(newState)          ← last game frame sent
+engine.isGameOver(newState) → true
+handleGameEnd()                         ← platform takes over, renderer unloaded
+```
+
+If your game needs an in-game settlement screen (animations, rankings, replay, etc.), you **must not** let `isGameOver()` return `true` until that screen is done.
+
+### Two-Phase Settlement Pattern
+
+Split game ending into two phases:
+
+```
+playing → (winner decided) → settlement → (player confirms or timer expires) → finished
+                               ↑                                                  ↑
+                        isGameOver = false                                 isGameOver = true
+                        game renderer shows                                platform takes over
+                        its own result screen
+```
+
+#### Engine Implementation
+
+```typescript
+handleAction(state: GameState, playerId: string, action: GameAction): GameState {
+  const data = state.data as MyGameData;
+
+  // 1. Normal gameplay — when winner is decided, enter settlement
+  if (state.phase === "playing" && winnerDecided(data)) {
+    return {
+      ...state,
+      phase: "settlement",
+      data: { ...data, rankings: computeRankings(data) },
+    };
+  }
+
+  // 2. Settlement — wait for confirm action, then finish
+  if (state.phase === "settlement" && action.type === "CONFIRM_RESULT") {
+    return { ...state, phase: "finished" };
+  }
+
+  return state;
+},
+
+isGameOver(state: GameState): boolean {
+  return state.phase === "finished";   // NOT "settlement"!
+},
+
+getPlayerView(state: GameState, playerId: string): Partial<GameState> {
+  if (state.phase === "settlement") {
+    // Return rankings / stats for the in-game result screen
+    return {
+      ...state,
+      data: { rankings: (state.data as MyGameData).rankings },
+    };
+  }
+  // ...
+},
+```
+
+#### Renderer Implementation
+
+```tsx
+export default function GameRenderer({ platform, state }: GameRendererProps) {
+  if (state.phase === "settlement") {
+    return (
+      <div>
+        {/* Show your in-game result screen here */}
+        <Rankings data={state.data.rankings} />
+        <button onClick={() => platform.send({ type: "CONFIRM_RESULT" })}>
+          确认
+        </button>
+      </div>
+    );
+  }
+  // ... normal gameplay UI
+}
+```
+
+### Common Mistakes
+
+| Mistake | Consequence |
+|---------|------------|
+| `isGameOver()` returns `true` in `settlement` phase | In-game result screen is skipped — platform unloads the renderer immediately |
+| No `settlement` phase; jumping straight from `playing` to `finished` | Players never see the in-game result animation / ranking |
+| Calling `platform.reportResult()` from the renderer | No-op — settlement is driven entirely by the server via `isGameOver` + `getResult` |
+
+### One-Liner Rule
+
+> **`isGameOver()` is the platform takeover switch. Do not return `true` until your in-game result screen is done.**
+
 ## Complete Example: Number Guessing Game
 
 See the [`examples/number-guess`](../../examples/number-guess) directory for a complete working example.

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/interfaces.d.ts

@@ -32,6 +32,16 @@ export interface GameConfig {
 export interface GameEngine {
     init(players: Player[], options?: Record<string, unknown>): GameState;
     handleAction(state: GameState, playerId: string, action: GameAction): GameState;
+    /**
+     * Called after every handleAction. When this returns true, the platform
+     * immediately sends game:result, unloads the renderer, and shows the
+     * platform settlement screen.
+     *
+     * If your game has an in-game result screen (animations, rankings, etc.),
+     * keep returning false during that phase and only return true when the
+     * in-game result screen is done. See "Game Settlement Lifecycle" in
+     * GAME_DEV_GUIDE.md.
+     */
     isGameOver(state: GameState): boolean;
     getResult(state: GameState): GameResult;
     getPlayerView(state: GameState, playerId: string): Partial<GameState>;

package/dist/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAChF,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACxC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3B"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAChF;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACxC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3B"}

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;
@@ -30,5 +44,25 @@ export interface Platform {
      * @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;IACvC;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC"}
+{"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.1.0",
+  "version": "2.2.1",
   "description": "Game SDK for Little Party Time platform - type definitions and testing utilities",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",