@uzuhq/code-sdk 0.7.1 → 0.7.2

package/README.md

@@ -271,8 +271,34 @@ const logic: GameLogic<MyState> = {
 ハンドラの引数は 1 つのオブジェクトで、使うものだけ書けばよい。
 `state` / `payload` / `playerId` はその呼び出しの事実、`ctx` は実行環境が与えるもの。
 
-時刻起点で何かを起こしたい場合は `tickRate` で毎秒ポーリングせず `ctx.schedule()` を使う。
-サーバーが指定時刻に自分で起きて action を撃つので、その間 Durable Object が hibernate できる。
+#### `deadlines`
+
+「state のこの時刻を過ぎたらこれをする」を宣言する。サーバーが最も早い `at` に合わせて
+自分で起き、過ぎた締切の `handler` を呼ぶ。
+
+```ts
+deadlines: {
+  phaseTimer: {
+    at: ({ state }) => state.timerEndsAt,   // null / undefined なら締切なし
+    handler: ({ state, ctx }) => {
+      state.phase = nextPhase(state);
+      ctx.emit('phase.changed', { phase: state.phase });
+    },
+  },
+},
+```
+
+|           |                                                                                                                                                                         |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `at`      | 締切の絶対時刻 (ms)。`null` / `undefined` で締切なし (optional chain の結果をそのまま返せる)。**state だけから決まる軽い関数にすること** (state が変わるたびに呼ばれる) |
+| `handler` | サーバーでのみ走る。`ctx` は `{ now, random, emit }`                                                                                                                    |
+
+締切は state から導出するので、**予約を張り替える処理を書かなくてよい**。action が throw して
+state が巻き戻れば締切も一緒に巻き戻る。発火直前に `at` を評価し直すので、二重発火を
+handler 側で弾く必要も無い。
+
+時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
+ポーリング中は Durable Object が hibernate できない。
 
 #### `serverOnly(handler)`
 

package/dist/index.d.ts

@@ -15,8 +15,8 @@
  * scenario ディレクトリで `uzu dev` を実行するだけで良い。 子 iframe は既存 online mode
  * (`?server=ws://localhost:<port>` 経路) で dev-server に接続する。
  */
-export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionArgs, ActionContext, ActionHandler, ServerActionArgs, SetupArgs, SetupContext, UpdateArgs, UpdateContext, EventHandler, EventSubscription, ScheduleOptions, Scheduler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
-export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } from './types.js';
+export type { PlayScreenMessage, BridgeChannel, BridgeMessage, Seat, SeatKind, Emit, ServerEvent, SeededRandom, GameLogic, GameConfig, SyncConfig, PatchFn, SetFn, Operation, ConnectionState, ConnectionCallbacks, PlayerVoiceState, PlayersChangedMessage, ActionArgs, ActionContext, ActionHandler, ServerActionArgs, SetupArgs, SetupContext, UpdateArgs, UpdateContext, EventHandler, EventSubscription, Deadline, DeadlineArgs, DeadlineContext, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
+export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
 export { serverNow } from './server-clock.js';
 export { Room } from './room.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } from './types.js';
+export { SERVER_TIME, DEFAULT_ICON_URLS } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
 export { serverNow } from './server-clock.js';
 export { Room } from './room.js';

package/dist/run/local-server-action.js

@@ -15,33 +15,82 @@ export function runLocalServerAction(config) {
     }));
     const myId = players[0].id;
     // イベント収集→一括配信（DO と同じパターン）
