@uzuhq/code-sdk 0.8.0 → 0.8.2

package/README.md

@@ -304,12 +304,13 @@ handler 側で弾く必要も無い。
 **時刻は 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 つの時刻の差を取る                           |
+| API                        | 意味                                                              |
+| -------------------------- | ----------------------------------------------------------------- |
+| `ctx.time`                 | そのハンドラが走っているゲーム内時刻。`setup` では必ず `0`        |
+| `ctx.after(d)`             | 今から `d` ms 後のゲーム内時刻。締切を state に置くときに使う     |
+| `gameTime()`               | 描画側で読む現在のゲーム内時刻 (推定値)。`performance.now()` 基準 |
+| `plus(t, d)` / `sub(t, d)` | 時刻に長さを足す / 引く                                           |
+| `minus(a, b)`              | 2 つの時刻の差 (ms)                                               |
 
 ```ts
 import { gameTime, minus } from '@uzuhq/code-sdk';
@@ -323,8 +324,9 @@ actions: {
 const remain = Math.ceil(minus(state.phaseEndsAt, gameTime()) / 1000);
 ```
 
-`GameTime` は `number` の brand 型なので、実行時はただの数値。state は素の JSON のまま。
-`Date.now()` を `GameTime` の場所に入れると TypeScript が弾く。
+`GameTime` は brand 型なので実行時はただの数値で、state は素の JSON のまま。ただし型の上では
+`number` と混ざらないので、`Date.now()` を書き込む式も `endsAt - Date.now()` と読む式も
+コンパイルが通らない。
 
 ### 緊急一時停止
 

package/dist/dev-globals.d.ts

