# @faiber/faiber-state-sdk 中文文档

规范地址：https://npmcn.com/package/%40faiber/faiber-state-sdk/

版本：2\.8\.0
npm 元数据更新时间：2026-11-14T09:45:10.476Z
中文译文更新时间：2026-11-14T08:58:51.211Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40faiber/faiber-state-sdk
原文对照：https://npmcn.com/package/%40faiber/faiber-state-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：240 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-28T11:24:29.409Z
- 最新版本发布：2026-11-14T09:45:10.275Z
- 近 30 天下载量：3994（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

被打入了状态世界,房间,WASM输出绑定,服务器授权游戏和票证认证的WebSockets.

## 安装

```sh
npm install @faiber/faiber-state-sdk
```

也可以使用：`pnpm add @faiber/faiber-state-sdk`、`yarn add @faiber/faiber-state-sdk`、`bun add @faiber/faiber-state-sdk`

## README

# @faiber/faiber-state-sdk (英语)

被打入了状态世界,房间,WASM输出绑定,服务器授权游戏和票证认证的WebSockets.

```bash
npm install @faiber/faiber-state-sdk
```

```ts
import { FaiberClient } from "@faiber/sdk-core";
import { StateApi, StateRealtimeClient } from "@faiber/faiber-state-sdk";

const state = new StateApi(new FaiberClient("state", {
  domains: { state: "https://state.example.com" },
  authMode: "cookie",
}));
const options = { headers: { "x-organization-id": organizationId }, signal };
const world = await state.createWorld({ name: "Arena", slug: "arena" }, options);
const room = await state.createRoom(world.data.data.id, { name: "Room 1", capacity: 8 }, options);
const ticket = (await state.join(room.data.data.id, userId, options)).data.data;
const realtime = new StateRealtimeClient(ticket);
realtime.on("patch", patch => applyServerPatch(patch));
realtime.on("pong", ({ tick }) => observeServerTick(tick));
await realtime.connect();
realtime.sendInput({ move_x: 5, move_z: -1 });
// On leaving the room:
realtime.close();
```

使用安全的 Http 只使用 cookie `withCredentials`,或配置 `FaiberClient` 带有 `TokenProvider` 提供纪念物 每一次HTTP呼叫都保留了全部Axios响应,选项,出错和取消信号. 抓取Axios错误进行验证(400/422),缺失记录(404),许可失败(401/403),冲突(409)和运输失败. 中止 `signal` 取消 HTTP 请求 。 完整的外观是: [`@faiber/faiber-ts-sdk`](https://www.npmjs.com/package/@faiber/faiber-ts-sdk)。 。 。 .

v1 世界/房间/WASM操作需要认证用户,非无 `x-organization-id` UUID,以及 `state:read`, (中文(简体) ), `state:write`,或 `state:execute` 每项行动都有记录。 国家管理、通配和管理员别名也被接受。 为另一个用户加入/援引需要管理机构。 管理游戏世界曝光 `managed: true` 并用409拒绝更新/删除。 所有 v1 和 v2 成功响应使用 `{ data }`。 。 。 .

浏览器在WebSocket上携带房间输入. 本地主机可以注射 `DatagramTransport` 用于JSON UDP输入网关;每个数据格包含有范围的房间票. `acked` UDP 发送返回确认 。 5分钟后房票过期,升级时会检查;再入场获得新玩家和出场券. `close()` 停止重试。 后端既可作为输入响应提供补丁,也可作为广播;消费者应当跟踪实体修改/顺序. `PredictionBuffer` 可以在权威更新后重放待定输入.

生成的 `state.operations` 覆盖所有挂载的HTTP API和WebSocket的升级. v2 游戏目录读取为公开; 受保护的游戏操作需要 `state:execute` 和适用的所有人/成员支票。 SQL游戏运行时间使用服务所配置的租户. 游戏操作摘要,节俭,会话页和事件页都命名了响应模型. 他们的查询键使用蛇 case( Name`page_size`, (中文(简体) ), `settlement_status`, (中文(简体) ), `user_id`;返回的页面元数据使用骆驼Case. 会话页面默认为25个条目,事件页面默认为50个,同时夹住大小为10–100个.

```ts
const created = await state.operations.gamesRoutesCreateSessionPost(gameId, {
  difficulty: "11-14", paid: false,
}, { signal });
const page = await state.operations.routesGameOperationSessionsGet({
  page: 1, page_size: 25, paid: false,
}, options);
const connection = await state.createMatchConnection(matchId, { signal });
const socket = await state.operations.connectMatchRealtime(connection.data.data, { signal });
```

游戏命令包括一个稳定的指令UUID和预期状态版本. Stale HTTP 游戏版本返回 409;匹配 WebSocket 命令拒绝使用 `command_result` 框架和一个新鲜的快照。 棋盘、挑战、衡量标准、事件有效载荷和游戏答案/动作JSON因注册的游戏/规则集而刻意不同,被记录为 `GamePayload`;组件/输入JSON因作者的世界计划而异.

`connectMatchRealtime` 验证所配置的服务来源,并在5秒内在初始Hello框架中发出30秒一使用接通票. 复通后取出新票. `MatchRealtimeClient` 仅在提供时自动重新连接 `refreshTicket`;消费的票不能被再使用。 服务器验证允许浏览器Origins. `routesRealtimeGet(ticket, { signal })` 对照配置的服务源打开 v1 房间复制。 Socket 操作返回连接的 WebSocket/客户端 .

`health()` 财务报告和审定财务报表 `operations.mainProcessHealthGet()` 读取静态 `/health` 广告`service`, (中文(简体) ), `status`, (中文(简体) ), `transports`, (中文(简体) ), `rulesets`, (中文(简体) ), `wasm`) (中文(简体) ). 这广告的WebSocket和 `kheradgah.v1`;它不验证数据库,游戏玩法,持久性,网关或WebSocket准备状态.

## 常见问题

### @faiber/faiber-state-sdk 是什么？

被打入了状态世界,房间,WASM输出绑定,服务器授权游戏和票证认证的WebSockets\.

### 如何安装 @faiber/faiber-state-sdk？

在项目目录运行 npm install @faiber/faiber-state-sdk，或使用 pnpm add / yarn add / bun add。

### @faiber/faiber-state-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @faiber/faiber-state-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faiber/faiber-state-sdk 可以商用吗？

@faiber/faiber-state-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @faiber/faiber-state-sdk 的下载量有多少？

根据 npm 官方下载统计，@faiber/faiber-state-sdk 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,994 次，日均约 133 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @faiber/faiber-state-sdk 还在维护吗？

最新版本 2\.8\.0 发布于 2026/11/14（今天）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2026/07/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。