-    // ソロモードでは alarm の代わりに setTimeout で予約を実現する。
-    // key ごとに 1 件へ畳む点は本番と同じ。
-    const scheduled = new Map();
-    const makeScheduleCtx = () => ({
-        schedule(options) {
-            const at = options.at ?? Date.now() + (options.after ?? 0) * 1000;
-            const prev = scheduled.get(options.key);
-            if (prev)
-                clearTimeout(prev);
-            scheduled.set(options.key, setTimeout(() => {
-                scheduled.delete(options.key);
-                try {
-                    dispatchAction(options.action, options.payload ?? {});
-                }
-                catch (err) {
-                    console.error(`[Scheduler] ❌ key=${options.key}:`, err);
-                }
-            }, Math.max(0, at - Date.now())));
-            return at;
-        },
-        unschedule(key) {
-            const t = scheduled.get(key);
-            if (t)
-                clearTimeout(t);
-            scheduled.delete(key);
-        },
-    });
+    // ソロモードでは alarm の代わりに setTimeout で締切に起きる。締切は state から
+    // 導出するので、state を変えたら syncWakeup() を通すだけでよい。
+    let wakeupTimer = null;
+    let wakeupAt = null;
+    const nextDeadline = () => {
+        if (!logic.deadlines)
+            return null;
+        let earliest = null;
+        for (const [key, deadline] of Object.entries(logic.deadlines)) {
+            let at;
+            try {
+                at = deadline.at({ state });
+            }
+            catch (err) {
+                console.error(`[Deadline] ❌ ${key}.at() で例外`, err);
+                continue;
+            }
+            if (typeof at !== 'number' || !Number.isFinite(at))
+                continue;
+            if (earliest === null || at < earliest)
+                earliest = at;
+        }
+        return earliest;
+    };
+    const fireDue = () => {
+        wakeupTimer = null;
+        wakeupAt = null;
+        if (!logic.deadlines)
+            return;
+        const now = Date.now();
+        const evts = [];
+        const firedKeys = [];
+        for (const [key, deadline] of Object.entries(logic.deadlines)) {
+            // handler が emit してから throw したときに捨てられるよう、締切ごとに溜める。
+            // state を戻したのに音や演出だけ流れると、起きていない出来事が見えてしまう。
+            const pending = [];
+            let snapshot = null;
+            try {
+                const at = deadline.at({ state });
+                if (typeof at !== 'number' || !Number.isFinite(at) || at > now)
+                    continue;
+                // 期限が来たものだけ複製する。毎周撮ると締切の数だけ state の複製が走る。
+                snapshot = structuredClone(state);
+                deadline.handler({
+                    state,
+                    ctx: { now, random, emit: (name, data) => pending.push({ name, data: data ?? {} }) },
+                });
+                evts.push(...pending);
+                firedKeys.push(key);
+            }
+            catch (err) {
+                // サーバー (DO) 側と同じく、失敗した締切ぶんだけ巻き戻す。
+                if (snapshot !== null)
+                    state = snapshot;
+                console.error(`[Deadline] ❌ ${key} で例外`, err);
+            }
+        }
+        syncWakeup();
+        if (firedKeys.length === 0)
+            return;
+        console.log(`[Deadline] ⏰ ${firedKeys.length} 件発火: ${firedKeys.join(', ')}`);
+        dispatchEvents(evts);
+        onState(state, myId);
+    };
+    const syncWakeup = () => {
+        const next = nextDeadline();
+        if (next === wakeupAt)
+            return;
+        if (wakeupTimer)
+            clearTimeout(wakeupTimer);
+        wakeupTimer = null;
+        wakeupAt = next;
+        if (next === null)
+            return;
+        wakeupTimer = setTimeout(fireDue, Math.max(0, next - Date.now()));
+    };
     // ソロモードはこのクライアント自身がサーバーなので、先読みという概念が無い。
     // predict の値によらず、確定として 1 回だけ実行する。
     const dispatchEvents = (evts) => {
@@ -80,7 +129,7 @@ export function runLocalServerAction(config) {
                     state,
                     payload: payload ?? {},
                     playerId: myId,
-                    ctx: { now, emit: plainEmit, ...makeScheduleCtx() },
+                    ctx: { now, emit: plainEmit },
                 });
             }
             catch (err) {
@@ -88,6 +137,7 @@ export function runLocalServerAction(config) {
                 return;
             }
             dispatchEvents(plainEvents);
+            syncWakeup();
             onState(state, myId);
         }
         if (!server)
