@uzuhq/code-sdk 0.7.6 → 0.8.0

package/README.md

@@ -223,7 +223,7 @@ import type { GameLogic } from '@uzuhq/code-sdk';
 
 const logic: GameLogic<MyState> = {
   setup({ players, ctx }) {
-    // 初期 state を生成。ctx.random は SeededRandom、ctx.now はサーバーの実時刻。
+    // 初期 state を生成。ctx.random は SeededRandom、ctx.time はゲーム内時刻 (必ず 0)。
     // players は配役を受け取る参加者だけで、観測者は含まれない
     return { players: {}, items: [] };
   },
@@ -235,24 +235,24 @@ const logic: GameLogic<MyState> = {
       state.players[playerId].x += payload.dx;
       // ctx.emit でイベント発火 (購読側は events で predict を宣言する)
       ctx.emit('sound', { sound: 'step' });
-      // 時刻は ctx.now を使う。Date.now() は端末とサーバーでズレる
+      // 時刻は ctx.after(d) を使う。Date.now() は epoch が違う (Unix ms vs ゲーム内時刻)
     },
   },
 
   // サーバーでのみ走る。実時刻・乱数・fetch などクライアントが再現できない処理。
   // actions と同名にすると「同じ action のサーバー側の続き」になる。
   serverActions: {
-    async notifyExternal({ state, payload, playerId }) {
+    async notifyExternal({ state, payload, playerId, ctx }) {
       await fetch('https://example.com/notify', {
         method: 'POST',
         body: JSON.stringify({ playerId, ...payload }),
       });
-      state.notifiedAt = Date.now();
+      state.notifiedAt = ctx.time;
     },
   },
 
   update({ state, ctx }) {
-    // 毎 tick 実行。ctx.tick / ctx.random / ctx.now / ctx.emit / ctx.playerInputs が使える
+    // 毎 tick 実行。ctx.tick / ctx.random / ctx.time / ctx.after / ctx.emit / ctx.playerInputs が使える
   },
 
   tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし)
