@lizardon386/game-sdk 0.0.0-stage → 0.3.0

package/dist/kit/shared.d.ts

@@ -0,0 +1,26 @@
+/** 游戏事件流的一条公开记录：玩法文本由游戏填，平台只搬运。 */
+export interface FeedEntry {
+    seq: number;
+    at: number;
+    type: string;
+    text: string;
+    actor?: string;
+    target?: string;
+    data?: Record<string, unknown>;
+}
+/** 事件对谁可见；team 需要 FeedLog 提供 seatTeams。 */
+export type FeedVisibility = 'all' | {
+    seatId: string;
+} | {
+    team: string | number;
+};
+export declare const FEED_EVENT = "bp.feed";
+export declare class FeedError extends Error {
+    constructor(message: string);
+}
+export interface SeatLike {
+    seatId: string;
+    slot?: number;
+    team?: string | number | null;
+}
+//# sourceMappingURL=shared.d.ts.map

package/dist/kit/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAEpF,eAAO,MAAM,UAAU,YAAY,CAAC;AAEpC,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC/B"}

package/dist/kit/shared.js

@@ -0,0 +1,8 @@
+export const FEED_EVENT = 'bp.feed';
+export class FeedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FeedError';
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/kit/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AAEpC,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/node/pack.d.ts

@@ -0,0 +1,2 @@
+export * from '@lizardon386/pack-format';
+//# sourceMappingURL=pack.d.ts.map

package/dist/node/pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/node/pack.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/dist/node/pack.js

@@ -0,0 +1,2 @@
+export * from '@lizardon386/pack-format';
+//# sourceMappingURL=pack.js.map

