@uzuhq/code-sdk 0.4.0 → 0.6.0

package/dist/types.d.ts

@@ -56,6 +56,40 @@ export interface PlayersChangedMessage {
     players: Record<string, PlayerVoiceState>;
 }
 export type Emit = (eventName: string, data?: Record<string, unknown>) => void;
+/**
+ * events handler。
+ *
+ * `emit(name, data)` の `data` をそのまま受け取る。先読み中か確定後かは渡さない
+ * (どちらで呼ばれても同じ処理をする前提。 `predict` で宣言済みなので分岐の必要がない)。
+ */
+export type EventHandler = (data: Record<string, unknown>) => void;
+/**
+ * events の購読宣言。
+ *
+ * `predict` は必須。 このイベントを「クライアント先読みの時点で実行してよいか」を
+ * シナリオ側が明示する。
+ *
+ * | `predict` | 実行タイミング | 向いているもの |
+ * |---|---|---|
+ * | `true` | 先読み時に即実行。確定は待たない | 短く上書きできる SE、画面フラッシュ |
+ * | `false` | サーバー確定後に 1 回だけ | 長い演出、ハプティクス、計測、外部通知 |
+ *
+ * IMPORTANT: 先読みは外れることがあり、実行してしまったものは取り消せない。
+ * 「起きなかった出来事」で実行されて困るもの (analytics / 実績解除 / 長いカットイン)
+ * は必ず `predict: false` にすること。誤送信は静かに、そして永久に残る。
+ *
+ * ```ts
+ * events: {
+ *   'dialogue.line': { predict: true, handler: (d) => playSound('page') },
+ *   'game.finished': { predict: false, handler: () => playFanfare() },
+ * }
+ * ```
+ */
+export interface EventSubscription {
+    /** 先読み時点で実行してよいか。宣言必須。 */
+    predict: boolean;
+    handler: EventHandler;
+}
 /** dev harness で観測される 1 件の emit。`data` は `emit(name)` 省略時に空 object になる。 */
 export interface ServerEvent {
     name: string;
@@ -71,19 +105,109 @@ export interface SeededRandom {
  * 素の action handler の実行文脈。空なのは意図的。
  *
  * 素の handler はサーバーとクライアント先読みの両方で走る。クライアントが自力で
- * 再現できない値 (tick / 実時刻 / 乱数) をここで配ると、サーバー・ソロ・dev では
- * 本物が入るのにオンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
- * そういう値が要る action は serverOnly() にして先読みの対象から外す。
+ * 再現できない値 (tick / 乱数) をここで配ると、サーバー・ソロ・dev では本物が入るのに
+ * オンラインの先読みだけ値がズレる、という一番気付きにくい形で壊れる。
+ * そういう値が要る処理は `serverActions` 側に書く。
  */
-export type ActionContext = Record<never, never>;
-/** serverOnly() handler の実行文脈。サーバーでしか走らないので tick を渡せる。 */
-export interface ServerOnlyActionContext {
+export interface ActionContext {
+    /**
+     * このアクションがサーバーで処理される時刻 (ms)。
+     *
+     * サーバーでは dispatch 時の実時刻。クライアント先読みでは、サーバーとのクロック
+     * オフセットから推定した値が入る。端末の時計がズレていても影響を受けない。
+     *
+     * IMPORTANT: 推定なのでサーバーの値とは数十 ms ずれる。時刻の **記録** に使うこと。
+     * `if (ctx.now > deadline)` のような **分岐** に使うと境界付近でクライアントと
+     * サーバーの判定が割れ、先読みが構造ごと外れる。時刻での分岐は `update()` で行う
+     * (サーバーでしか走らないので実時刻で正確)。
+     *
+     * 再適用 (reconciliation でのやり直し) では初回予測時の値を使い回す。取り直すと
+     * やり直すたびに値がズレて表示がガタつくため。
+     */
+    now: number;
+    /**
+     * サーバー権威のタイマー予約。
+     *
+     * IMPORTANT: クライアント先読みでは**何も予約しない** (予約はサーバーだけが持つ)。
+     * 戻り値の絶対時刻は先読みでも計算されるので、表示用の値は即座に出せる。
+     */
+    schedule(options: ScheduleOptions): number;
+    /** 予約を取り消す。クライアント先読みでは何もしない。 */
+    unschedule(key: string): void;
+}
+/** 予約されたタイマーの識別子付き宣言。 */
+export interface ScheduleOptions {
+    /**
+     * 予約の識別子。同じ key で予約し直すと**置き換わる**。
+     *
+     * key を必須にしているのは、古い予約を確実に消せるようにするため。
+     * 例: GM がタイマーを 20 分 -> 30 秒に変更したとき、同じ key で予約し直せば
+     * 古い 20 分の予約は消える。key が無いと両方が生き残り、19 分後に
+     * 「もう終わったフェーズ」を進める事故になる。
+     */
+    key: string;
+    /** 発火する絶対時刻 (ms)。`after` と排他。過去を指定すると即座に発火する。 */
+    at?: number;
+    /** 何秒後に発火するか。`at` と排他。 */
+    after?: number;
+    /** 発火時に実行する action 名。 */
+    action: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * サーバー権威のタイマー。
+ *
+ * クライアントの時計やアプリのバックグラウンド化に依存せず、サーバーが指定時刻に
+ * 自分で起きて action を撃つ。`tickRate` で毎秒ポーリングする必要が無くなり、
+ * その間 Durable Object は hibernate できる。
+ */
+export interface Scheduler {
+    /**
+     * 予約する。戻り値は確定した絶対時刻 (ms)。
+     *
+     * 表示用の `endsAt` と発火の予約が二重管理で drift しないよう、戻り値をそのまま
+     * state に入れられるようにしている。
+     *
+     * ```ts
+     * state.game.timerEndsAt = ctx.schedule({
+     *   key: 'phaseTimer', after: 1200, action: 'phase.timeout', payload: { phaseId },
+     * });
+     * ```
+     *
+     * IMPORTANT: 発火は at-least-once。同じ予約が 2 回実行されうるので、handler 側で
+     * 「もう進んでいたら何もしない」ガードを書くこと。
+     */
+    schedule(options: ScheduleOptions): number;
+    /** 予約を取り消す。存在しない key を渡しても何も起きない。 */
+    unschedule(key: string): void;
+}
+/**
+ * 予約から発火した action に渡る playerId。
+ *
+ * 送信者がいないので、人間の操作と区別するための定数。
+ * `if (playerId !== SCHEDULED_ACTOR) return;` で人間からの直接実行を弾ける。
+ */
+export declare const SCHEDULED_ACTOR = "__scheduled";
+/** `serverActions` handler の実行文脈。サーバーでしか走らないので tick と乱数を渡せる。 */
+export interface ServerActionContext {
     tick: number;
+    random: SeededRandom;
+    /** サーバーの実時刻 (ms)。同じ dispatch の `actions` に渡る `ctx.now` と同一値。 */
+    now: number;
+    schedule(options: ScheduleOptions): number;
+    unschedule(key: string): void;
 }
+/** @deprecated `ServerActionContext` を使う。 */
+export type ServerOnlyActionContext = ServerActionContext;
 export type ActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ActionContext) => void;
-export type ServerOnlyActionHandlerFn<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerOnlyActionContext) => Promise<void> | void;
-/** serverOnly() で wrap された handler。`__serverOnly` brand で識別する。 */
-export type ServerOnlyAction<S> = ServerOnlyActionHandlerFn<S> & {
+export type ServerActionHandler<S> = (state: S, payload: any, playerId: string, emit: Emit, ctx: ServerActionContext) => Promise<void> | void;
+/** @deprecated `ServerActionHandler` を使う。 */
+export type ServerOnlyActionHandlerFn<S> = ServerActionHandler<S>;
+/**
+ * @deprecated `serverActions` フィールドに直接書く。
+ * `serverOnly()` で wrap された handler。`__serverOnly` brand で識別する。
+ */
+export type ServerOnlyAction<S> = ServerActionHandler<S> & {
     readonly __serverOnly: true;
 };
 export interface GameLogic<S> {
@@ -92,10 +216,29 @@ export interface GameLogic<S> {
      * ゲームの配役は kind === 'player' (または kind 省略) だけを対象にすること。
      */
     setup(seats: Seat[], random: SeededRandom): S;
-    actions: Record<string, ActionHandler<S> | ServerOnlyAction<S>>;
+    /**
+     * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
+     *
+     * `serverActions` に同名のキーを置くと、同じ action の「サーバーだけで走る続き」に
+     * なる。1 つの action を「即座に反映していい部分」と「サーバーが決める部分」へ
+     * 分けられる (例: 駒の移動は先読み、持ち時間の減算はサーバー)。
+     */
+    actions: Record<string, ActionHandler<S>>;
+    /**
+     * サーバーでのみ走る handler。実時刻 / 乱数 / fetch など、クライアント先読みで
+     * 再現できない処理をここに書く。async 可。
+     *
+     * `actions` と同名でも別名でもよい。別名だけに置けば「先読みしない action」
+     * (旧 `serverOnly()` 相当) になる。
+     */
+    serverActions?: Record<string, ServerActionHandler<S>>;
     update(state: S, ctx: {
         random: SeededRandom;
         tick: number;
+        /** サーバーの実時刻 (ms)。update はサーバーでしか走らないので常に正確。 */
+        now: number;
+        schedule(options: ScheduleOptions): number;
+        unschedule(key: string): void;
         emit: Emit;
         playerInputs: Record<string, Record<string, any>>;
     }): void;
@@ -105,7 +248,15 @@ export interface GameConfig<S> extends ConnectionCallbacks {
     logic: GameLogic<S>;
     onState: (state: S, myPlayerId: string) => void;
     inputs: (sendAction: (type: string, payload?: any) => void) => void;
-    events?: Record<string, (data: Record<string, unknown>) => void>;
+    /**
+     * `emit(name, data)` の購読。 キーごとに `predict` の宣言が必須。
+     *
+     * 同じ出来事が二重に実行されないよう、SDK は「先読みで実行した記録」を持ち、
+     * サーバーから同一の event (name と data が完全一致) が届いたら実行を抑止する。
+     * したがって `data` には**クライアントとサーバーで必ず同じ値になるもの**だけを
+     * 入れること。`ctx.now` や乱数 ID を混ぜると一致せず二重実行になる。
+     */
+    events?: Record<string, EventSubscription>;
     playerCount: number;
     /** Dev harness のデフォルト向き。manifest.json の `orientation` を渡す。 */
     orientation?: 'portrait' | 'landscape';

package/dist/types.js

@@ -1,3 +1,10 @@
+/**
+ * 予約から発火した 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.4.0",
+  "version": "0.6.0",
   "description": "UZU PlayScreen SDK - Flutter ↔ JS ゲーム通信ライブラリ",
   "type": "module",
   "exports": {