@@ -287,10 +287,10 @@ deadlines: {
 },
 ```
 
-|           |                                                                                                                                                                         |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `at`      | 締切の絶対時刻 (ms)。`null` / `undefined` で締切なし (optional chain の結果をそのまま返せる)。**state だけから決まる軽い関数にすること** (state が変わるたびに呼ばれる) |
-| `handler` | サーバーでのみ走る。`ctx` は `{ now, random, emit }`                                                                                                                    |
+|           |                                                                                                                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `at`      | 締切の[ゲーム内時刻](#ゲーム内時計) (`GameTime`)。`null` / `undefined` で締切なし (optional chain の結果をそのまま返せる)。**state だけから決まる軽い純関数にすること** (state が変わるたびに呼ばれる) |
+| `handler` | サーバーでのみ走る。`ctx` は `{ time, after, random, emit }`                                                                                                                                           |
 
 締切は state から導出するので、**予約を張り替える処理を書かなくてよい**。action が throw して
 state が巻き戻れば締切も一緒に巻き戻る。発火直前に `at` を評価し直すので、二重発火を
@@ -299,6 +299,49 @@ handler 側で弾く必要も無い。
 時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
 ポーリング中は Durable Object が hibernate できない。
 
+### ゲーム内時計
+
+**時刻は Unix epoch ではない。** `ctx.time` はゲーム開始からの経過 ms (`GameTime`) で、
+[緊急一時停止](#緊急一時停止)中は進まない。`Date.now()` とは桁も意味も違う。
+
+| API                          | 意味                                                              |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `ctx.time`                   | そのハンドラが走っているゲーム内時刻。`setup` では必ず `0`        |
+| `ctx.after(d)`               | 今から `d` ms 後のゲーム内時刻。締切を state に置くときに使う     |
+| `gameTime()`                 | 描画側で読む現在のゲーム内時刻 (推定値)。`performance.now()` 基準 |
+| `plus(t, d)` / `minus(a, b)` | 時刻に長さを足す / 2 つの時刻の差を取る                           |
+
+```ts
+import { gameTime, minus } from '@uzuhq/code-sdk';
+
+// 締切を置く
+actions: {
+  startPhase: ({ state, ctx }) => { state.phaseEndsAt = ctx.after(5 * 60_000); },
+},
+
+// 残り時間を描く
+const remain = Math.ceil(minus(state.phaseEndsAt, gameTime()) / 1000);
+```
+
+`GameTime` は `number` の brand 型なので、実行時はただの数値。state は素の JSON のまま。
+`Date.now()` を `GameTime` の場所に入れると TypeScript が弾く。
+
+### 緊急一時停止
+
+プレイヤーが UZU メニューから全員のタイマーを止められる。**シナリオは停止を知らないし、
+知る必要も無い。** 停止中は `update()` が呼ばれず、action はサーバーが弾き、締切も来ない。
+
+演出だけを止めたいときに限り、読み取り専用で参照できる。
+
+```ts
+import { isPaused, onPauseChange } from '@uzuhq/code-sdk';
+
+onPauseChange((paused) => (paused ? engine.stop() : engine.start()));
+```
+
+`GameLogic` からは触れない。停止を state に持ち込むと「停止中は state が変わらない」という
+前提が崩れる。
+
 #### `serverOnly(handler)`
 
 > **Deprecated**: `serverActions` に直接書く。

package/dist/dev-globals.d.ts

@@ -1,28 +1,13 @@
-/**
- * scenario 側 (`test/*.ts` / `tools/*.ts`) から `window.__uzu_dev` を
- * 補完 + 型チェック付きで呼べるようにする ambient module。
- *
- * 使い方: scenario の `tsconfig.json` で
- *
- * ```jsonc
- * { "compilerOptions": { "types": ["@uzuhq/code-sdk/dev-globals"] } }
- * ```
- *
- * SDK 自身を import するコード (= `@uzuhq/code-sdk` の named import を持つ
- * モジュール) では `dev-hooks.ts` 側の `declare global` で同じ型が既に効く
- * ため、本 module を `types` に足す必要はない。target は import しない
- * scenario test/tools のみ。
- */
-import type { UzuDevHooks } from './dev-hooks.js';
+import { i as UzuDevHooks } from "./dev-hooks-D6CbhPDP.js";
+//#region src/dev-globals.d.ts
 declare global {
-    interface Window {
-        /**
-         * dev harness / Playwright / 単独 page で attach される dev hooks。
-         * 本番 (Flutter native ホスト) では undefined。
-         * - run() devHarness: 親 frame に attach (authoritative state)
-         * - sync() / online: 子 frame で undefined
-         */
-        __uzu_dev?: UzuDevHooks<unknown>;
-    }
-}
-export {};
+  interface Window {
+    /**
+     * dev harness / Playwright / 単独 page で attach される dev hooks。
+     * 本番 (Flutter native ホスト) では undefined。
+     * - run() devHarness: 親 frame に attach (authoritative state)
+     * - sync() / online: 子 frame で undefined
+     */
+    __uzu_dev?: UzuDevHooks<unknown>;
+  }
+}

package/dist/dev-globals.js

@@ -1,16 +1 @@
-/**
- * scenario 側 (`test/*.ts` / `tools/*.ts`) から `window.__uzu_dev` を
- * 補完 + 型チェック付きで呼べるようにする ambient module。
- *
- * 使い方: scenario の `tsconfig.json` で
- *
- * ```jsonc
- * { "compilerOptions": { "types": ["@uzuhq/code-sdk/dev-globals"] } }
- * ```
- *
- * SDK 自身を import するコード (= `@uzuhq/code-sdk` の named import を持つ
- * モジュール) では `dev-hooks.ts` 側の `declare global` で同じ型が既に効く
- * ため、本 module を `types` に足す必要はない。target は import しない
- * scenario test/tools のみ。
- */
 export {};