@bgnut/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GomuLabs
+
+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

@@ -0,0 +1,57 @@
+# @bgnut/sdk
+
+桌游匠 BGNut 游戏运行时 SDK —— 让你的 HTML 桌游接入 [BGNut 平台](https://bgnut.gomulabs.com) 的好友联机对战。
+
+## 运行时怎么引
+
+**推荐直接引用平台托管版**（协议热修不需要你重新发版）：
+
+```html
+<script src="https://bgnut-play.gomulabs.com/sdk/v1.js"></script>
+```
+
+平台沙盒会在出站时自动把这个地址适配到当前环境（生产 / 预发 / 本地开发），你的游戏包跨环境零改动。npm 包主要提供 TypeScript 类型与构建集成：
+
+```bash
+npm install --save-dev @bgnut/sdk
+```
+
+## 快速开始
+
+```js
+const ctx = await BGNut.join();
+// ctx.seat        我的座位号（0 起）
+// ctx.members     房间成员（座位/昵称/头像）
+// ctx.config      房间配置（来自你的 bgnut.json manifest）
+// ctx.seed        本局随机种子（全员一致）
+// ctx.random()    确定性随机，取代 Math.random —— 所有客户端产出同一序列
+
+// 三步契约（确定性指令同步的关键）：
+// 1. 先按序应用历史指令（断线重连/中途加入时恢复现场）
+ctx.replay.forEach(apply);
+// 2. 监听后续指令 —— 包括你自己发出的（服务器全序回显）
+ctx.onCommand(apply);
+// 3. 操作只 send，不直接改本地状态；收到广播后统一在 apply 里改
+button.onclick = () => ctx.send({ type: 'move', x: 1 });
+
+// 结束时上报胜负
+ctx.finish(winnerSeat);
+```
+
+联机模型：服务器不理解游戏规则，只保证「同成员、同配置、同种子、全序指令流」四件事；各客户端确定性演进出相同状态。所以请遵守：随机全部走 `ctx.random()`，状态变更全部由指令驱动。
+
+## 单机 mock 模式
+
+没有父窗口（本地直接打开、平台单机试玩）时，`BGNut.join()` 自动进入单机 mock：你是座位 0，`send` 的指令原样回显。游戏无需为单机写任何分支。
+
+## 配套工具
+
+用 [`@bgnut/cli`](https://www.npmjs.com/package/@bgnut/cli) 完成脚手架、本地双人模拟与发布：
+
+```bash
+npx @bgnut/cli init
+```
+
+## License
+
+MIT © GomuLabs

package/index.d.ts

@@ -0,0 +1,45 @@
+// @bgnut/sdk 类型定义
+export interface BGNutMember {
+  seat: number;
+  name: string;
+  handle: string | null;
+  avatarUrl: string | null;
+  online: boolean;
+}
+
+export interface BGNutCommand {
+  seq: number;
+  seat: number;
+  data: unknown;
+}
+
+export interface BGNutContext {
+  seat: number;
+  members: BGNutMember[];
+  config: Record<string, unknown>;
+  maxPlayers: number;
+  seed: number;
+  /** 开局历史指令：初始化时先按序应用，再监听 onCommand */
+  replay: BGNutCommand[];
+  /** 确定性随机（种子驱动，所有客户端同序列），取代 Math.random */
+  random(): number;
+  send(data: unknown): void;
+  finish(winner: number | null): void;
+  onCommand(cb: (cmd: BGNutCommand) => void): () => void;
+  onMembers(cb: (members: BGNutMember[]) => void): () => void;
+  onPhase(cb: (p: { phase: 'playing' | 'ended'; winner: number | null }) => void): () => void;
+}
+
+export interface BGNutSdk {
+  version: string;
+  join(): Promise<BGNutContext>;
+}
+
+declare const BGNut: BGNutSdk;
+export default BGNut;
+
+declare global {
+  interface Window {
+    BGNut: BGNutSdk;
+  }
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@bgnut/sdk",
+  "version": "1.0.0",
+  "description": "桌游匠 BGNut 游戏运行时 SDK：联机桥、确定性随机、单机 mock。运行时推荐引用托管版 https://bgnut-play.gomulabs.com/sdk/v1.js",
+  "main": "sdk.js",
+  "types": "index.d.ts",
+  "files": ["sdk.js", "index.d.ts", "README.md"],
+  "keywords": ["bgnut", "boardgame", "multiplayer", "sdk", "桌游"],
+  "homepage": "https://bgnut.gomulabs.com",
+  "author": "GomuLabs",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": { "access": "public" }
+}

package/sdk.js

@@ -0,0 +1,153 @@
+/*!
+ * BGNut SDK v1 —— 桌游匠联机运行时桥（ADR-0007 指令中继模型）
+ * 唯一事实来源：packages/sdk/sdk.js
+ * 托管副本：bgnut-site/public/sdk/v1.js（node scripts/sync-sdk.mjs 同步，禁止直接改副本）
+ *
+ * 游戏三步合约：
+ *   1. 引入本 SDK；
+ *   2. const ctx = await BGNut.join() 后再初始化（用 ctx.random() 取代 Math.random）；
+ *   3. 本地操作一律 ctx.send(指令)，在 ctx.onCommand 里统一应用（含自己的回显）。
+ *
+ * 无宿主（直接打开页面 / 审核初玩）时自动进入单机 mock 模式。
+ */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.BGNut = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  // 确定性 PRNG（mulberry32）——同种子必同序列
+  function mulberry32(seed) {
+    var a = seed >>> 0;
+    return function () {
+      a |= 0;
+      a = (a + 0x6d2b79f5) | 0;
+      var t = Math.imul(a ^ (a >>> 15), 1 | a);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  function makeEmitter() {
+    var handlers = [];
+    return {
+      on: function (fn) {
+        handlers.push(fn);
+        return function () {
+          var i = handlers.indexOf(fn);
+          if (i >= 0) handlers.splice(i, 1);
+        };
+      },
+      emit: function (payload) {
+        for (var i = 0; i < handlers.length; i++) {
+          try {
+            handlers[i](payload);
+          } catch (e) {
+            console.error('[BGNut] 回调异常:', e);
+          }
+        }
+      },
+    };
+  }
+
+  function buildCtx(init, post) {
+    var commandEv = makeEmitter();
+    var membersEv = makeEmitter();
+    var phaseEv = makeEmitter();
+    var ctx = {
+      /** 我的座位号（0 起） */
+      seat: init.seat,
+      /** 成员列表 [{seat,name,handle,avatarUrl,online}] */
+      members: init.members,
+      /** 房间配置（bgnut.json manifest.config，所有客户端一致） */
+      config: init.config || {},
+      maxPlayers: init.maxPlayers,
+      /** 共享随机种子 */
+      seed: init.seed,
+      /** 开局历史指令（重连/中途加载时先按序应用它，再监听 onCommand） */
+      replay: init.replay || [],
+      /** 确定性随机（种子驱动，所有客户端同序列） */
+      random: mulberry32(init.seed),
+      /** 发送指令：服务器定序后广播给所有人（含自己） */
+      send: function (data) {
+        post({ bgnut: 'command', data: data });
+      },
+      /** 报告对局结束（首个报告生效） */
+      finish: function (winner) {
+        post({ bgnut: 'finish', winner: typeof winner === 'number' ? winner : null });
+      },
+      /** 新指令（含自己的回显）：cb({seq, seat, data}) */
+      onCommand: commandEv.on,
+      /** 成员变化（上线/掉线/加入）：cb(members) */
+      onMembers: membersEv.on,
+      /** 阶段变化：cb({phase:'playing'|'ended', winner}) */
+      onPhase: phaseEv.on,
+      _dispatch: { command: commandEv.emit, members: membersEv.emit, phase: phaseEv.emit },
+    };
+    return ctx;
+  }
+
+  // ---------- 桥模式（在主站对局页 iframe 中） ----------
+  function joinViaBridge() {
+    return new Promise(function (resolve) {
+      var ctx = null;
+      window.addEventListener('message', function (ev) {
+        var m = ev.data;
+        if (!m || typeof m !== 'object' || !m.bgnut) return;
+        if (m.bgnut === 'init' && !ctx) {
+          ctx = buildCtx(m, function (out) {
+            window.parent.postMessage(out, '*');
+          });
+          resolve(ctx);
+        } else if (ctx) {
+          if (m.bgnut === 'command') ctx._dispatch.command({ seq: m.seq, seat: m.seat, data: m.data });
+          else if (m.bgnut === 'members') {
+            ctx.members = m.members;
+            ctx._dispatch.members(m.members);
+          } else if (m.bgnut === 'phase') ctx._dispatch.phase({ phase: m.phase, winner: m.winner });
+        }
+      });
+      window.parent.postMessage({ bgnut: 'ready' }, '*');
+    });
+  }
+
+  // ---------- 单机 mock 模式（无宿主：本地直开 / 审核初玩 / bgnut dev 单窗） ----------
+  function joinMock() {
+    var seq = 0;
+    var ctx = buildCtx(
+      {
+        seat: 0,
+        members: [{ seat: 0, name: '本地玩家', handle: null, avatarUrl: null, online: true }],
+        config: {},
+        maxPlayers: 1,
+        seed: (Date.now() % 2147483647) | 0,
+        replay: [],
+      },
+      function (out) {
+        if (out.bgnut === 'command') {
+          seq += 1;
+          var cmd = { seq: seq, seat: 0, data: out.data };
+          setTimeout(function () {
+            ctx._dispatch.command(cmd);
+          }, 0);
+        } else if (out.bgnut === 'finish') {
+          setTimeout(function () {
+            ctx._dispatch.phase({ phase: 'ended', winner: out.winner });
+          }, 0);
+        }
+      },
+    );
+    console.info('[BGNut] 无宿主环境，进入单机 mock 模式');
+    return Promise.resolve(ctx);
+  }
+
+  var joined = null;
+  return {
+    version: '1.0.0',
+    /** 加入对局：返回 ctx。桥模式等待宿主 init；无宿主自动单机 mock。 */
+    join: function () {
+      if (!joined) joined = window.parent !== window ? joinViaBridge() : joinMock();
+      return joined;
+    },
+  };
+});