@@ -1,4 +1,4 @@
-import { i as UzuDevHooks } from "./dev-hooks-D6CbhPDP.js";
+import { i as UzuDevHooks } from "./dev-hooks-DOtJHP55.js";
 //#region src/dev-globals.d.ts
 declare global {
   interface Window {

package/dist/{dev-hooks-D6CbhPDP.d.ts → dev-hooks-DOtJHP55.d.ts}

@@ -94,21 +94,47 @@ declare function applyJsonPatch(target: Record<string, unknown>, ops: JsonPatchO
  * 違うぶんは残る (`Date.now()` を混ぜれば締切が 56,000 日後になって初回で気付く)。
  */
 declare const gameTimeBrand: unique symbol;
-/** ゲーム内時刻 (ゲーム開始からの ms)。停止中は進まない。 */
-type GameTime = number & {
+/** brand の印。`GameTime` を組み立てるためだけに使う。 */
+type GameTimeTag = {
   readonly [gameTimeBrand]: 'GameTime';
 };
+/**
+ * ゲーム内時刻 (ゲーム開始からの ms)。停止中は進まない。
+ *
+ * `number & Tag` ではなく `(number & Tag) | Tag` にしてあるのは、**読み側を守るため**。
+ * 交差だけだと `GameTime` が `number` へ代入できてしまい、
+ * `state.endsAt - Date.now()` が型検査を通る。これは `GameTime` を導入した動機
+ * そのもののバグで、しかも実行時に静かに壊れる (巨大な負数が
+ * `Math.max(0, ...)` に潰されてタイマーが 00:00 で固まる)。
+ *
+ * union にすると `number` への代入と算術が型で止まり、`GameTime` 同士の比較・`===`・
+ * テンプレート・`Number.isFinite`・JSON 往復・一段 cast はそのまま使える。
+ * TypeScript コンパイラ自身が `__String` (識別子の内部表現) で同じ形を採っている
+ * (microsoft/TypeScript#16915)。
+ */
+type GameTime = (number & GameTimeTag) | GameTimeTag;
 /** 長さ (ms)。差や間隔はこちら。 */
 type Duration = number;
 /**
  * `GameTime` に長さを足す。
  *
- * 算術をすると brand が落ちる (`number + number = number`) ので、`GameTime` を
- * 作り直す道はこの関数と `ctx.after` に限られる。
+ * 算術は型で止まるので、`GameTime` を作り直す道はこの関数と `ctx.after` に限られる。
  */
 declare const plus: (t: GameTime, d: Duration) => GameTime;
+/** `GameTime` から長さを引く。`plus(t, -d)` と書かせないための対。 */
+declare const sub: (t: GameTime, d: Duration) => GameTime;
 /** 2 つの `GameTime` の差 (ms)。 */
 declare const minus: (a: GameTime, b: GameTime) => Duration;
+/**
+ * ゲーム内時計の原点。ゲーム開始の瞬間で、`setup()` の `ctx.time` と同じ値。
+ *
+ * `minus(t, GAME_START)` がゲーム開始からの経過 ms になる。表示やログのために
+ * 素の数値が要る場面は、これを使えば cast を書かずに済む。
+ *
+ * `toMs` を公開しないのは `toMs(a) - toMs(b)` と書けて保護が丸ごと消えるためだが、
+ * `GAME_START` にその使い方は無い。差を取るには結局 `minus` を通る。
+ */
+declare const GAME_START: GameTime;
 //#endregion
 //#region ../engine-core/src/types.d.ts
 /**
@@ -712,4 +738,4 @@ interface DevHooksCtx<S = unknown> {
 declare function createDevHooks<S>(ctx: DevHooksCtx<S>): UzuDevHooks<S>;
 declare function attachDevHooks<S>(ctx: DevHooksCtx<S>): void;
 //#endregion
-export { minus as $, DEFAULT_ICON_URLS as A, ServerActionContext as B, SetFn as C, ActionContext as D, ActionArgs as E, GameLogic as F, ServerOnlyActionContext as G, ServerActionMap as H, SERVER_TIME as I, SetupContext as J, ServerOnlyActionHandlerFn as K, Seat as L, DeadlineArgs as M, DeadlineContext as N, ActionHandler as O, Emit as P, GameTime as Q, SeededRandom as R, SendAction as S, Operation as T, ServerEvent as U, ServerActionHandler as V, ServerOnlyAction as W, UpdateContext as X, UpdateArgs as Y, Duration as Z, PayloadMap as _, attachDevHooks as a, PlayersChangedMessage as b, getPredictionWarnings as c, ConnectionCallbacks as d, plus as et, ConnectionState as f, PatchFn as g, GameConfig as h, UzuDevHooks as i, applyJsonPatch as it, Deadline as j, ActionMap as k, BridgeChannel as l, EventSubscription as m, RunHandle as n, JsonPatchOp as nt, createDevHooks as o, EventHandler as p, SetupArgs as q, SyncHandle as r, applyJsonMergePatch as rt, PredictionWarning as s, DevHooksCtx as t, JsonMergePatch as tt, BridgeMessage as u, PlayScreenMessage as v, SyncConfig as w, SeatKind as x, PlayerVoiceState as y, ServerActionArgs as z };
+export { GameTime as $, DEFAULT_ICON_URLS as A, ServerActionContext as B, SetFn as C, ActionContext as D, ActionArgs as E, GameLogic as F, ServerOnlyActionContext as G, ServerActionMap as H, SERVER_TIME as I, SetupContext as J, ServerOnlyActionHandlerFn as K, Seat as L, DeadlineArgs as M, DeadlineContext as N, ActionHandler as O, Emit as P, GAME_START as Q, SeededRandom as R, SendAction as S, Operation as T, ServerEvent as U, ServerActionHandler as V, ServerOnlyAction as W, UpdateContext as X, UpdateArgs as Y, Duration as Z, PayloadMap as _, attachDevHooks as a, applyJsonMergePatch as at, PlayersChangedMessage as b, getPredictionWarnings as c, ConnectionCallbacks as d, minus as et, ConnectionState as f, PatchFn as g, GameConfig as h, UzuDevHooks as i, JsonPatchOp as it, Deadline as j, ActionMap as k, BridgeChannel as l, EventSubscription as m, RunHandle as n, sub as nt, createDevHooks as o, applyJsonPatch as ot, EventHandler as p, SetupArgs as q, SyncHandle as r, JsonMergePatch as rt, PredictionWarning as s, DevHooksCtx as t, plus as tt, BridgeMessage as u, PlayScreenMessage as v, SyncConfig as w, SeatKind as x, PlayerVoiceState as y, ServerActionArgs as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as minus, A as DEFAULT_ICON_URLS, B as ServerActionContext, C as SetFn, D as ActionContext, E as ActionArgs, F as GameLogic, G as ServerOnlyActionContext, H as ServerActionMap, I as SERVER_TIME, J as SetupContext, K as ServerOnlyActionHandlerFn, L as Seat, M as DeadlineArgs, N as DeadlineContext, O as ActionHandler, P as Emit, Q as GameTime, R as SeededRandom, S as SendAction, T as Operation, U as ServerEvent, V as ServerActionHandler, W as ServerOnlyAction, X as UpdateContext, Y as UpdateArgs, Z as Duration, _ as PayloadMap, a as attachDevHooks, b as PlayersChangedMessage, c as getPredictionWarnings, d as ConnectionCallbacks, et as plus, f as ConnectionState, g as PatchFn, h as GameConfig, i as UzuDevHooks, it as applyJsonPatch, j as Deadline, k as ActionMap, l as BridgeChannel, m as EventSubscription, n as RunHandle, nt as JsonPatchOp, o as createDevHooks, p as EventHandler, q as SetupArgs, r as SyncHandle, rt as applyJsonMergePatch, s as PredictionWarning, t as DevHooksCtx, tt as JsonMergePatch, u as BridgeMessage, v as PlayScreenMessage, w as SyncConfig, x as SeatKind, y as PlayerVoiceState, z as ServerActionArgs } from "./dev-hooks-D6CbhPDP.js";
+import { $ as GameTime, A as DEFAULT_ICON_URLS, B as ServerActionContext, C as SetFn, D as ActionContext, E as ActionArgs, F as GameLogic, G as ServerOnlyActionContext, H as ServerActionMap, I as SERVER_TIME, J as SetupContext, K as ServerOnlyActionHandlerFn, L as Seat, M as DeadlineArgs, N as DeadlineContext, O as ActionHandler, P as Emit, Q as GAME_START, R as SeededRandom, S as SendAction, T as Operation, U as ServerEvent, V as ServerActionHandler, W as ServerOnlyAction, X as UpdateContext, Y as UpdateArgs, Z as Duration, _ as PayloadMap, a as attachDevHooks, at as applyJsonMergePatch, b as PlayersChangedMessage, c as getPredictionWarnings, d as ConnectionCallbacks, et as minus, f as ConnectionState, g as PatchFn, h as GameConfig, i as UzuDevHooks, it as JsonPatchOp, j as Deadline, k as ActionMap, l as BridgeChannel, m as EventSubscription, n as RunHandle, nt as sub, o as createDevHooks, ot as applyJsonPatch, p as EventHandler, q as SetupArgs, r as SyncHandle, rt as JsonMergePatch, s as PredictionWarning, t as DevHooksCtx, tt as plus, u as BridgeMessage, v as PlayScreenMessage, w as SyncConfig, x as SeatKind, y as PlayerVoiceState, z as ServerActionArgs } from "./dev-hooks-DOtJHP55.js";
 //#region ../engine-core/src/random.d.ts
 declare class SeededRandomImpl implements SeededRandom {
   private _state;
@@ -205,4 +205,4 @@ declare function onPlayersChanged(handler: PlayersChangedHandler): void;
 declare function run<S, A extends ActionMap<S> = ActionMap<S>, SA extends ServerActionMap<S> = Record<never, never>>(config: GameConfig<S, A, SA>): void;
 declare function sync<S>(config: SyncConfig<S>): void;
 //#endregion
-export { type ActionArgs, type ActionContext, type ActionHandler, type ActionMap, type BridgeChannel, type BridgeMessage, type ConnectionCallbacks, type ConnectionState, DEFAULT_ICON_URLS, type Deadline, type DeadlineArgs, type DeadlineContext, type DevHooksCtx, type Duration, type Emit, type EventHandler, type EventSubscription, type GameConfig, type GameLogic, type GameTime, type JsonMergePatch, type JsonPatchOp, type Operation, type PatchFn, type PayloadMap, type PlayScreenMessage, type PlayerVoiceState, type PlayersChangedMessage, type PredictionWarning, type ReconnectableWSOptions, ReconnectableWebSocket, Room, type RoomLike, type RunHandle, SERVER_TIME, type Seat, type SeatKind, type SeededRandom, SeededRandomImpl, type SendAction, type ServerActionArgs, type ServerActionContext, type ServerActionHandler, type ServerActionMap, type ServerEvent, type ServerOnlyAction, type ServerOnlyActionContext, type ServerOnlyActionHandlerFn, type SetFn, type SetupArgs, type SetupContext, type SyncConfig, type SyncHandle, type UpdateArgs, type UpdateContext, type UzuDevHooks, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getPredictionWarnings, getRoom, init, isHosted, isPaused, isServerOnlyAction, minus, on, onPauseChange, onPlayersChanged, onRoom, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sync };
+export { type ActionArgs, type ActionContext, type ActionHandler, type ActionMap, type BridgeChannel, type BridgeMessage, type ConnectionCallbacks, type ConnectionState, DEFAULT_ICON_URLS, type Deadline, type DeadlineArgs, type DeadlineContext, type DevHooksCtx, type Duration, type Emit, type EventHandler, type EventSubscription, GAME_START, type GameConfig, type GameLogic, type GameTime, type JsonMergePatch, type JsonPatchOp, type Operation, type PatchFn, type PayloadMap, type PlayScreenMessage, type PlayerVoiceState, type PlayersChangedMessage, type PredictionWarning, type ReconnectableWSOptions, ReconnectableWebSocket, Room, type RoomLike, type RunHandle, SERVER_TIME, type Seat, type SeatKind, type SeededRandom, SeededRandomImpl, type SendAction, type ServerActionArgs, type ServerActionContext, type ServerActionHandler, type ServerActionMap, type ServerEvent, type ServerOnlyAction, type ServerOnlyActionContext, type ServerOnlyActionHandlerFn, type SetFn, type SetupArgs, type SetupContext, type SyncConfig, type SyncHandle, type UpdateArgs, type UpdateContext, type UzuDevHooks, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getPredictionWarnings, getRoom, init, isHosted, isPaused, isServerOnlyAction, minus, on, onPauseChange, onPlayersChanged, onRoom, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub, sync };

package/dist/index.js

@@ -10,20 +10,39 @@ const DEFAULT_ICON_URLS = [
 //#endregion
 //#region ../engine-core/src/game-time.ts
 /**
+* エンジン内部で素の ms へ落とす。**パッケージの公開 API には出さない** (`index.ts` を見よ)。
+*
+* 公開すると `toMs(a) - toMs(b)` と書けてしまい brand の保護が丸ごと消える。
+* 差を取る正当な用途は `minus` が既に埋めているので、外へ出す理由が無い。
+* 外部 API へ素の数値を渡したいという実需が出たら、そのとき足す。
+*/
+const toMs = (t) => t;
+/**
 * `GameTime` に長さを足す。
 *
-* 算術をすると brand が落ちる (`number + number = number`) ので、`GameTime` を
-* 作り直す道はこの関数と `ctx.after` に限られる。
+* 算術は型で止まるので、`GameTime` を作り直す道はこの関数と `ctx.after` に限られる。
 */
-const plus = (t, d) => t + d;
+const plus = (t, d) => toMs(t) + d;
+/** `GameTime` から長さを引く。`plus(t, -d)` と書かせないための対。 */
+const sub = (t, d) => toMs(t) - d;
 /** 2 つの `GameTime` の差 (ms)。 */
-const minus = (a, b) => a - b;
+const minus = (a, b) => toMs(a) - toMs(b);
 /**
 * エンジン内部専用。作家コードから呼ばない。
 *
 * 時計の実装 (play-server の facet / dev-server / ソロ / SDK の補間) だけがここを通る。
 */
 const asGameTime = (ms) => ms;
+/**
+* ゲーム内時計の原点。ゲーム開始の瞬間で、`setup()` の `ctx.time` と同じ値。
+*
+* `minus(t, GAME_START)` がゲーム開始からの経過 ms になる。表示やログのために
+* 素の数値が要る場面は、これを使えば cast を書かずに済む。
+*
+* `toMs` を公開しないのは `toMs(a) - toMs(b)` と書けて保護が丸ごと消えるためだが、
+* `GAME_START` にその使い方は無い。差を取るには結局 `minus` を通る。
+*/
+const GAME_START = asGameTime(0);
 //#endregion
 //#region ../engine-core/src/game-clock.ts
 /**
@@ -74,7 +93,7 @@ var GameClock = class {
 	}
 	/** ゲーム内時刻を、alarm / setTimeout が使う実時刻へ直す。 */
 	toWall(at) {
-		return at + this.startedAtWall + this.pausedTotalMs;
+		return toMs(at) + this.startedAtWall + this.pausedTotalMs;
 	}
 	/** 実際に理由を足したら true。呼び出し側が永続化や tick 停止の要否に使う。 */
 	freeze(reason) {
@@ -139,8 +158,9 @@ var GameClock = class {
 function withGameClock(time, fn) {
 	const realNow = Date.now;
 	const RealDate = Date;
-	Date.now = () => time;
-	globalThis.Date = new Proxy(RealDate, { construct: (target, args) => Reflect.construct(target, args.length === 0 ? [time] : args) });
+	const ms = toMs(time);
+	Date.now = () => ms;
+	globalThis.Date = new Proxy(RealDate, { construct: (target, args) => Reflect.construct(target, args.length === 0 ? [ms] : args) });
 	try {
 		return fn();
 	} finally {
@@ -303,7 +323,7 @@ function observeGameTime(t) {
 * state の到着とは無関係にいつでも呼べる。
 */
 function gameTime() {
-	return asGameTime(frozenAt ?? performance.now() + offset);
+	return frozenAt ?? asGameTime(performance.now() + offset);
 }
 /**
 * 時計を凍らせる。
@@ -2227,4 +2247,4 @@ function calcHudInsets(params) {
 	};
 }
 //#endregion
-export { DEFAULT_ICON_URLS, ReconnectableWebSocket, Room, SERVER_TIME, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getPredictionWarnings, getRoom, init, isHosted, isPaused, isServerOnlyAction, minus, on, onPauseChange, onPlayersChanged, onRoom, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sync };
+export { DEFAULT_ICON_URLS, GAME_START, ReconnectableWebSocket, Room, SERVER_TIME, SeededRandomImpl, applyJsonMergePatch, applyJsonPatch, attachDevHooks, changeRoom, createDevHooks, firstFrameReady, gameReady, gameTime, getPredictionWarnings, getRoom, init, isHosted, isPaused, isServerOnlyAction, minus, on, onPauseChange, onPlayersChanged, onRoom, playBgm, playSound, plus, run, send, serverOnly, setMicEnabled, stopBgm, sub, sync };

package/package.json

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