@uzuhq/code-sdk 0.7.0 → 0.7.1

package/README.md

@@ -219,61 +219,73 @@ run({
 ### GameLogic
 
 ```ts
-import { serverOnly, type GameLogic } from '@uzuhq/code-sdk';
+import type { GameLogic } from '@uzuhq/code-sdk';
 
 const logic: GameLogic<MyState> = {
-  setup(seats, random) {
-    // 初期 state を生成。random は SeededRandom。
+  setup({ seats, ctx }) {
+    // 初期 state を生成。ctx.random は SeededRandom、ctx.now はサーバーの実時刻。
     // seats には観戦系の席 (kind: 'spectator' | 'admin') も含まれ得るため、
     // ゲームの席は kind === 'player' に絞る
     return { players: {}, items: [] };
   },
 
+  // クライアント先読みとサーバーの 2 回走る。決定的でなければならない。
   actions: {
-    move(state, payload, playerId, emit, ctx) {
+    move({ state, payload, playerId, ctx }) {
       // state を直接変更する（Immer 的な mutable 操作）
       state.players[playerId].x += payload.dx;
-      // emit でイベント発火
-      emit('sound', { sound: 'step' });
-      // ctx.tick でサーバーの現在 tick を参照可能
+      // ctx.emit でイベント発火 (購読側は events で predict を宣言する)
+      ctx.emit('sound', { sound: 'step' });
+      // 時刻は ctx.now を使う。Date.now() は端末とサーバーでズレる
     },
+  },
 
-    // serverOnly(): client 先行実行をスキップしてサーバーだけで実行 (async OK)
-    notifyExternal: serverOnly(async (state, payload, playerId) => {
+  // サーバーでのみ走る。実時刻・乱数・fetch などクライアントが再現できない処理。
+  // actions と同名にすると「同じ action のサーバー側の続き」になる。
+  serverActions: {
+    async notifyExternal({ state, payload, playerId }) {
       await fetch('https://example.com/notify', {
         method: 'POST',
         body: JSON.stringify({ playerId, ...payload }),
       });
       state.notifiedAt = Date.now();
-    }),
+    },
   },
 
-  update(state, ctx) {
-    // 毎 tick 実行。ctx.tick, ctx.random, ctx.emit, ctx.playerInputs が使える
+  update({ state, ctx }) {
+    // 毎 tick 実行。ctx.tick / ctx.random / ctx.now / ctx.emit / ctx.playerInputs が使える
   },
 
-  tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし, 0 でターン制)
+  tickRate: 10, // 秒間 tick 数 (default: 0 = tick なし)
 };
 ```
 
-| キー       | 型                                                                                                                                 | 必須 | 説明                                                                        |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------- |
-| `setup`    | `(seats: Seat[], random: SeededRandom) => S`                                                                                       | Yes  | 初期 state を生成。seats には `kind !== 'player'` の席も含まれる            |
-| `actions`  | `Record<string, ActionHandler<S> \| ServerOnlyAction<S>>`                                                                          | Yes  | アクションハンドラ。`serverOnly()` で wrap すると client 先行実行をスキップ |
-| `update`   | `(state: S, ctx: { random: SeededRandom, tick: number, emit: EmitFn, playerInputs: Record<string, Record<string, any>> }) => void` | Yes  | 毎 tick 実行                                                                |
-| `tickRate` | `number`                                                                                                                           | No   | 秒間 tick 数 (default: 0 = tick なし)                                       |
+| キー            | 型                                       | 必須 | 説明                                                             |
+| --------------- | ---------------------------------------- | ---- | ---------------------------------------------------------------- |
+| `setup`         | `(args: SetupArgs) => S`                 | Yes  | 初期 state を生成。seats には `kind !== 'player'` の席も含まれる |
+| `actions`       | `Record<string, ActionHandler<S>>`       | Yes  | クライアント先読み + サーバーの 2 回走る。決定的であること       |
+| `serverActions` | `Record<string, ServerActionHandler<S>>` | No   | サーバーでのみ走る。async 可。`ctx` に `tick` / `random` が入る  |
+| `update`        | `(args: UpdateArgs<S>) => void`          | Yes  | 毎 tick 実行 (`tickRate` が 0 なら呼ばれない)                    |
+| `tickRate`      | `number`                                 | No   | 秒間 tick 数 (default: 0 = tick なし)                            |
+
+ハンドラの引数は 1 つのオブジェクトで、使うものだけ書けばよい。
+`state` / `payload` / `playerId` はその呼び出しの事実、`ctx` は実行環境が与えるもの。
+
+時刻起点で何かを起こしたい場合は `tickRate` で毎秒ポーリングせず `ctx.schedule()` を使う。
+サーバーが指定時刻に自分で起きて action を撃つので、その間 Durable Object が hibernate できる。
 
 #### `serverOnly(handler)`
 
-`actions` に登録する handler を「サーバーでだけ実行される」ものに変換する wrapper。
+> **Deprecated**: `serverActions` に直接書く。
 
-- クライアント側ではローカル先行実行 (楽観的更新) をスキップし、サーバーからの state delta を待つ
-- サーバー側で `await` で実行され、`fetch` などの副作用付き処理を安全に書ける
-- handler のシグネチャ: `(state, payload, playerId, emit, ctx) => Promise<void> | void`
-- 例外を投げると送信元クライアントに `__action_error` が返る (state は変更されない)
+`actions` に登録する handler を「サーバーでだけ実行される」ものに変換する旧 wrapper。
+`serverActions` フィールドが同じことを型で表現できるので、新しいコードでは使わない。
 
 ```ts
-import { serverOnly } from '@uzuhq/code-sdk';
+// before
+actions: { notifyExternal: serverOnly(async (state) => { ... }) }
+// after
+serverActions: { notifyExternal: async ({ state }) => { ... } }
 ```
 
 ### manifest.json（run() を使う場合）

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  * 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, UpdateArgs, UpdateContext, EventHandler, EventSubscription, ScheduleOptions, Scheduler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } 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, ScheduleOptions, Scheduler, ServerActionContext, ServerActionHandler, ServerOnlyAction, ServerOnlyActionContext, ServerOnlyActionHandlerFn, } from './types.js';
 export { SERVER_TIME, DEFAULT_ICON_URLS, SCHEDULED_ACTOR } from './types.js';
 export { serverOnly, isServerOnlyAction } from './server-only.js';
 export { serverNow } from './server-clock.js';

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

