@lizardon386/core-abi 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 3178-battle-platform contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @lizardon386/core-abi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+3178 对战平台的游戏 ABI：`GameModule`、`GameInstance`、`Effect`、`GameContext`、房间/座位视图和版本常量。
+
+游戏工程通常通过 `@lizardon386/game-sdk` 使用这些类型，不需要直接安装本包。需要单独引用 ABI 时可以直接依赖。
+
+接入文档：[INTEGRATION_GUIDE.md](https://github.com/Lizardon386/3178-battle-platform/blob/master/INTEGRATION_GUIDE.md)
+
+License: MIT

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+export interface GameClientContract {
+    /** 把对局状态渲染进容器；返回的视图要能在下一次 mount 时替换。 */
+    mount(host: HTMLElement, view: unknown, actions: GameActions): void;
+    unmount?(host: HTMLElement): void;
+    onEvent?(event: {
+        name: string;
+        payload?: unknown;
+    }, actions: GameActions): void;
+}
+export interface GameActions {
+    send(name: string, payload?: unknown): void;
+    seatId(): string | null;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACpE,OAAO,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,OAAO,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAClF;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,MAAM,IAAI,MAAM,GAAG,IAAI,CAAC;CACzB"}

package/dist/client.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":""}

package/dist/codes.d.ts

@@ -0,0 +1,6 @@
+/** 平台错误码和通知码：游戏会用到，放进 ABI；默认文案留在 protocol。 */
+export declare const PLATFORM_CODES: readonly ["PROTOCOL", "VERSION", "RULES", "UNKNOWN_GAME", "NOROOM", "NOSEAT", "FULL", "NOTHOST", "HOSTONLY", "PASSWORD", "PHASE", "RATE", "SEATLOST", "BADMSG", "INTERNAL"];
+export type PlatformCode = (typeof PLATFORM_CODES)[number];
+export declare const NOTICE_CODES: readonly ["HOSTLEFT", "HOST_CHANGED", "ROOM_CLOSED", "SEAT_EJECTED", "RULES_MISMATCH", "REJOINED", "TOO_FEW"];
+export type NoticeCode = (typeof NOTICE_CODES)[number];
+//# sourceMappingURL=codes.d.ts.map

package/dist/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,eAAO,MAAM,cAAc,6KAgBjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,eAAO,MAAM,YAAY,+GAQf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/codes.js

@@ -0,0 +1,28 @@
+/** 平台错误码和通知码：游戏会用到，放进 ABI；默认文案留在 protocol。 */
+export const PLATFORM_CODES = [
+    'PROTOCOL',
+    'VERSION',
+    'RULES',
+    'UNKNOWN_GAME',
+    'NOROOM',
+    'NOSEAT',
+    'FULL',
+    'NOTHOST',
+    'HOSTONLY',
+    'PASSWORD',
+    'PHASE',
+    'RATE',
+    'SEATLOST',
+    'BADMSG',
+    'INTERNAL',
+];
+export const NOTICE_CODES = [
+    'HOSTLEFT',
+    'HOST_CHANGED',
+    'ROOM_CLOSED',
+    'SEAT_EJECTED',
+    'RULES_MISMATCH',
+    'REJOINED',
+    'TOO_FEW',
+];
+//# sourceMappingURL=codes.js.map

package/dist/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU;IACV,SAAS;IACT,OAAO;IACP,cAAc;IACd,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,SAAS;IACT,UAAU;IACV,UAAU;IACV,OAAO;IACP,MAAM;IACN,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAC;AAIX,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,UAAU;IACV,cAAc;IACd,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,UAAU;IACV,SAAS;CACD,CAAC"}

package/dist/hash.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 稳定摘要：把任意 JSON 值规范化后算出可跨端复现的短哈希。
+ * 只回答"两端配置是否一致"，不做安全用途；包完整性另走 sha256。
+ */
+/** 键排序、数组保序、undefined 归 null 的确定性 JSON。 */
+export declare function canonicalJson(value: unknown): string;
+/** 16 位十六进制稳定摘要。同一输入在 Node 与浏览器下结果必须一致。 */
+export declare function stableDigest(value: unknown): string;
+export declare function digestsMatch(a: string | undefined, b: string | undefined): boolean;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0DH,2CAA2C;AAC3C,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD;AAYD,2CAA2C;AAC3C,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGlF"}

package/dist/hash.js

@@ -0,0 +1,86 @@
+/**
+ * 稳定摘要：把任意 JSON 值规范化后算出可跨端复现的短哈希。
+ * 只回答"两端配置是否一致"，不做安全用途；包完整性另走 sha256。
+ */
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = (1n << 64n) - 1n;
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function encode(value, seen, out) {
+    if (value === null) {
+        out.push('null');
+        return;
+    }
+    if (typeof value === 'boolean' || typeof value === 'string' || typeof value === 'number') {
+        out.push(JSON.stringify(value) ?? 'null');
+        return;
+    }
+    if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+        out.push('null');
+        return;
+    }
+    if (typeof value === 'bigint') {
+        out.push(`${value.toString(16)}n`);
+        return;
+    }
+    if (!isPlainObject(value) && !Array.isArray(value)) {
+        out.push(`"${String(value)}"`);
+        return;
+    }
+    if (seen.has(value))
+        throw new TypeError('规范化失败：存在循环引用');
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            out.push('[');
+            value.forEach((item, i) => {
+                if (i)
+                    out.push(',');
+                encode(item, seen, out);
+            });
+            out.push(']');
+            return;
+        }
+        const obj = value;
+        const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+        out.push('{');
+        keys.forEach((k, i) => {
+            if (i)
+                out.push(',');
+            out.push(JSON.stringify(k), ':');
+            encode(obj[k], seen, out);
+        });
+        out.push('}');
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** 键排序、数组保序、undefined 归 null 的确定性 JSON。 */
+export function canonicalJson(value) {
+    const out = [];
+    encode(value, new Set(), out);
+    return out.join('');
+}
+function fnv1a64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let hash = FNV_OFFSET;
+    for (const b of bytes) {
+        hash ^= BigInt(b);
+        hash = (hash * FNV_PRIME) & MASK_64;
+    }
+    return hash;
+}
+/** 16 位十六进制稳定摘要。同一输入在 Node 与浏览器下结果必须一致。 */
+export function stableDigest(value) {
+    return fnv1a64(canonicalJson(value)).toString(16).padStart(16, '0');
+}
+export function digestsMatch(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string')
+        return false;
+    return a.toLowerCase() === b.toLowerCase();
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './module-api.js';
+export * from './client.js';
+export * from './seats.js';
+export * from './manifest.js';
+export * from './codes.js';
+export * from './hash.js';
+export * from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './module-api.js';
+export * from './client.js';
+export * from './seats.js';
+export * from './manifest.js';
+export * from './codes.js';
+export * from './hash.js';
+export * from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,35 @@
+import type { SeatRole } from './seats.js';
+export interface GameUiOptions {
+    /** 游戏内聊天由平台聊天卡提供，还是由游戏自己的界面提供。 */
+    chat?: 'platform' | 'game';
+}
+/** 游戏模块对外声明的自己：房主建房、客户端校验、模块下发三处都要用它。 */
+export interface GameManifest {
+    id: string;
+    name: string;
+    /** 语义化版本，只用于展示与"版本不同"的提示文案。 */
+    version: string;
+    /** 房规摘要：由 create 时的 config 算出，与 config 一起构成入房闸。 */
+    rulesHash: string;
+    seats: {
+        min: number;
+        max: number;
+    };
+    allowSpectate: boolean;
+    /** 游戏是否支持 AI 填充席位（war3 的"电脑玩家"）。 */
+    soloFill: boolean;
+    /** 需要的席位角色集合，平台据此拒绝模块乱用角色。 */
+    roles: SeatRole[];
+    /** 客户端 UI 入口，相对该模块的 base URL。 */
+    entry: string;
+    /** 下发给客户端的资源清单；hash 为 'sha256:<hex>' 或裸 hex。 */
+    assets?: GameAsset[];
+    /** 可选 UI 能力；缺省时按平台默认（聊天卡由平台显示）。 */
+    ui?: GameUiOptions;
+}
+export interface GameAsset {
+    path: string;
+    hash: string;
+    bytes?: number;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC5B;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,aAAa,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,mCAAmC;IACnC,EAAE,CAAC,EAAE,aAAa,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/manifest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":""}

package/dist/module-api.d.ts

@@ -0,0 +1,103 @@
+import type { NoticeCode, PlatformCode } from './codes.js';
+import type { GameUiOptions } from './manifest.js';
+import type { RoomPhase, SeatRole } from './seats.js';
+/**
+ * 宿主与游戏模块之间的 ABI。
+ * 1. 游戏状态不进平台对象，平台只搬 opaque blob。
+ * 2. 游戏不直接碰 socket，对外投递只通过 Effect[]。
+ * 3. 游戏不改房间相位、座位表或房主权限。
+ */
+export type ViewerId = string | null;
+export type Effect = {
+    kind: 'broadcast';
+    name: string;
+    payload?: unknown;
+} | {
+    kind: 'toSeat';
+    seatId: string;
+    name: string;
+    payload?: unknown;
+} | {
+    kind: 'notice';
+    code: NoticeCode;
+    text?: string;
+} | {
+    kind: 'system';
+    text: string;
+} | {
+    kind: 'end';
+    reason?: string;
+} | {
+    kind: 'kick';
+    seatId: string;
+    reason?: string;
+};
+export interface Reject {
+    reject: string;
+    code?: PlatformCode;
+}
+export type Outcome = Effect[] | Reject;
+export declare function isReject(value: Outcome): value is Reject;
+export declare function reject(message: string, code?: PlatformCode): Reject;
+export interface GameAction {
+    name: string;
+    payload?: unknown;
+}
+/** 传给游戏模块的座位信息：不含 socket、不含票据，游戏拿不到传输细节。 */
+export interface GameSeatInfo {
+    seatId: string;
+    slot: number;
+    name: string;
+    role: SeatRole;
+    team: string | number | null;
+    ready: boolean;
+    connected: boolean;
+}
+export interface GameContext {
+    readonly roomCode: string;
+    readonly config: Record<string, unknown>;
+    /** 注入时钟与随机源，让规则测试可确定性推进。 */
+    now(): number;
+    random(): number;
+    seats(): GameSeatInfo[];
+    seat(seatId: string): GameSeatInfo | undefined;
+}
+export interface GameInstance {
+    /** 按视角裁剪后的状态；`null` 表示观战视角。 */
+    serialize(viewer: ViewerId): unknown;
+    handle(action: GameAction, by: string): Outcome;
+    /** 开局。平台已确认发话人是房主且所有人类玩家都 Ready。 */
+    begin(): Outcome;
+    snapshot(): unknown;
+    /** 心跳：规则计时窗口在这里推进（旧项目心跳里的玩法部分）。 */
+    tick?(now: number): Effect[];
+    onSeatJoin?(seat: GameSeatInfo): Effect[];
+    onSeatLeave?(seat: GameSeatInfo, phase: RoomPhase): Effect[];
+    /** 座位超时。托管与罚则属于游戏，不属于平台。 */
+    onTimeout?(seat: GameSeatInfo): Effect[];
+    dispose?(): void;
+}
+export interface GameModule {
+    id: string;
+    name: string;
+    version: string;
+    entry: string;
+    seats: {
+        min: number;
+        max: number;
+    };
+    allowSpectate: boolean;
+    soloFill: boolean;
+    roles: SeatRole[];
+    /** 把房主原始设置规范化；返回的形状决定 rulesHash 与 create 的输入。 */
+    normalizeConfig(raw: Record<string, unknown> | undefined): Record<string, unknown>;
+    /** 只摘要真正影响对局的字段，避免"改了房间名也算房规不同"。 */
+    rulesHashOf(config: Record<string, unknown>): string;
+    create(config: Record<string, unknown>, ctx: GameContext): GameInstance;
+    resume(snapshot: unknown, ctx: GameContext): GameInstance;
+    /** 存档快照的兼容性闸；返回 false 则平台丢弃快照并报错给房主。 */
+    acceptsSnapshot?(snapshot: unknown): boolean;
+    /** 可选 UI 声明；例如让游戏自己的聊天面板替代平台聊天卡。 */
+    ui?: GameUiOptions;
+}
+//# sourceMappingURL=module-api.d.ts.map

package/dist/module-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-api.d.ts","sourceRoot":"","sources":["../src/module-api.ts"],"names":[],"mappings":"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"}

package/dist/module-api.js

@@ -0,0 +1,7 @@
+export function isReject(value) {
+    return !Array.isArray(value) && typeof value?.reject === 'string';
+}
+export function reject(message, code) {
+    return code ? { reject: message, code } : { reject: message };
+}
+//# sourceMappingURL=module-api.js.map

package/dist/module-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-api.js","sourceRoot":"","sources":["../src/module-api.ts"],"names":[],"mappings":"AA4BA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAQ,KAAgB,EAAE,MAAM,KAAK,QAAQ,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,IAAmB;IACzD,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAChE,CAAC"}

package/dist/seats.d.ts

@@ -0,0 +1,20 @@
+/** 游戏 ABI 和客户端都认的座位/相位形状；平台的房间视图另在 protocol。 */
+export declare const SEAT_ROLES: readonly ["host", "player", "spectator", "ai"];
+export type SeatRole = (typeof SEAT_ROLES)[number];
+export declare const ROOM_PHASES: readonly ["lobby", "playing", "ended"];
+export type RoomPhase = (typeof ROOM_PHASES)[number];
+/** 座位视图（下发给客户端和游戏界面）。 */
+export interface SeatView {
+    seatId: string;
+    slot: number;
+    name: string;
+    role: SeatRole;
+    ready: boolean;
+    connected: boolean;
+    /** 距上次心跳的毫秒数；离线座位为 null。 */
+    ageMs: number | null;
+    team: string | number | null;
+    /** 是否为房主座位（role==='host' 的冗余标记，便于前端画 🎮）。 */
+    isHost: boolean;
+}
+//# sourceMappingURL=seats.d.ts.map

package/dist/seats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seats.d.ts","sourceRoot":"","sources":["../src/seats.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAEhD,eAAO,MAAM,UAAU,gDAAiD,CAAC;AACzE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,WAAW,wCAAyC,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,yBAAyB;AACzB,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAC;CACjB"}

package/dist/seats.js

@@ -0,0 +1,4 @@
+/** 游戏 ABI 和客户端都认的座位/相位形状；平台的房间视图另在 protocol。 */
+export const SEAT_ROLES = ['host', 'player', 'spectator', 'ai'];
+export const ROOM_PHASES = ['lobby', 'playing', 'ended'];
+//# sourceMappingURL=seats.js.map

package/dist/seats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seats.js","sourceRoot":"","sources":["../src/seats.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAEhD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAU,CAAC;AAGzE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/** 游戏 ABI 和宿主支持的模式/接口版本。 */
+export declare const API_VERSION = 1;
+export declare const SUPPORTED_API_VERSIONS: readonly number[];
+export declare const GAME_MODES: readonly ["turn", "realtime"];
+export type GameMode = (typeof GAME_MODES)[number];
+/** 当前宿主只实际支持 turn；realtime 是规划中的 profile。 */
+export declare const SUPPORTED_MODES: Readonly<Record<GameMode, readonly number[]>>;
+export declare const DEFAULT_MODE: GameMode;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAE5B,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAkB,CAAC;AAEvE,eAAO,MAAM,UAAU,+BAAgC,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,6CAA6C;AAC7C,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC,CAGzE,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,QAAiB,CAAC"}

package/dist/version.js

@@ -0,0 +1,11 @@
+/** 游戏 ABI 和宿主支持的模式/接口版本。 */
+export const API_VERSION = 1;
+export const SUPPORTED_API_VERSIONS = [API_VERSION];
+export const GAME_MODES = ['turn', 'realtime'];
+/** 当前宿主只实际支持 turn；realtime 是规划中的 profile。 */
+export const SUPPORTED_MODES = {
+    turn: [1],
+    realtime: [],
+};
+export const DEFAULT_MODE = 'turn';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAE5B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,WAAW,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,UAAU,CAAU,CAAC;AAGxD,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAkD;IAC5E,IAAI,EAAE,CAAC,CAAC,CAAC;IACT,QAAQ,EAAE,EAAE;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAa,MAAM,CAAC"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lizardon386/core-abi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "3178 游戏接口层：GameModule / GameInstance / Effect 等宿主与游戏共同遵守的 ABI 和数据类型",
+  "license": "MIT",
+  "author": "3178-battle-platform contributors",
+  "homepage": "https://github.com/Lizardon386/3178-battle-platform#readme",
+  "bugs": {
+    "url": "https://github.com/Lizardon386/3178-battle-platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lizardon386/3178-battle-platform.git",
+    "directory": "packages/core-abi"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "keywords": [
+    "3178",
+    "game-platform",
+    "game-abi",
+    "types"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,11 @@
+export interface GameClientContract {
+  /** 把对局状态渲染进容器；返回的视图要能在下一次 mount 时替换。 */
+  mount(host: HTMLElement, view: unknown, actions: GameActions): void;
+  unmount?(host: HTMLElement): void;
+  onEvent?(event: { name: string; payload?: unknown }, actions: GameActions): void;
+}
+
+export interface GameActions {
+  send(name: string, payload?: unknown): void;
+  seatId(): string | null;
+}

package/src/codes.ts

@@ -0,0 +1,33 @@
+/** 平台错误码和通知码：游戏会用到，放进 ABI；默认文案留在 protocol。 */
+
+export const PLATFORM_CODES = [
+  'PROTOCOL',
+  'VERSION',
+  'RULES',
+  'UNKNOWN_GAME',
+  'NOROOM',
+  'NOSEAT',
+  'FULL',
+  'NOTHOST',
+  'HOSTONLY',
+  'PASSWORD',
+  'PHASE',
+  'RATE',
+  'SEATLOST',
+  'BADMSG',
+  'INTERNAL',
+] as const;
+
+export type PlatformCode = (typeof PLATFORM_CODES)[number];
+
+export const NOTICE_CODES = [
+  'HOSTLEFT',
+  'HOST_CHANGED',
+  'ROOM_CLOSED',
+  'SEAT_EJECTED',
+  'RULES_MISMATCH',
+  'REJOINED',
+  'TOO_FEW',
+] as const;
+
+export type NoticeCode = (typeof NOTICE_CODES)[number];

package/src/hash.ts

@@ -0,0 +1,87 @@
+/**
+ * 稳定摘要：把任意 JSON 值规范化后算出可跨端复现的短哈希。
+ * 只回答"两端配置是否一致"，不做安全用途；包完整性另走 sha256。
+ */
+
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = (1n << 64n) - 1n;
+
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function encode(value: unknown, seen: Set<object>, out: string[]): void {
+  if (value === null) {
+    out.push('null');
+    return;
+  }
+  if (typeof value === 'boolean' || typeof value === 'string' || typeof value === 'number') {
+    out.push(JSON.stringify(value) ?? 'null');
+    return;
+  }
+  if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+    out.push('null');
+    return;
+  }
+  if (typeof value === 'bigint') {
+    out.push(`${value.toString(16)}n`);
+    return;
+  }
+  if (!isPlainObject(value) && !Array.isArray(value)) {
+    out.push(`"${String(value)}"`);
+    return;
+  }
+  if (seen.has(value)) throw new TypeError('规范化失败：存在循环引用');
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      out.push('[');
+      value.forEach((item, i) => {
+        if (i) out.push(',');
+        encode(item, seen, out);
+      });
+      out.push(']');
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+    out.push('{');
+    keys.forEach((k, i) => {
+      if (i) out.push(',');
+      out.push(JSON.stringify(k), ':');
+      encode(obj[k], seen, out);
+    });
+    out.push('}');
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/** 键排序、数组保序、undefined 归 null 的确定性 JSON。 */
+export function canonicalJson(value: unknown): string {
+  const out: string[] = [];
+  encode(value, new Set(), out);
+  return out.join('');
+}
+
+function fnv1a64(text: string): bigint {
+  const bytes = new TextEncoder().encode(text);
+  let hash = FNV_OFFSET;
+  for (const b of bytes) {
+    hash ^= BigInt(b);
+    hash = (hash * FNV_PRIME) & MASK_64;
+  }
+  return hash;
+}
+
+/** 16 位十六进制稳定摘要。同一输入在 Node 与浏览器下结果必须一致。 */
+export function stableDigest(value: unknown): string {
+  return fnv1a64(canonicalJson(value)).toString(16).padStart(16, '0');
+}
+
+export function digestsMatch(a: string | undefined, b: string | undefined): boolean {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  return a.toLowerCase() === b.toLowerCase();
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './module-api.js';
+export * from './client.js';
+export * from './seats.js';
+export * from './manifest.js';
+export * from './codes.js';
+export * from './hash.js';
+export * from './version.js';

package/src/manifest.ts

@@ -0,0 +1,34 @@
+import type { SeatRole } from './seats.js';
+
+export interface GameUiOptions {
+  /** 游戏内聊天由平台聊天卡提供，还是由游戏自己的界面提供。 */
+  chat?: 'platform' | 'game';
+}
+
+/** 游戏模块对外声明的自己：房主建房、客户端校验、模块下发三处都要用它。 */
+export interface GameManifest {
+  id: string;
+  name: string;
+  /** 语义化版本，只用于展示与"版本不同"的提示文案。 */
+  version: string;
+  /** 房规摘要：由 create 时的 config 算出，与 config 一起构成入房闸。 */
+  rulesHash: string;
+  seats: { min: number; max: number };
+  allowSpectate: boolean;
+  /** 游戏是否支持 AI 填充席位（war3 的"电脑玩家"）。 */
+  soloFill: boolean;
+  /** 需要的席位角色集合，平台据此拒绝模块乱用角色。 */
+  roles: SeatRole[];
+  /** 客户端 UI 入口，相对该模块的 base URL。 */
+  entry: string;
+  /** 下发给客户端的资源清单；hash 为 'sha256:<hex>' 或裸 hex。 */
+  assets?: GameAsset[];
+  /** 可选 UI 能力；缺省时按平台默认（聊天卡由平台显示）。 */
+  ui?: GameUiOptions;
+}
+
+export interface GameAsset {
+  path: string;
+  hash: string;
+  bytes?: number;
+}

package/src/module-api.ts

@@ -0,0 +1,98 @@
+import type { NoticeCode, PlatformCode } from './codes.js';
+import type { GameUiOptions } from './manifest.js';
+import type { RoomPhase, SeatRole } from './seats.js';
+
+/**
+ * 宿主与游戏模块之间的 ABI。
+ * 1. 游戏状态不进平台对象，平台只搬 opaque blob。
+ * 2. 游戏不直接碰 socket，对外投递只通过 Effect[]。
+ * 3. 游戏不改房间相位、座位表或房主权限。
+ */
+
+export type ViewerId = string | null;
+
+export type Effect =
+  | { kind: 'broadcast'; name: string; payload?: unknown }
+  | { kind: 'toSeat'; seatId: string; name: string; payload?: unknown }
+  | { kind: 'notice'; code: NoticeCode; text?: string }
+  | { kind: 'system'; text: string }
+  | { kind: 'end'; reason?: string }
+  | { kind: 'kick'; seatId: string; reason?: string };
+
+export interface Reject {
+  reject: string;
+  code?: PlatformCode;
+}
+
+export type Outcome = Effect[] | Reject;
+
+export function isReject(value: Outcome): value is Reject {
+  return !Array.isArray(value) && typeof (value as Reject)?.reject === 'string';
+}
+
+export function reject(message: string, code?: PlatformCode): Reject {
+  return code ? { reject: message, code } : { reject: message };
+}
+
+export interface GameAction {
+  name: string;
+  payload?: unknown;
+}
+
+/** 传给游戏模块的座位信息：不含 socket、不含票据，游戏拿不到传输细节。 */
+export interface GameSeatInfo {
+  seatId: string;
+  slot: number;
+  name: string;
+  role: SeatRole;
+  team: string | number | null;
+  ready: boolean;
+  connected: boolean;
+}
+
+export interface GameContext {
+  readonly roomCode: string;
+  readonly config: Record<string, unknown>;
+  /** 注入时钟与随机源，让规则测试可确定性推进。 */
+  now(): number;
+  random(): number;
+  seats(): GameSeatInfo[];
+  seat(seatId: string): GameSeatInfo | undefined;
+}
+
+export interface GameInstance {
+  /** 按视角裁剪后的状态；`null` 表示观战视角。 */
+  serialize(viewer: ViewerId): unknown;
+  handle(action: GameAction, by: string): Outcome;
+  /** 开局。平台已确认发话人是房主且所有人类玩家都 Ready。 */
+  begin(): Outcome;
+  snapshot(): unknown;
+  /** 心跳：规则计时窗口在这里推进（旧项目心跳里的玩法部分）。 */
+  tick?(now: number): Effect[];
+  onSeatJoin?(seat: GameSeatInfo): Effect[];
+  onSeatLeave?(seat: GameSeatInfo, phase: RoomPhase): Effect[];
+  /** 座位超时。托管与罚则属于游戏，不属于平台。 */
+  onTimeout?(seat: GameSeatInfo): Effect[];
+  dispose?(): void;
+}
+
+export interface GameModule {
+  id: string;
+  name: string;
+  version: string;
+  entry: string;
+  seats: { min: number; max: number };
+  allowSpectate: boolean;
+  soloFill: boolean;
+  roles: SeatRole[];
+  /** 把房主原始设置规范化；返回的形状决定 rulesHash 与 create 的输入。 */
+  normalizeConfig(raw: Record<string, unknown> | undefined): Record<string, unknown>;
+  /** 只摘要真正影响对局的字段，避免"改了房间名也算房规不同"。 */
+  rulesHashOf(config: Record<string, unknown>): string;
+  create(config: Record<string, unknown>, ctx: GameContext): GameInstance;
+  resume(snapshot: unknown, ctx: GameContext): GameInstance;
+  /** 存档快照的兼容性闸；返回 false 则平台丢弃快照并报错给房主。 */
+  acceptsSnapshot?(snapshot: unknown): boolean;
+  /** 可选 UI 声明；例如让游戏自己的聊天面板替代平台聊天卡。 */
+  ui?: GameUiOptions;
+}

package/src/seats.ts

@@ -0,0 +1,22 @@
+/** 游戏 ABI 和客户端都认的座位/相位形状；平台的房间视图另在 protocol。 */
+
+export const SEAT_ROLES = ['host', 'player', 'spectator', 'ai'] as const;
+export type SeatRole = (typeof SEAT_ROLES)[number];
+
+export const ROOM_PHASES = ['lobby', 'playing', 'ended'] as const;
+export type RoomPhase = (typeof ROOM_PHASES)[number];
+
+/** 座位视图（下发给客户端和游戏界面）。 */
+export interface SeatView {
+  seatId: string;
+  slot: number;
+  name: string;
+  role: SeatRole;
+  ready: boolean;
+  connected: boolean;
+  /** 距上次心跳的毫秒数；离线座位为 null。 */
+  ageMs: number | null;
+  team: string | number | null;
+  /** 是否为房主座位（role==='host' 的冗余标记，便于前端画 🎮）。 */
+  isHost: boolean;
+}

package/src/version.ts

@@ -0,0 +1,16 @@
+/** 游戏 ABI 和宿主支持的模式/接口版本。 */
+
+export const API_VERSION = 1;
+
+export const SUPPORTED_API_VERSIONS: readonly number[] = [API_VERSION];
+
+export const GAME_MODES = ['turn', 'realtime'] as const;
+export type GameMode = (typeof GAME_MODES)[number];
+
+/** 当前宿主只实际支持 turn；realtime 是规划中的 profile。 */
+export const SUPPORTED_MODES: Readonly<Record<GameMode, readonly number[]>> = {
+  turn: [1],
+  realtime: [],
+};
+
+export const DEFAULT_MODE: GameMode = 'turn';