package/dist/node/pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../src/node/pack.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@lizardon386/game-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "3178 游戏接入 SDK：游戏 ABI、客户端契约、单文件包和 game-kit",
+  "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/game-sdk"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "keywords": [
+    "3178",
+    "game-platform",
+    "game-sdk",
+    "game-kit"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/contract/client.d.ts",
+      "default": "./dist/contract/client.js"
+    },
+    "./node": {
+      "types": "./dist/node/pack.d.ts",
+      "default": "./dist/node/pack.js"
+    },
+    "./kit": {
+      "types": "./dist/kit/client/index.d.ts",
+      "default": "./dist/kit/client/index.js"
+    },
+    "./kit/server": {
+      "types": "./dist/kit/server/index.d.ts",
+      "default": "./dist/kit/server/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@lizardon386/core-abi": "^0.3.0",
+    "@lizardon386/pack-format": "^0.3.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/contract/client.ts

@@ -0,0 +1 @@
+export type { GameActions, GameClientContract } from '@lizardon386/core-abi';

package/src/index.ts

@@ -0,0 +1,45 @@
+export type {
+  Effect,
+  GameAction,
+  GameAsset,
+  GameContext,
+  GameInstance,
+  GameManifest,
+  GameMode,
+  GameModule,
+  GameReferenceDocument,
+  GameReferenceGroup,
+  GameReferenceImage,
+  GameReferenceItem,
+  GameReferenceParseResult,
+  GameReferenceSpec,
+  GameSeatInfo,
+  GameUiOptions,
+  NoticeCode,
+  Outcome,
+  PlatformCode,
+  Reject,
+  RoomPhase,
+  RuleConfigField,
+  RuleConfigParseResult,
+  RuleConfigSpec,
+  SeatRole,
+  SeatView,
+  ViewerId,
+} from '@lizardon386/core-abi';
+export {
+  API_VERSION,
+  DEFAULT_MODE,
+  GAME_MODES,
+  GAME_REFERENCE_LIMITS,
+  RULE_CONFIG_LIMITS,
+  SUPPORTED_API_VERSIONS,
+  SUPPORTED_MODES,
+  isReject,
+  isValidGameReferenceEntry,
+  isValidPackRelativePath,
+  parseGameReference,
+  parseRuleConfig,
+  reject,
+  stableDigest,
+} from '@lizardon386/core-abi';

package/src/kit/client/chat.ts

@@ -0,0 +1,199 @@
+export interface ChatLine {
+  seatId: string;
+  name: string;
+  text: string;
+  at: number;
+  kind: 'say' | 'system';
+}
+
+export interface ChatPanelOptions {
+  mount?: HTMLElement;
+  max?: number;
+  maxText?: number;
+  showSystem?: boolean;
+  placeholder?: string;
+  sendLabel?: string;
+  /** 覆盖默认发送方式；不填时在 iframe 里 parent.postMessage。 */
+  onSend?: (text: string) => void;
+  /** 新到的消息回调；初始历史不会触发。 */
+  onLine?: (line: ChatLine) => void;
+  /** 是否监听 window 的 bp:chat-history / bp:chat；有 mount 时默认开。 */
+  listen?: boolean;
+}
+
+const MAX_CHAT_TEXT = 300;
+
+function clamp(value: number | undefined, min: number, max: number, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+export function chatText(value: string): string | null {
+  const text = value.trim();
+  if (text.length < 1 || text.length > MAX_CHAT_TEXT) return null;
+  return text;
+}
+
+export function chatLineKey(line: ChatLine): string {
+  return `${line.at}|${line.seatId}|${line.kind}|${line.text}`;
+}
+
+export function normalizeChatLine(value: unknown): ChatLine | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.seatId !== 'string' || typeof raw.name !== 'string') return null;
+  if (typeof raw.text !== 'string' || typeof raw.at !== 'number' || !Number.isFinite(raw.at)) return null;
+  if (raw.kind !== 'say' && raw.kind !== 'system') return null;
+  const text = raw.text.trim();
+  if (!text || text.length > MAX_CHAT_TEXT) return null;
+  return { seatId: raw.seatId, name: raw.name, text, at: raw.at, kind: raw.kind };
+}
+
+export function mergeChatLines(current: readonly ChatLine[], incoming: readonly ChatLine[], max: number): ChatLine[] {
+  const byKey = new Map<string, ChatLine>();
+  for (const line of current) byKey.set(chatLineKey(line), line);
+  for (const line of incoming) byKey.set(chatLineKey(line), line);
+  return [...byKey.values()].sort((a, b) => a.at - b.at).slice(-Math.max(1, max));
+}
+
+/** 房间聊天面板：历史以平台推送的 bp:chat-history 为准，发送只发纯文本。 */
+export class ChatPanel {
+  private readonly options: ChatPanelOptions;
+  private readonly max: number;
+  private readonly maxText: number;
+  private readonly root: HTMLDivElement | null = null;
+  private readonly log: HTMLOListElement | null = null;
+  private readonly input: HTMLInputElement | null = null;
+  private readonly form: HTMLFormElement | null = null;
+  private readonly onChatHistory: ((event: Event) => void) | null = null;
+  private readonly onChatLine: ((event: Event) => void) | null = null;
+  private lines: ChatLine[] = [];
+
+  constructor(options: ChatPanelOptions = {}) {
+    this.options = options;
+    this.max = clamp(options.max, 1, 500, 200);
+    this.maxText = clamp(options.maxText, 1, MAX_CHAT_TEXT, MAX_CHAT_TEXT);
+    if (options.mount) {
+      const doc = options.mount.ownerDocument;
+      const root = doc.createElement('div');
+      root.className = 'bp-chat';
+      root.style.cssText = 'display:flex;flex-direction:column;min-height:0;font:13px/1.5 system-ui, "Microsoft YaHei UI", "Microsoft YaHei", sans-serif';
+      const log = doc.createElement('ol');
+      log.className = 'bp-chat-log';
+      log.setAttribute('role', 'log');
+      log.setAttribute('aria-live', 'polite');
+      log.style.cssText = 'margin:0;padding:4px 8px;list-style:none;overflow-y:auto;flex:1 1 auto;min-height:120px;max-height:260px';
+      const form = doc.createElement('form');
+      form.className = 'bp-chat-form';
+      form.style.cssText = 'display:flex;gap:6px;padding:6px 0 0';
+      const input = doc.createElement('input');
+      input.className = 'bp-chat-input';
+      input.type = 'text';
+      input.maxLength = MAX_CHAT_TEXT;
+      input.autocomplete = 'off';
+      input.placeholder = options.placeholder ?? '说点什么';
+      input.style.cssText = 'flex:1 1 auto;min-width:0;padding:4px 6px';
+      const button = doc.createElement('button');
+      button.className = 'bp-chat-send';
+      button.type = 'submit';
+      button.textContent = options.sendLabel ?? '发送';
+      button.style.cssText = 'flex:none;padding:4px 10px';
+      form.append(input, button);
+      root.append(log, form);
+      options.mount.replaceChildren(root);
+      this.root = root;
+      this.log = log;
+      this.input = input;
+      this.form = form;
+      form.addEventListener('submit', (event) => {
+        event.preventDefault();
+        this.send();
+      });
+    }
+
+    if (options.listen ?? Boolean(options.mount)) {
+      if (typeof window !== 'undefined') {
+        this.onChatHistory = (event: Event) => {
+          const lines = (event as CustomEvent).detail;
+          if (Array.isArray(lines)) this.setLines(lines as ChatLine[]);
+        };
+        this.onChatLine = (event: Event) => {
+          this.append((event as CustomEvent).detail as ChatLine);
+        };
+        window.addEventListener('bp:chat-history', this.onChatHistory);
+        window.addEventListener('bp:chat', this.onChatLine);
+      }
+    }
+  }
+
+  setLines(lines: readonly ChatLine[]): void {
+    const normalized = lines.map(normalizeChatLine).filter((line): line is ChatLine => line !== null);
+    this.lines = mergeChatLines([], normalized, this.max);
+    this.render();
+  }
+
+  append(line: ChatLine): void {
+    const normalized = normalizeChatLine(line);
+    if (!normalized) return;
+    if (this.lines.some((item) => chatLineKey(item) === chatLineKey(normalized))) return;
+    this.lines = mergeChatLines(this.lines, [normalized], this.max);
+    this.render();
+    this.options.onLine?.(normalized);
+  }
+
+  send(): void {
+    const input = this.input;
+    if (!input) return;
+    const text = chatText(input.value);
+    if (!text) return;
+    if (this.options.onSend) {
+      this.options.onSend(text);
+    } else if (typeof parent !== 'undefined' && parent !== window) {
+      parent.postMessage({ type: 'chat', text }, '*');
+    }
+    input.value = '';
+  }
+
+  clear(): void {
+    this.lines = [];
+    this.render();
+  }
+
+  destroy(): void {
+    if (typeof window !== 'undefined') {
+      if (this.onChatHistory) window.removeEventListener('bp:chat-history', this.onChatHistory);
+      if (this.onChatLine) window.removeEventListener('bp:chat', this.onChatLine);
+    }
+    this.options.mount?.replaceChildren();
+    this.lines = [];
+  }
+
+  private render(): void {
+    const log = this.log;
+    if (!log) return;
+    const nearBottom = log.scrollHeight - log.scrollTop - log.clientHeight < 8;
+    const allowed = this.options.showSystem === false ? this.lines.filter((line) => line.kind !== 'system') : this.lines;
+    log.replaceChildren();
+    for (const line of allowed) {
+      const item = log.ownerDocument.createElement('li');
+      item.className = `bp-chat-line bp-chat-${line.kind}`;
+      item.dataset.seatId = line.seatId;
+      item.style.cssText = 'padding:1px 0;overflow-wrap:anywhere';
+      if (line.kind === 'system') {
+        item.style.opacity = '0.65';
+        item.textContent = line.text.length > this.maxText ? `${line.text.slice(0, this.maxText)}…` : line.text;
+      } else {
+        const name = log.ownerDocument.createElement('span');
+        name.className = 'bp-chat-name';
+        name.textContent = `${line.name}：`;
+        name.style.cssText = 'font-weight:600;margin-right:2px';
+        const text = log.ownerDocument.createElement('span');
+        text.className = 'bp-chat-text';
+        text.textContent = line.text.length > this.maxText ? `${line.text.slice(0, this.maxText)}…` : line.text;
+        item.append(name, text);
+      }
+      log.append(item);
+    }
+    if (nearBottom) log.scrollTop = log.scrollHeight;
+  }
+}