@@ -50,7 +50,7 @@ export function runLocalServerAction(config) {
         }
     };
     // setRawState で全置換できるよう let。closures は名前参照なので最新束縛を読む。
-    let state = logic.setup(players, random);
+    let state = logic.setup({ seats: players, ctx: { random, now: Date.now() } });
     let tick = 0;
     const playerInputs = {};
     // Action 処理。`actions` は同期実行で `sendAction()` 直後の同期 onState を保証する

package/dist/types.d.ts

@@ -200,12 +200,28 @@ export interface UpdateArgs<S> {
     state: S;
     ctx: UpdateContext;
 }
-export interface GameLogic<S> {
+/**
+ * `setup()` の実行文脈。サーバーでしか走らないので実時刻をそのまま渡せる。
+ *
+ * `emit` は無い。まだ誰も購読していない時点なので、鳴らしても届かない。
+ * `schedule` も無い。開幕から予約したい要求が出たら足す。
+ */
+export interface SetupContext {
+    random: SeededRandom;
+    /** サーバーの実時刻 (ms)。setup はサーバーでしか走らないので常に正確。 */
+    now: number;
+}
+/** `setup()` の引数。 */
+export interface SetupArgs {
     /**
      * seats には kind !== 'player' の席 (spectator / admin) も含まれる。
      * ゲームの配役は kind === 'player' (または kind 省略) だけを対象にすること。
      */
-    setup(seats: Seat[], random: SeededRandom): S;
+    seats: Seat[];
+    ctx: SetupContext;
+}
+export interface GameLogic<S> {
+    setup(args: SetupArgs): S;
     /**
      * クライアント先読みとサーバーの両方で走る handler。決定的でなければならない。
      *

package/package.json

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