@@ -98,7 +148,7 @@ export function runLocalServerAction(config) {
                     state,
                     payload: payload ?? {},
                     playerId: myId,
-                    ctx: { tick, random, now, emit: serverEmit, ...makeScheduleCtx() },
+                    ctx: { tick, random, now, emit: serverEmit },
                 });
             }
             catch (err) {
@@ -106,10 +156,12 @@ export function runLocalServerAction(config) {
                 return;
             }
             dispatchEvents(serverEvents);
+            syncWakeup();
             onState(state, myId);
         })();
     };
     inputs(dispatchAction);
+    syncWakeup();
     onState(state, myId);
     // Tick ループ（tickRate > 0 の場合のみ、DO と同じ）
     if (tickRate > 0) {
@@ -123,7 +175,6 @@ export function runLocalServerAction(config) {
                         random,
                         tick,
                         now: Date.now(),
-                        ...makeScheduleCtx(),
                         emit: tickEmit,
                         playerInputs,
                     },
@@ -136,6 +187,7 @@ export function runLocalServerAction(config) {
             }
             tick++;
             dispatchEvents(tickEvents);
+            syncWakeup();
             onState(state, myId);
         }, 1000 / tickRate);
     }
@@ -143,6 +195,7 @@ export function runLocalServerAction(config) {
         getRawState: () => state,
         setRawState: async (next) => {
             state = next;
+            syncWakeup();
             onState(state, myId);
         },
         mergeRawState: async (patch) => {

package/dist/run/optimistic-action-client.js

@@ -41,18 +41,6 @@ export function createOptimisticActionClient(config) {
     };
     /** events の同一性キー。name と data が一致すれば「同じ出来事」とみなす。 */
     const eventKey = (e) => `${e.name}\u0000${JSON.stringify(e.data ?? {})}`;
-    /**
-     * 先読み用の schedule。予約自体はサーバーだけが持つので**何もしない**が、
-     * 戻り値 (確定した絶対時刻) は返す。シナリオは戻り値を表示用の endsAt として
-     * state に入れるので、ここで undefined を返すと先読み中だけタイマーが消える。
-     *
-     * 型には schedule があるのに実体を渡さないと `ctx.schedule is not a function` で
-     * 先読みが丸ごと落ちる (predicted な action から呼ばれた瞬間)。
-     */
-    const predictedScheduleCtx = (now) => ({
-        schedule: (options) => options.at != null ? Number(options.at) : now + Number(options.after ?? 0) * 1000,
-        unschedule: () => { },
-    });
     /**
      * サーバーの events から、先読みで実行済みのものを差し引く (多重集合の差)。
      *
@@ -102,7 +90,7 @@ export function createOptimisticActionClient(config) {
                     state: displayState,
                     payload,
                     playerId,
-                    ctx: { now, emit: noopEmit, ...predictedScheduleCtx(now) },
+                    ctx: { now, emit: noopEmit },
                 }));
                 i++;
             }
@@ -159,7 +147,7 @@ export function createOptimisticActionClient(config) {
                         state: target,
                         payload: payload ?? {},
                         playerId,
-                        ctx: { now, emit: predictEmit, ...predictedScheduleCtx(now) },
+                        ctx: { now, emit: predictEmit },
                     }));
                     pendingActions.push({ seq, action: type, payload: payload ?? {}, now });
                     onState(target, playerId);

package/dist/run/optimistic-action-client.test.js

@@ -28,14 +28,6 @@ const makeLogic = () => ({
             state.stampedAt = ctx.now;
             ctx.emit('moved', {});
         },
-        // 先読みでも ctx.schedule を呼ぶ action。型にはあるので呼べてしまう。
-        startTimer: ({ state, ctx }) => {
-            state.stampedAt = ctx.schedule({
-                key: 'timer',
-                after: 60,
-                action: 'timer.fire',
-            });
-        },
         // 予測の結果によって別の event を出す (予測ミスの再現用)
         guess: ({ state, payload, ctx }) => {
             state.moves += 1;
@@ -416,23 +408,6 @@ describe('createOptimisticActionClient', () => {
             expect(latest(states).stampedAt).toBeGreaterThanOrEqual(before);
             expect(latest(states).stampedAt).toBeLessThanOrEqual(Date.now());
         });
-        /**
-         * IMPORTANT: 型に schedule があるので、先読みされる action からも呼べてしまう。
-         * 実体を渡していないと `ctx.schedule is not a function` で先読みが丸ごと落ちる。
-         *
-         * 予約自体はサーバーだけが持つので先読みでは何もしないが、戻り値 (絶対時刻) は
-         * 返す必要がある。シナリオはそれを表示用の endsAt として state に入れるため、
-         * undefined を返すと先読み中だけタイマーが消える。
-         */
-        it('先読みでも ctx.schedule が呼べて絶対時刻を返す', () => {
-            const { client, states, sent } = setup();
-            client.send('startTimer');
-            // 先読みが落ちていたら pending に積まれず state も変わらない
-            expect(sent).toEqual([{ action: 'startTimer', seq: 1 }]);
-            const stamped = latest(states).stampedAt;
-            expect(stamped).toBeGreaterThanOrEqual(Date.now() + 60000 - 5000);
-            expect(stamped).toBeLessThanOrEqual(Date.now() + 60000 + 5000);
-        });
         /**
          * IMPORTANT: 再適用 (reconciliation でのやり直し) では初回予測時の now を使い回す。
          *

package/dist/types.d.ts

@@ -104,45 +104,50 @@ export interface ActionContext {
      */
     now: number;
     emit: Emit;
-    /** 予約はサーバーだけが持つ。先読みでは戻り値を計算するだけで、予約も取り消しもしない。 */
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
 }
-/** 予約されたタイマーの識別子付き宣言。 */
-export interface ScheduleOptions {
-    /** 予約の識別子。同じ key で予約し直すと置き換わる (古い予約が残ると二重に発火する)。 */
-    key: string;
-    /** 絶対時刻 (ms)。`after` と排他。過去なら即座に発火する。 */
-    at?: number;
-    /** 何秒後か。`at` と排他。 */
-    after?: number;
-    action: string;
-    payload?: Record<string, unknown>;
+/** `deadlines` handler の実行文脈。サーバーでしか走らないので tick 以外を渡せる。 */
+export interface DeadlineContext {
+    /** 発火時刻 (ms)。サーバー専用なので常に正確。 */
+    now: number;
+    random: SeededRandom;
+    emit: Emit;
+}
+/** `deadlines` handler の引数。 */
+export interface DeadlineArgs<S> {
+    state: S;
+    ctx: DeadlineContext;
 }
 /**
- * サーバー権威のタイマー。
+ * サーバー権威の締切。
+ *
+ * 「state のこの時刻を過ぎたらこれをする」を宣言する。サーバーが `at` の最も早いものに
+ * 合わせて自分で起き、過ぎた締切の `handler` を呼ぶ。`tickRate` で毎秒ポーリングする
+ * 必要が無くなり、その間 Durable Object は hibernate できる。
  *
- * クライアントの時計やアプリのバックグラウンド化に依存せず、サーバーが指定時刻に
- * 自分で起きて action を撃つ。`tickRate` で毎秒ポーリングする必要が無くなり、
- * その間 Durable Object は hibernate できる。
+ * 締切は state から導出するので、予約を張り替える処理を書かなくてよい。action が
+ * throw して state が巻き戻れば、締切も一緒に巻き戻る。
  */
-export interface Scheduler {
+export interface Deadline<S> {
+    /**
+     * 締切の絶対時刻 (ms)。締切が無いときは null / undefined。
+     *
+     * `state.timer?.endsAt` のような optional chain の結果をそのまま返せるよう
+     * undefined も受ける。数値以外は「締切なし」として同じに扱う。
+     *
+     * state が変わるたびに呼ばれるので、state だけから決まる軽い関数にすること。
+     * ここで実時刻や乱数を読むと、呼ばれるたびに答えが変わって予約が暴れる。
+     */
+    at(args: {
+        state: S;
+    }): number | null | undefined;
     /**
-     * 予約して確定した絶対時刻 (ms) を返す。表示用の endsAt にそのまま使える。
+     * `at` の時刻を過ぎたときにサーバーで呼ばれる。
      *
-     * 発火は at-least-once。同じ予約が 2 回実行されうるので、handler 側で「自分が予約した
-     * ものか」を state と突き合わせて弾くこと (action 名や key では区別できない)。
+     * 発火は at-least-once だが、SDK が発火直前に `at` を評価し直して過ぎているものだけを
+     * 呼ぶので、handler 側で二重発火を弾く必要は無い。
      */
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
+    handler(args: DeadlineArgs<S>): void;
 }
-/**
- * 予約から発火した action に渡る playerId。
- *
- * 送信者がいないので、人間の操作と区別するための定数。
- * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
- */
-export declare const SCHEDULED_ACTOR = "__scheduled";
 /** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
 export interface ServerActionContext {
     tick: number;
@@ -150,8 +155,6 @@ export interface ServerActionContext {
     /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
     now: number;
     emit: Emit;
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
 }
 /** @deprecated `ServerActionContext` を使う。 */
 export type ServerOnlyActionContext = ServerActionContext;
@@ -191,8 +194,6 @@ export interface UpdateContext {
     tick: number;
     /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
     now: number;
-    schedule(options: ScheduleOptions): number;
-    unschedule(key: string): void;
     emit: Emit;
     playerInputs: Record<string, Record<string, any>>;
 }
@@ -204,7 +205,6 @@ export interface UpdateArgs<S> {
  * `setup()` の実行文脈。サーバーでしか走らないので実時刻をそのまま渡せる。
  *
  * `emit` は無い。まだ誰も購読していない時点なので、鳴らしても届かない。
- * `schedule` も無い。開幕から予約したい要求が出たら足す。
  */
 export interface SetupContext {
     random: SeededRandom;
@@ -239,6 +239,13 @@ export interface GameLogic<S> {
      */
     serverActions?: Record<string, ServerActionHandler<S>>;
     update(args: UpdateArgs<S>): void;
+    /**
+     * state 由来の締切。サーバーが `at` の時刻に自分で起きて `handler` を呼ぶ。
+     *
+     * 時刻をきっかけに何かを起こすなら `tickRate` で毎秒ポーリングせずこちらを使う。
+     * ポーリング中は Durable Object が hibernate できない。
+     */
+    deadlines?: Record<string, Deadline<S>>;
     tickRate?: number;
 }
 export interface GameConfig<S> extends ConnectionCallbacks {

package/dist/types.js

@@ -1,10 +1,3 @@
-/**
- * 予約から発火した action に渡る playerId。
- *
- * 送信者がいないので、人間の操作と区別するための定数。
- * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
- */
-export const SCHEDULED_ACTOR = '__scheduled';
 /** Sentinel value — patch の value にセットすると、サーバーが Date.now() に置換する */
 export const SERVER_TIME = '__SERVER_TIME__';
 /** デフォルトのプレイヤーアイコン URL 一覧（dev / local モード用） */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzuhq/code-sdk",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "UZU PlayScreen SDK - Flutter ↔ JS ゲーム通信ライブラリ",
   "type": "module",
   "exports": {