package/src/kit/client/feed.ts

@@ -0,0 +1,170 @@
+import { FEED_EVENT, type FeedEntry } from '../shared.js';
+
+export interface FeedEvent {
+  name: string;
+  payload?: unknown;
+}
+
+export interface FeedPanelOptions {
+  mount?: HTMLElement;
+  max?: number;
+  /** 只显示这些 type；不填表示全部。 */
+  types?: readonly string[];
+  maxText?: number;
+  emptyText?: string;
+  timeFormat?: (at: number) => string;
+  /** 给 actor 上色；不填则用默认文本色。 */
+  colorOf?: (seatId: string) => string | null;
+  /** 只给新到的事件回调；初始历史不会触发。 */
+  onEntry?: (entry: FeedEntry) => void;
+}
+
+function clamp(value: number | undefined, min: number, max: number, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+export function formatFeedTime(at: number): string {
+  const date = new Date(at);
+  const pad = (value: number): string => String(value).padStart(2, '0');
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+export function normalizeFeedEntry(value: unknown): FeedEntry | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  if (!Number.isSafeInteger(raw.seq) || (raw.seq as number) < 1) return null;
+  if (typeof raw.at !== 'number' || !Number.isFinite(raw.at)) return null;
+  if (typeof raw.type !== 'string' || raw.type.trim().length === 0) return null;
+  if (typeof raw.text !== 'string' || raw.text.trim().length === 0) return null;
+  if (raw.actor !== undefined && typeof raw.actor !== 'string') return null;
+  if (raw.target !== undefined && typeof raw.target !== 'string') return null;
+  if (raw.data !== undefined && (typeof raw.data !== 'object' || raw.data === null || Array.isArray(raw.data))) return null;
+  const text = raw.text.trim();
+  if (text.length === 0) return null;
+  const entry: FeedEntry = {
+    seq: raw.seq as number,
+    at: raw.at,
+    type: raw.type.trim(),
+    text,
+  };
+  if (raw.actor !== undefined) entry.actor = raw.actor;
+  if (raw.target !== undefined) entry.target = raw.target;
+  if (raw.data !== undefined) entry.data = raw.data as Record<string, unknown>;
+  return entry;
+}
+
+/** 按 seq 合并，保留最近的 max 条；重复帧不会重复显示。 */
+export function mergeFeedEntries(
+  current: readonly FeedEntry[],
+  incoming: readonly FeedEntry[],
+  max: number,
+): FeedEntry[] {
+  const bySeq = new Map<number, FeedEntry>();
+  for (const entry of current) bySeq.set(entry.seq, entry);
+  for (const entry of incoming) bySeq.set(entry.seq, entry);
+  return [...bySeq.values()].sort((a, b) => a.seq - b.seq).slice(-Math.max(1, max));
+}
+
+/** 渲染无关的事件流面板；不挂 mount 时只跑回调和状态。 */
+export class FeedPanel {
+  private readonly options: FeedPanelOptions;
+  private readonly max: number;
+  private readonly maxText: number;
+  private readonly list: HTMLOListElement | null = null;
+  private entries: FeedEntry[] = [];
+
+  constructor(options: FeedPanelOptions = {}) {
+    this.options = options;
+    this.max = clamp(options.max, 1, 500, 100);
+    this.maxText = clamp(options.maxText, 1, 2_000, 240);
+    if (options.mount) {
+      const list = options.mount.ownerDocument.createElement('ol');
+      list.className = 'bp-feed';
+      list.setAttribute('role', 'log');
+      list.setAttribute('aria-live', 'polite');
+      list.setAttribute('aria-relevant', 'additions');
+      list.style.cssText = [
+        'margin:0',
+        'padding:2px 8px',
+        'max-height:240px',
+        'overflow-y:auto',
+        'list-style:none',
+        'font:12px/1.6 system-ui, "Microsoft YaHei UI", "Microsoft YaHei", sans-serif',
+      ].join(';');
+      options.mount.replaceChildren(list);
+      this.list = list;
+    }
+  }
+
+  setEntries(entries: readonly FeedEntry[]): void {
+    const normalized = entries.map(normalizeFeedEntry).filter((entry): entry is FeedEntry => entry !== null);
+    this.entries = mergeFeedEntries([], normalized, this.max);
+    this.render();
+  }
+
+  append(entry: FeedEntry): void {
+    const normalized = normalizeFeedEntry(entry);
+    if (!normalized || this.entries.some((item) => item.seq === normalized.seq)) return;
+    this.entries = mergeFeedEntries(this.entries, [normalized], this.max);
+    this.render();
+    this.options.onEntry?.(normalized);
+  }
+
+  /** 直接接 GameClient.onEvent；不是 bp.feed 时返回 false。 */
+  handleEvent(event: FeedEvent): boolean {
+    if (event.name !== FEED_EVENT) return false;
+    const payloads = Array.isArray(event.payload) ? event.payload : [event.payload];
+    for (const payload of payloads) this.append(payload as FeedEntry);
+    return true;
+  }
+
+  clear(): void {
+    this.entries = [];
+    this.render();
+  }
+
+  destroy(): void {
+    this.options.mount?.replaceChildren();
+    this.entries = [];
+  }
+
+  private render(): void {
+    const list = this.list;
+    if (!list) return;
+    const nearBottom = list.scrollHeight - list.scrollTop - list.clientHeight < 8;
+    const allowed = this.options.types ? new Set(this.options.types) : null;
+    const visible = this.entries.filter((entry) => !allowed || allowed.has(entry.type));
+    list.replaceChildren();
+    if (visible.length === 0) {
+      const empty = list.ownerDocument.createElement('li');
+      empty.className = 'bp-feed-empty';
+      empty.textContent = this.options.emptyText ?? '暂无事件';
+      empty.style.cssText = 'padding:4px 0;opacity:.55';
+      list.append(empty);
+      return;
+    }
+    for (const entry of visible) {
+      const item = list.ownerDocument.createElement('li');
+      item.className = 'bp-feed-item';
+      item.dataset.type = entry.type;
+      item.style.cssText = 'display:flex;gap:8px;padding:1px 0;align-items:baseline';
+      const time = list.ownerDocument.createElement('time');
+      time.className = 'bp-feed-time';
+      time.dateTime = new Date(entry.at).toISOString();
+      time.textContent = (this.options.timeFormat ?? formatFeedTime)(entry.at);
+      time.style.cssText = 'flex:none;opacity:.55;font-variant-numeric:tabular-nums';
+      const text = list.ownerDocument.createElement('span');
+      text.className = 'bp-feed-text';
+      text.textContent = entry.text.length > this.maxText ? `${entry.text.slice(0, this.maxText)}…` : entry.text;
+      text.style.cssText = 'min-width:0;overflow-wrap:anywhere';
+      if (entry.actor && this.options.colorOf) {
+        const color = this.options.colorOf(entry.actor);
+        if (color) text.style.color = color;
+      }
+      item.append(time, text);
+      list.append(item);
+    }
+    if (nearBottom) list.scrollTop = list.scrollHeight;
+  }
+}

package/src/kit/client/index.ts

@@ -0,0 +1,33 @@
+export {
+  FeedPanel,
+  formatFeedTime,
+  mergeFeedEntries,
+  normalizeFeedEntry,
+  type FeedEvent,
+  type FeedPanelOptions,
+} from './feed.js';
+export {
+  ChatPanel,
+  chatLineKey,
+  chatText,
+  mergeChatLines,
+  normalizeChatLine,
+  type ChatLine,
+  type ChatPanelOptions,
+} from './chat.js';
+export {
+  ScoreboardPanel,
+  buildScoreboardRows,
+  connectionLabel,
+  formatColumnValue,
+  normalizeScoreboardRows,
+  resolveColumnValue,
+  sortScoreboardRows,
+  type ScoreboardColumn,
+  type ScoreboardPanelOptions,
+  type ScoreboardRoom,
+  type ScoreboardRow,
+  type ScoreboardSort,
+} from './scoreboard.js';
+export { seatColor, type SeatColor } from '../palette.js';
+export { FEED_EVENT, FeedError, type FeedEntry, type FeedVisibility, type SeatLike } from '../shared.js';