@lizardon386/core-abi 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export * from './module-api.js';
 export * from './client.js';
 export * from './seats.js';
 export * from './manifest.js';
+export * from './reference.js';
+export * from './rule-config.js';
 export * from './codes.js';
 export * from './hash.js';
 export * from './version.js';

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -2,6 +2,8 @@ export * from './module-api.js';
 export * from './client.js';
 export * from './seats.js';
 export * from './manifest.js';
+export * from './reference.js';
+export * from './rule-config.js';
 export * from './codes.js';
 export * from './hash.js';
 export * from './version.js';

package/dist/index.js.map

@@ -1 +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"}
+{"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,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/manifest.d.ts

@@ -3,6 +3,58 @@ export interface GameUiOptions {
     /** 游戏内聊天由平台聊天卡提供，还是由游戏自己的界面提供。 */
     chat?: 'platform' | 'game';
 }
+type RuleConfigFieldBase = {
+    key: string;
+    label: string;
+    description?: string;
+};
+/** 建房时房主需要填的一项规则；只声明表单项，值仍走 roomCreate.config。 */
+export type RuleConfigField = (RuleConfigFieldBase & {
+    type: 'boolean';
+    default: boolean;
+}) | (RuleConfigFieldBase & {
+    type: 'enum';
+    default: string;
+    options: Array<{
+        value: string;
+        label: string;
+        description?: string;
+    }>;
+}) | (RuleConfigFieldBase & {
+    type: 'integer';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+});
+/** 游戏的规则表单声明；平台据此渲染开关，规范化与校验仍由游戏和服务端负责。 */
+export interface RuleConfigSpec {
+    fields: RuleConfigField[];
+}
+/** 游戏提供的静态资料入口；只给包内相对路径，内容懒加载。 */
+export interface GameReferenceSpec {
+    entry: string;
+}
+export interface GameReferenceDocument {
+    version: 1;
+    title?: string;
+    groups: GameReferenceGroup[];
+}
+export interface GameReferenceGroup {
+    id: string;
+    title: string;
+    items: GameReferenceItem[];
+}
+export interface GameReferenceItem {
+    title?: string;
+    text: string;
+    images?: GameReferenceImage[];
+}
+export interface GameReferenceImage {
+    path: string;
+    alt: string;
+    caption?: string;
+}
 /** 游戏模块对外声明的自己：房主建房、客户端校验、模块下发三处都要用它。 */
 export interface GameManifest {
     id: string;
@@ -26,10 +78,15 @@ export interface GameManifest {
     assets?: GameAsset[];
     /** 可选 UI 能力；缺省时按平台默认（聊天卡由平台显示）。 */
     ui?: GameUiOptions;
+    /** 建房时的规则表单；缺省表示这个游戏没有可配置项。 */
+    ruleConfig?: RuleConfigSpec;
+    /** 静态资料入口；只声明路径，文档由平台按需取。 */
+    reference?: GameReferenceSpec;
 }
 export interface GameAsset {
     path: string;
     hash: string;
     bytes?: number;
 }
+export {};
 //# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

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

package/dist/module-api.d.ts

@@ -1,5 +1,5 @@
 import type { NoticeCode, PlatformCode } from './codes.js';
-import type { GameUiOptions } from './manifest.js';
+import type { GameReferenceSpec, GameUiOptions, RuleConfigSpec } from './manifest.js';
 import type { RoomPhase, SeatRole } from './seats.js';
 /**
  * 宿主与游戏模块之间的 ABI。
@@ -99,5 +99,9 @@ export interface GameModule {
     acceptsSnapshot?(snapshot: unknown): boolean;
     /** 可选 UI 声明；例如让游戏自己的聊天面板替代平台聊天卡。 */
     ui?: GameUiOptions;
+    /** 建房规则表单；只声明可配置项，值仍由 normalizeConfig 收口。 */
+    ruleConfig?: RuleConfigSpec;
+    /** 静态资料入口；manifest 只带路径，文档由平台懒加载。 */
+    reference?: GameReferenceSpec;
 }
 //# sourceMappingURL=module-api.d.ts.map

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

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

package/dist/reference.d.ts

@@ -0,0 +1,36 @@
+import type { GameReferenceDocument } from './manifest.js';
+/**
+ * 游戏静态资料：平台只认纯文本 + 图片，不解析 HTML / Markdown。
+ * 这一份解析器由平台客户端和 sdk-tools 共用，校验口径只有一处。
+ */
+export declare const GAME_REFERENCE_LIMITS: {
+    readonly documentBytes: number;
+    readonly groups: 20;
+    readonly items: 120;
+    readonly groupId: 64;
+    readonly documentTitle: 40;
+    readonly groupTitle: 40;
+    readonly itemTitle: 60;
+    readonly text: 2000;
+    readonly imagesPerItem: 6;
+    readonly entryLength: 256;
+    readonly alt: 120;
+    readonly caption: 120;
+};
+export type GameReferenceParseResult = {
+    ok: true;
+    doc: GameReferenceDocument;
+} | {
+    ok: false;
+    error: string;
+};
+/** 包内相对路径：不接受绝对路径、反斜杠、`..` 段和空段。 */
+export declare function isValidPackRelativePath(value: unknown): value is string;
+/** reference.entry 指向包内 JSON 文档。 */
+export declare function isValidGameReferenceEntry(value: unknown): value is string;
+/**
+ * 校验并规范化资料文档。输入可以是已解析的对象，也可以是原始 JSON 文本；
+ * 失败时返回一句可以直接显示给开发者的中文原因。
+ */
+export declare function parseGameReference(value: unknown): GameReferenceParseResult;
+//# sourceMappingURL=reference.d.ts.map

package/dist/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../src/reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EAItB,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAaxB,CAAC;AAIX,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,qBAAqB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAoBjC,oCAAoC;AACpC,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAMvE;AAED,oCAAoC;AACpC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzE;AA+DD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CA2B3E"}

package/dist/reference.js

@@ -0,0 +1,161 @@
+/**
+ * 游戏静态资料：平台只认纯文本 + 图片，不解析 HTML / Markdown。
+ * 这一份解析器由平台客户端和 sdk-tools 共用，校验口径只有一处。
+ */
+export const GAME_REFERENCE_LIMITS = {
+    documentBytes: 64 * 1024,
+    groups: 20,
+    items: 120,
+    groupId: 64,
+    documentTitle: 40,
+    groupTitle: 40,
+    itemTitle: 60,
+    text: 2000,
+    imagesPerItem: 6,
+    entryLength: 256,
+    alt: 120,
+    caption: 120,
+};
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'svg', 'gif'];
+class ReferenceCheckError extends Error {
+}
+function fail(path, message) {
+    throw new ReferenceCheckError(path ? `${path} ${message}` : message);
+}
+function chars(value) {
+    return [...value].length;
+}
+function utf8Bytes(value) {
+    return new TextEncoder().encode(value).length;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** 包内相对路径：不接受绝对路径、反斜杠、`..` 段和空段。 */
+export function isValidPackRelativePath(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    if (value.length > GAME_REFERENCE_LIMITS.entryLength)
+        return false;
+    if (value.includes('\\') || value.startsWith('/') || /^[A-Za-z]:/.test(value))
+        return false;
+    if (/[\u0000-\u001f]/.test(value))
+        return false;
+    return value.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
+/** reference.entry 指向包内 JSON 文档。 */
+export function isValidGameReferenceEntry(value) {
+    return isValidPackRelativePath(value) && /\.json$/i.test(value);
+}
+function readText(value, path, limit, required) {
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== 'string')
+        fail(path, '必须是字符串');
+    if (value.length === 0)
+        fail(path, '不能为空');
+    if (chars(value) > limit)
+        fail(path, `超过 ${limit} 字`);
+    return value;
+}
+function readImage(value, path) {
+    if (!isObject(value))
+        fail(path, '必须是对象');
+    const imagePath = value.path;
+    if (!isValidPackRelativePath(imagePath))
+        fail(`${path}.path`, '必须是合法的包内相对路径');
+    if (!IMAGE_EXTENSIONS.some((ext) => imagePath.toLowerCase().endsWith(`.${ext}`))) {
+        fail(`${path}.path`, `扩展名只允许 ${IMAGE_EXTENSIONS.join(' / ')}`);
+    }
+    const alt = readText(value.alt, `${path}.alt`, GAME_REFERENCE_LIMITS.alt, true);
+    const caption = readText(value.caption, `${path}.caption`, GAME_REFERENCE_LIMITS.caption, false);
+    return { path: imagePath, alt, ...(caption === undefined ? {} : { caption }) };
+}
+function readItem(value, path) {
+    if (!isObject(value))
+        fail(path, '必须是对象');
+    const title = readText(value.title, `${path}.title`, GAME_REFERENCE_LIMITS.itemTitle, false);
+    const text = readText(value.text, `${path}.text`, GAME_REFERENCE_LIMITS.text, true);
+    let images;
+    if (value.images !== undefined) {
+        if (!Array.isArray(value.images))
+            fail(`${path}.images`, '必须是数组');
+        if (value.images.length > GAME_REFERENCE_LIMITS.imagesPerItem) {
+            fail(`${path}.images`, `每项最多 ${GAME_REFERENCE_LIMITS.imagesPerItem} 张图`);
+        }
+        images = value.images.map((image, index) => readImage(image, `${path}.images[${index}]`));
+    }
+    return { text, ...(title === undefined ? {} : { title }), ...(images === undefined ? {} : { images }) };
+}
+function readGroup(value, path, seenIds) {
+    if (!isObject(value))
+        fail(path, '必须是对象');
+    if (typeof value.id !== 'string' || value.id.length === 0)
+        fail(`${path}.id`, '必须是非空字符串');
+    if (chars(value.id) > GAME_REFERENCE_LIMITS.groupId)
+        fail(`${path}.id`, `超过 ${GAME_REFERENCE_LIMITS.groupId} 字`);
+    if (seenIds.has(value.id))
+        fail(`${path}.id`, '与前面的分组重复');
+    seenIds.add(value.id);
+    const title = readText(value.title, `${path}.title`, GAME_REFERENCE_LIMITS.groupTitle, true);
+    if (!Array.isArray(value.items))
+        fail(`${path}.items`, '必须是数组');
+    const items = value.items.map((item, index) => readItem(item, `${path}.items[${index}]`));
+    return { id: value.id, title, items };
+}
+function parseDocument(value) {
+    if (!isObject(value))
+        fail('', '资料文档必须是对象');
+    if (value.version !== 1)
+        fail('version', '当前只支持 1');
+    const title = readText(value.title, 'title', GAME_REFERENCE_LIMITS.documentTitle, false);
+    if (!Array.isArray(value.groups))
+        fail('groups', '必须是数组');
+    if (value.groups.length === 0)
+        fail('groups', '至少要有一个分组');
+    if (value.groups.length > GAME_REFERENCE_LIMITS.groups)
+        fail('groups', `最多 ${GAME_REFERENCE_LIMITS.groups} 组`);
+    const seenIds = new Set();
+    const groups = value.groups.map((group, index) => readGroup(group, `groups[${index}]`, seenIds));
+    const totalItems = groups.reduce((sum, group) => sum + group.items.length, 0);
+    if (totalItems > GAME_REFERENCE_LIMITS.items)
+        fail('groups', `条数合计最多 ${GAME_REFERENCE_LIMITS.items} 条`);
+    return { version: 1, ...(title === undefined ? {} : { title }), groups };
+}
+/**
+ * 校验并规范化资料文档。输入可以是已解析的对象，也可以是原始 JSON 文本；
+ * 失败时返回一句可以直接显示给开发者的中文原因。
+ */
+export function parseGameReference(value) {
+    try {
+        let raw = value;
+        if (typeof value === 'string') {
+            if (utf8Bytes(value) > GAME_REFERENCE_LIMITS.documentBytes) {
+                fail('', `文档超过 ${GAME_REFERENCE_LIMITS.documentBytes} 字节`);
+            }
+            try {
+                raw = JSON.parse(value);
+            }
+            catch {
+                fail('', '不是合法的 JSON');
+            }
+        }
+        let bytes;
+        try {
+            bytes = utf8Bytes(JSON.stringify(raw) ?? '');
+        }
+        catch {
+            fail('', '文档无法序列化');
+        }
+        if (bytes > GAME_REFERENCE_LIMITS.documentBytes) {
+            fail('', `文档超过 ${GAME_REFERENCE_LIMITS.documentBytes} 字节`);
+        }
+        return { ok: true, doc: parseDocument(raw) };
+    }
+    catch (error) {
+        if (error instanceof ReferenceCheckError)
+            return { ok: false, error: error.message };
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=reference.js.map

package/dist/reference.js.map

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

package/dist/rule-config.d.ts

@@ -0,0 +1,25 @@
+import type { RuleConfigSpec } from './manifest.js';
+/**
+ * 建房规则表单的校验口径。声明的是表单项，不是值；
+ * 值仍由 roomCreate.config 传入，由游戏 normalizeConfig 规范化、服务端校验。
+ */
+export declare const RULE_CONFIG_LIMITS: {
+    readonly fields: 24;
+    readonly keyLength: 32;
+    readonly label: 40;
+    readonly description: 200;
+    readonly enumOptions: 8;
+    readonly enumValueLength: 32;
+    readonly enumLabel: 24;
+    readonly integerSpan: 1000;
+};
+export type RuleConfigParseResult = {
+    ok: true;
+    spec: RuleConfigSpec;
+} | {
+    ok: false;
+    error: string;
+};
+/** 校验并规范化规则表单声明；失败时返回一句可以直接显示给开发者的中文原因。 */
+export declare function parseRuleConfig(value: unknown): RuleConfigParseResult;
+//# sourceMappingURL=rule-config.d.ts.map

package/dist/rule-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-config.d.ts","sourceRoot":"","sources":["../src/rule-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;CASrB,CAAC;AAKX,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAsGjC,2CAA2C;AAC3C,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAarE"}

package/dist/rule-config.js

@@ -0,0 +1,147 @@
+/**
+ * 建房规则表单的校验口径。声明的是表单项，不是值；
+ * 值仍由 roomCreate.config 传入，由游戏 normalizeConfig 规范化、服务端校验。
+ */
+export const RULE_CONFIG_LIMITS = {
+    fields: 24,
+    keyLength: 32,
+    label: 40,
+    description: 200,
+    enumOptions: 8,
+    enumValueLength: 32,
+    enumLabel: 24,
+    integerSpan: 1000,
+};
+const KEY_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+const ENUM_VALUE_PATTERN = /^[a-z0-9-]{1,32}$/;
+class RuleConfigCheckError extends Error {
+}
+function fail(path, message) {
+    throw new RuleConfigCheckError(path ? `${path} ${message}` : message);
+}
+function chars(value) {
+    return [...value].length;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function readLabel(value, path, limit) {
+    if (typeof value !== 'string')
+        fail(path, '必须是字符串');
+    if (value.length === 0)
+        fail(path, '不能为空');
+    if (chars(value) > limit)
+        fail(path, `超过 ${limit} 字`);
+    return value;
+}
+function readDescription(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        fail(path, '必须是字符串');
+    if (chars(value) > RULE_CONFIG_LIMITS.description)
+        fail(path, `超过 ${RULE_CONFIG_LIMITS.description} 字`);
+    return value;
+}
+function readField(value, path, seenKeys) {
+    if (!isObject(value))
+        fail(path, '必须是对象');
+    if (typeof value.key !== 'string' || !KEY_PATTERN.test(value.key)) {
+        fail(`${path}.key`, '必须匹配 ^[a-z][a-z0-9-]{0,31}$');
+    }
+    if (seenKeys.has(value.key))
+        fail(`${path}.key`, '与前面的字段重复');
+    seenKeys.add(value.key);
+    const label = readLabel(value.label, `${path}.label`, RULE_CONFIG_LIMITS.label);
+    const description = readDescription(value.description, `${path}.description`);
+    if (value.type === 'boolean') {
+        if (typeof value.default !== 'boolean')
+            fail(`${path}.default`, 'boolean 字段的默认值必须是布尔值');
+        return { key: value.key, label, type: 'boolean', default: value.default, ...(description === undefined ? {} : { description }) };
+    }
+    if (value.type === 'enum') {
+        if (!Array.isArray(value.options))
+            fail(`${path}.options`, '必须是数组');
+        if (value.options.length === 0)
+            fail(`${path}.options`, '至少要有一个选项');
+        if (value.options.length > RULE_CONFIG_LIMITS.enumOptions) {
+            fail(`${path}.options`, `最多 ${RULE_CONFIG_LIMITS.enumOptions} 个选项`);
+        }
+        const seenValues = new Set();
+        const options = value.options.map((option, index) => {
+            const optionPath = `${path}.options[${index}]`;
+            if (!isObject(option))
+                fail(optionPath, '必须是对象');
+            if (typeof option.value !== 'string' || !ENUM_VALUE_PATTERN.test(option.value)) {
+                fail(`${optionPath}.value`, '必须匹配 ^[a-z0-9-]{1,32}$');
+            }
+            if (seenValues.has(option.value))
+                fail(`${optionPath}.value`, '与前面的选项重复');
+            seenValues.add(option.value);
+            const optionLabel = readLabel(option.label, `${optionPath}.label`, RULE_CONFIG_LIMITS.enumLabel);
+            const optionDescription = readDescription(option.description, `${optionPath}.description`);
+            return { value: option.value, label: optionLabel, ...(optionDescription === undefined ? {} : { description: optionDescription }) };
+        });
+        if (typeof value.default !== 'string')
+            fail(`${path}.default`, 'enum 字段的默认值必须是字符串');
+        if (!seenValues.has(value.default))
+            fail(`${path}.default`, '必须是 options 里的某个 value');
+        return { key: value.key, label, type: 'enum', default: value.default, options, ...(description === undefined ? {} : { description }) };
+    }
+    if (value.type === 'integer') {
+        if (typeof value.default !== 'number' || !Number.isSafeInteger(value.default)) {
+            fail(`${path}.default`, 'integer 字段的默认值必须是整数');
+        }
+        if (typeof value.min !== 'number' || !Number.isSafeInteger(value.min))
+            fail(`${path}.min`, '必须是整数');
+        if (typeof value.max !== 'number' || !Number.isSafeInteger(value.max))
+            fail(`${path}.max`, '必须是整数');
+        if (value.min > value.default)
+            fail(`${path}.min`, '不能大于 default');
+        if (value.default > value.max)
+            fail(`${path}.max`, '不能小于 default');
+        if (value.max - value.min > RULE_CONFIG_LIMITS.integerSpan) {
+            fail(`${path}.max`, `与 min 的跨度最多 ${RULE_CONFIG_LIMITS.integerSpan}`);
+        }
+        let step;
+        if (value.step !== undefined) {
+            if (typeof value.step !== 'number' || !Number.isSafeInteger(value.step) || value.step <= 0) {
+                fail(`${path}.step`, '必须是正整数');
+            }
+            step = value.step;
+        }
+        return {
+            key: value.key,
+            label,
+            type: 'integer',
+            default: value.default,
+            min: value.min,
+            max: value.max,
+            ...(step === undefined ? {} : { step }),
+            ...(description === undefined ? {} : { description }),
+        };
+    }
+    return fail(`${path}.type`, '只支持 boolean / enum / integer');
+}
+/** 校验并规范化规则表单声明；失败时返回一句可以直接显示给开发者的中文原因。 */
+export function parseRuleConfig(value) {
+    try {
+        if (!isObject(value))
+            fail('', '规则表单声明必须是对象');
+        if (!Array.isArray(value.fields))
+            fail('fields', '必须是数组');
+        if (value.fields.length === 0)
+            fail('fields', '至少要有一项');
+        if (value.fields.length > RULE_CONFIG_LIMITS.fields)
+            fail('fields', `最多 ${RULE_CONFIG_LIMITS.fields} 项`);
+        const seenKeys = new Set();
+        const fields = value.fields.map((field, index) => readField(field, `fields[${index}]`, seenKeys));
+        return { ok: true, spec: { fields } };
+    }
+    catch (error) {
+        if (error instanceof RuleConfigCheckError)
+            return { ok: false, error: error.message };
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=rule-config.js.map

package/dist/rule-config.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizardon386/core-abi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "3178 游戏接口层：GameModule / GameInstance / Effect 等宿主与游戏共同遵守的 ABI 和数据类型",
   "license": "MIT",
   "author": "3178-battle-platform contributors",

package/src/index.ts

@@ -2,6 +2,8 @@ export * from './module-api.js';
 export * from './client.js';
 export * from './seats.js';
 export * from './manifest.js';
+export * from './reference.js';
+export * from './rule-config.js';
 export * from './codes.js';
 export * from './hash.js';
 export * from './version.js';

package/src/manifest.ts

@@ -5,6 +5,56 @@ export interface GameUiOptions {
   chat?: 'platform' | 'game';
 }
 
+type RuleConfigFieldBase = {
+  key: string;
+  label: string;
+  description?: string;
+};
+
+/** 建房时房主需要填的一项规则；只声明表单项，值仍走 roomCreate.config。 */
+export type RuleConfigField =
+  | (RuleConfigFieldBase & { type: 'boolean'; default: boolean })
+  | (RuleConfigFieldBase & {
+      type: 'enum';
+      default: string;
+      options: Array<{ value: string; label: string; description?: string }>;
+    })
+  | (RuleConfigFieldBase & { type: 'integer'; default: number; min: number; max: number; step?: number });
+
+/** 游戏的规则表单声明；平台据此渲染开关，规范化与校验仍由游戏和服务端负责。 */
+export interface RuleConfigSpec {
+  fields: RuleConfigField[];
+}
+
+/** 游戏提供的静态资料入口；只给包内相对路径，内容懒加载。 */
+export interface GameReferenceSpec {
+  entry: string;
+}
+
+export interface GameReferenceDocument {
+  version: 1;
+  title?: string;
+  groups: GameReferenceGroup[];
+}
+
+export interface GameReferenceGroup {
+  id: string;
+  title: string;
+  items: GameReferenceItem[];
+}
+
+export interface GameReferenceItem {
+  title?: string;
+  text: string;
+  images?: GameReferenceImage[];
+}
+
+export interface GameReferenceImage {
+  path: string;
+  alt: string;
+  caption?: string;
+}
+
 /** 游戏模块对外声明的自己：房主建房、客户端校验、模块下发三处都要用它。 */
 export interface GameManifest {
   id: string;
@@ -25,6 +75,10 @@ export interface GameManifest {
   assets?: GameAsset[];
   /** 可选 UI 能力；缺省时按平台默认（聊天卡由平台显示）。 */
   ui?: GameUiOptions;
+  /** 建房时的规则表单；缺省表示这个游戏没有可配置项。 */
+  ruleConfig?: RuleConfigSpec;
+  /** 静态资料入口；只声明路径，文档由平台按需取。 */
+  reference?: GameReferenceSpec;
 }
 
 export interface GameAsset {

package/src/module-api.ts

@@ -1,5 +1,5 @@
 import type { NoticeCode, PlatformCode } from './codes.js';
-import type { GameUiOptions } from './manifest.js';
+import type { GameReferenceSpec, GameUiOptions, RuleConfigSpec } from './manifest.js';
 import type { RoomPhase, SeatRole } from './seats.js';
 
 /**
@@ -95,4 +95,8 @@ export interface GameModule {
   acceptsSnapshot?(snapshot: unknown): boolean;
   /** 可选 UI 声明；例如让游戏自己的聊天面板替代平台聊天卡。 */
   ui?: GameUiOptions;
+  /** 建房规则表单；只声明可配置项，值仍由 normalizeConfig 收口。 */
+  ruleConfig?: RuleConfigSpec;
+  /** 静态资料入口；manifest 只带路径，文档由平台懒加载。 */
+  reference?: GameReferenceSpec;
 }

package/src/reference.ts

@@ -0,0 +1,157 @@
+import type {
+  GameReferenceDocument,
+  GameReferenceGroup,
+  GameReferenceImage,
+  GameReferenceItem,
+} from './manifest.js';
+
+/**
+ * 游戏静态资料：平台只认纯文本 + 图片，不解析 HTML / Markdown。
+ * 这一份解析器由平台客户端和 sdk-tools 共用，校验口径只有一处。
+ */
+export const GAME_REFERENCE_LIMITS = {
+  documentBytes: 64 * 1024,
+  groups: 20,
+  items: 120,
+  groupId: 64,
+  documentTitle: 40,
+  groupTitle: 40,
+  itemTitle: 60,
+  text: 2000,
+  imagesPerItem: 6,
+  entryLength: 256,
+  alt: 120,
+  caption: 120,
+} as const;
+
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'svg', 'gif'];
+
+export type GameReferenceParseResult =
+  | { ok: true; doc: GameReferenceDocument }
+  | { ok: false; error: string };
+
+class ReferenceCheckError extends Error {}
+
+function fail(path: string, message: string): never {
+  throw new ReferenceCheckError(path ? `${path} ${message}` : message);
+}
+
+function chars(value: string): number {
+  return [...value].length;
+}
+
+function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).length;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 包内相对路径：不接受绝对路径、反斜杠、`..` 段和空段。 */
+export function isValidPackRelativePath(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  if (value.length > GAME_REFERENCE_LIMITS.entryLength) return false;
+  if (value.includes('\\') || value.startsWith('/') || /^[A-Za-z]:/.test(value)) return false;
+  if (/[\u0000-\u001f]/.test(value)) return false;
+  return value.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
+
+/** reference.entry 指向包内 JSON 文档。 */
+export function isValidGameReferenceEntry(value: unknown): value is string {
+  return isValidPackRelativePath(value) && /\.json$/i.test(value);
+}
+
+function readText(value: unknown, path: string, limit: number, required: boolean): string | undefined {
+  if (value === undefined && !required) return undefined;
+  if (typeof value !== 'string') fail(path, '必须是字符串');
+  if (value.length === 0) fail(path, '不能为空');
+  if (chars(value) > limit) fail(path, `超过 ${limit} 字`);
+  return value;
+}
+
+function readImage(value: unknown, path: string): GameReferenceImage {
+  if (!isObject(value)) fail(path, '必须是对象');
+  const imagePath = value.path;
+  if (!isValidPackRelativePath(imagePath)) fail(`${path}.path`, '必须是合法的包内相对路径');
+  if (!IMAGE_EXTENSIONS.some((ext) => imagePath.toLowerCase().endsWith(`.${ext}`))) {
+    fail(`${path}.path`, `扩展名只允许 ${IMAGE_EXTENSIONS.join(' / ')}`);
+  }
+  const alt = readText(value.alt, `${path}.alt`, GAME_REFERENCE_LIMITS.alt, true) as string;
+  const caption = readText(value.caption, `${path}.caption`, GAME_REFERENCE_LIMITS.caption, false);
+  return { path: imagePath, alt, ...(caption === undefined ? {} : { caption }) };
+}
+
+function readItem(value: unknown, path: string): GameReferenceItem {
+  if (!isObject(value)) fail(path, '必须是对象');
+  const title = readText(value.title, `${path}.title`, GAME_REFERENCE_LIMITS.itemTitle, false);
+  const text = readText(value.text, `${path}.text`, GAME_REFERENCE_LIMITS.text, true) as string;
+  let images: GameReferenceImage[] | undefined;
+  if (value.images !== undefined) {
+    if (!Array.isArray(value.images)) fail(`${path}.images`, '必须是数组');
+    if (value.images.length > GAME_REFERENCE_LIMITS.imagesPerItem) {
+      fail(`${path}.images`, `每项最多 ${GAME_REFERENCE_LIMITS.imagesPerItem} 张图`);
+    }
+    images = value.images.map((image, index) => readImage(image, `${path}.images[${index}]`));
+  }
+  return { text, ...(title === undefined ? {} : { title }), ...(images === undefined ? {} : { images }) };
+}
+
+function readGroup(value: unknown, path: string, seenIds: Set<string>): GameReferenceGroup {
+  if (!isObject(value)) fail(path, '必须是对象');
+  if (typeof value.id !== 'string' || value.id.length === 0) fail(`${path}.id`, '必须是非空字符串');
+  if (chars(value.id) > GAME_REFERENCE_LIMITS.groupId) fail(`${path}.id`, `超过 ${GAME_REFERENCE_LIMITS.groupId} 字`);
+  if (seenIds.has(value.id)) fail(`${path}.id`, '与前面的分组重复');
+  seenIds.add(value.id);
+  const title = readText(value.title, `${path}.title`, GAME_REFERENCE_LIMITS.groupTitle, true) as string;
+  if (!Array.isArray(value.items)) fail(`${path}.items`, '必须是数组');
+  const items = value.items.map((item, index) => readItem(item, `${path}.items[${index}]`));
+  return { id: value.id, title, items };
+}
+
+function parseDocument(value: unknown): GameReferenceDocument {
+  if (!isObject(value)) fail('', '资料文档必须是对象');
+  if (value.version !== 1) fail('version', '当前只支持 1');
+  const title = readText(value.title, 'title', GAME_REFERENCE_LIMITS.documentTitle, false);
+  if (!Array.isArray(value.groups)) fail('groups', '必须是数组');
+  if (value.groups.length === 0) fail('groups', '至少要有一个分组');
+  if (value.groups.length > GAME_REFERENCE_LIMITS.groups) fail('groups', `最多 ${GAME_REFERENCE_LIMITS.groups} 组`);
+  const seenIds = new Set<string>();
+  const groups = value.groups.map((group, index) => readGroup(group, `groups[${index}]`, seenIds));
+  const totalItems = groups.reduce((sum, group) => sum + group.items.length, 0);
+  if (totalItems > GAME_REFERENCE_LIMITS.items) fail('groups', `条数合计最多 ${GAME_REFERENCE_LIMITS.items} 条`);
+  return { version: 1, ...(title === undefined ? {} : { title }), groups };
+}
+
+/**
+ * 校验并规范化资料文档。输入可以是已解析的对象，也可以是原始 JSON 文本；
+ * 失败时返回一句可以直接显示给开发者的中文原因。
+ */
+export function parseGameReference(value: unknown): GameReferenceParseResult {
+  try {
+    let raw = value;
+    if (typeof value === 'string') {
+      if (utf8Bytes(value) > GAME_REFERENCE_LIMITS.documentBytes) {
+        fail('', `文档超过 ${GAME_REFERENCE_LIMITS.documentBytes} 字节`);
+      }
+      try {
+        raw = JSON.parse(value) as unknown;
+      } catch {
+        fail('', '不是合法的 JSON');
+      }
+    }
+    let bytes: number;
+    try {
+      bytes = utf8Bytes(JSON.stringify(raw) ?? '');
+    } catch {
+      fail('', '文档无法序列化');
+    }
+    if (bytes > GAME_REFERENCE_LIMITS.documentBytes) {
+      fail('', `文档超过 ${GAME_REFERENCE_LIMITS.documentBytes} 字节`);
+    }
+    return { ok: true, doc: parseDocument(raw) };
+  } catch (error) {
+    if (error instanceof ReferenceCheckError) return { ok: false, error: error.message };
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/rule-config.ts

@@ -0,0 +1,139 @@
+import type { RuleConfigField, RuleConfigSpec } from './manifest.js';
+
+/**
+ * 建房规则表单的校验口径。声明的是表单项，不是值；
+ * 值仍由 roomCreate.config 传入，由游戏 normalizeConfig 规范化、服务端校验。
+ */
+export const RULE_CONFIG_LIMITS = {
+  fields: 24,
+  keyLength: 32,
+  label: 40,
+  description: 200,
+  enumOptions: 8,
+  enumValueLength: 32,
+  enumLabel: 24,
+  integerSpan: 1000,
+} as const;
+
+const KEY_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+const ENUM_VALUE_PATTERN = /^[a-z0-9-]{1,32}$/;
+
+export type RuleConfigParseResult =
+  | { ok: true; spec: RuleConfigSpec }
+  | { ok: false; error: string };
+
+class RuleConfigCheckError extends Error {}
+
+function fail(path: string, message: string): never {
+  throw new RuleConfigCheckError(path ? `${path} ${message}` : message);
+}
+
+function chars(value: string): number {
+  return [...value].length;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readLabel(value: unknown, path: string, limit: number): string {
+  if (typeof value !== 'string') fail(path, '必须是字符串');
+  if (value.length === 0) fail(path, '不能为空');
+  if (chars(value) > limit) fail(path, `超过 ${limit} 字`);
+  return value;
+}
+
+function readDescription(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') fail(path, '必须是字符串');
+  if (chars(value) > RULE_CONFIG_LIMITS.description) fail(path, `超过 ${RULE_CONFIG_LIMITS.description} 字`);
+  return value;
+}
+
+function readField(value: unknown, path: string, seenKeys: Set<string>): RuleConfigField {
+  if (!isObject(value)) fail(path, '必须是对象');
+  if (typeof value.key !== 'string' || !KEY_PATTERN.test(value.key)) {
+    fail(`${path}.key`, '必须匹配 ^[a-z][a-z0-9-]{0,31}$');
+  }
+  if (seenKeys.has(value.key)) fail(`${path}.key`, '与前面的字段重复');
+  seenKeys.add(value.key);
+  const label = readLabel(value.label, `${path}.label`, RULE_CONFIG_LIMITS.label);
+  const description = readDescription(value.description, `${path}.description`);
+
+  if (value.type === 'boolean') {
+    if (typeof value.default !== 'boolean') fail(`${path}.default`, 'boolean 字段的默认值必须是布尔值');
+    return { key: value.key, label, type: 'boolean', default: value.default, ...(description === undefined ? {} : { description }) };
+  }
+
+  if (value.type === 'enum') {
+    if (!Array.isArray(value.options)) fail(`${path}.options`, '必须是数组');
+    if (value.options.length === 0) fail(`${path}.options`, '至少要有一个选项');
+    if (value.options.length > RULE_CONFIG_LIMITS.enumOptions) {
+      fail(`${path}.options`, `最多 ${RULE_CONFIG_LIMITS.enumOptions} 个选项`);
+    }
+    const seenValues = new Set<string>();
+    const options = value.options.map((option, index) => {
+      const optionPath = `${path}.options[${index}]`;
+      if (!isObject(option)) fail(optionPath, '必须是对象');
+      if (typeof option.value !== 'string' || !ENUM_VALUE_PATTERN.test(option.value)) {
+        fail(`${optionPath}.value`, '必须匹配 ^[a-z0-9-]{1,32}$');
+      }
+      if (seenValues.has(option.value)) fail(`${optionPath}.value`, '与前面的选项重复');
+      seenValues.add(option.value);
+      const optionLabel = readLabel(option.label, `${optionPath}.label`, RULE_CONFIG_LIMITS.enumLabel);
+      const optionDescription = readDescription(option.description, `${optionPath}.description`);
+      return { value: option.value, label: optionLabel, ...(optionDescription === undefined ? {} : { description: optionDescription }) };
+    });
+    if (typeof value.default !== 'string') fail(`${path}.default`, 'enum 字段的默认值必须是字符串');
+    if (!seenValues.has(value.default)) fail(`${path}.default`, '必须是 options 里的某个 value');
+    return { key: value.key, label, type: 'enum', default: value.default, options, ...(description === undefined ? {} : { description }) };
+  }
+
+  if (value.type === 'integer') {
+    if (typeof value.default !== 'number' || !Number.isSafeInteger(value.default)) {
+      fail(`${path}.default`, 'integer 字段的默认值必须是整数');
+    }
+    if (typeof value.min !== 'number' || !Number.isSafeInteger(value.min)) fail(`${path}.min`, '必须是整数');
+    if (typeof value.max !== 'number' || !Number.isSafeInteger(value.max)) fail(`${path}.max`, '必须是整数');
+    if (value.min > value.default) fail(`${path}.min`, '不能大于 default');
+    if (value.default > value.max) fail(`${path}.max`, '不能小于 default');
+    if (value.max - value.min > RULE_CONFIG_LIMITS.integerSpan) {
+      fail(`${path}.max`, `与 min 的跨度最多 ${RULE_CONFIG_LIMITS.integerSpan}`);
+    }
+    let step: number | undefined;
+    if (value.step !== undefined) {
+      if (typeof value.step !== 'number' || !Number.isSafeInteger(value.step) || value.step <= 0) {
+        fail(`${path}.step`, '必须是正整数');
+      }
+      step = value.step;
+    }
+    return {
+      key: value.key,
+      label,
+      type: 'integer',
+      default: value.default,
+      min: value.min,
+      max: value.max,
+      ...(step === undefined ? {} : { step }),
+      ...(description === undefined ? {} : { description }),
+    };
+  }
+
+  return fail(`${path}.type`, '只支持 boolean / enum / integer');
+}
+
+/** 校验并规范化规则表单声明；失败时返回一句可以直接显示给开发者的中文原因。 */
+export function parseRuleConfig(value: unknown): RuleConfigParseResult {
+  try {
+    if (!isObject(value)) fail('', '规则表单声明必须是对象');
+    if (!Array.isArray(value.fields)) fail('fields', '必须是数组');
+    if (value.fields.length === 0) fail('fields', '至少要有一项');
+    if (value.fields.length > RULE_CONFIG_LIMITS.fields) fail('fields', `最多 ${RULE_CONFIG_LIMITS.fields} 项`);
+    const seenKeys = new Set<string>();
+    const fields = value.fields.map((field, index) => readField(field, `fields[${index}]`, seenKeys));
+    return { ok: true, spec: { fields } };
+  } catch (error) {
+    if (error instanceof RuleConfigCheckError) return { ok: false, error: error.message };
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}