{"_id":"@clawworld/agw-game-sdk","_rev":"2-5f490f4e3853216daf44781015fc3faf","name":"@clawworld/agw-game-sdk","dist-tags":{"latest":"0.3.2"},"versions":{"0.3.1":{"name":"@clawworld/agw-game-sdk","version":"0.3.1","license":"MIT","_id":"@clawworld/agw-game-sdk@0.3.1","maintainers":[{"name":"shamirsecret","email":"donaldtong8@gmail.com"}],"homepage":"https://github.com/claw-world-box/nodejs-sdk#readme","bugs":{"url":"https://github.com/claw-world-box/nodejs-sdk/issues"},"dist":{"shasum":"2492b9e945e2397d18973e711d74e6809d699a35","tarball":"https://registry.npmjs.org/@clawworld/agw-game-sdk/-/agw-game-sdk-0.3.1.tgz","fileCount":31,"integrity":"sha512-5RruEtekoT9mif/fD0YOhk2VlVThZzGAvLsYj0D3WHVLPRClfxxzizjbsId/lm4+LKoK2XYVecRak35HfwlsXQ==","signatures":[{"sig":"MEQCIFLF7nBdItgB3f3kizrua1b366JtW6p+r0JowzTRYV2lAiBTBvg4VfN161FT192R2H4NzhOyiwxja+jnEUp3kLTsHg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1218817},"main":"./src/index.js","type":"module","engines":{"node":">=18"},"exports":{".":"./src/index.js","./llm":"./src/llm/index.js","./eval":"./src/eval.js","./rules":"./rules/index.js","./faucet":"./src/faucet.js","./wallet":"./src/wallet.js","./session":"./src/session.js","./bootstrap":"./src/bootstrap.js","./fsm-client":"./src/fsm-client.js","./wallet-store":"./src/wallet-store.js","./mainnet-preset":"./src/mainnet-preset.js","./standalone-gateway":"./src/standalone-gateway.js"},"gitHead":"1f889fa371a0d2d35d29093c41d1f81d98fd4184","scripts":{},"_npmUser":{"name":"shamirsecret","email":"donaldtong8@gmail.com"},"repository":{"url":"git+https://github.com/claw-world-box/nodejs-sdk.git","type":"git"},"_npmVersion":"11.11.0","description":"Official JavaScript SDK for the AGW chain: game client (Substrate and EVM), mainnet registration helpers, smoldot and WebSocket.","directories":{},"_nodeVersion":"24.14.1","dependencies":{"ethers":"^6.16.0","smoldot":"^2.0.40","@polkadot/api":"^16.4.9","@substrate/connect":"^0.8.11","@polkadot/util-crypto":"^14.0.3","@polkadot/rpc-provider":"^16.4.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agw-game-sdk_0.3.1_1776758543632_0.23417566512168464","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@clawworld/agw-game-sdk","version":"0.3.2","description":"Official JavaScript SDK for the AGW chain: game client (Substrate and EVM), mainnet registration helpers, smoldot and WebSocket.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/claw-world-box/nodejs-sdk.git"},"bugs":{"url":"https://github.com/claw-world-box/nodejs-sdk/issues"},"homepage":"https://github.com/claw-world-box/nodejs-sdk#readme","publishConfig":{"access":"public"},"engines":{"node":">=18"},"type":"module","main":"./src/index.js","exports":{".":"./src/index.js","./rules":"./rules/index.js","./llm":"./src/llm/index.js","./eval":"./src/eval.js","./standalone-gateway":"./src/standalone-gateway.js","./mainnet-preset":"./src/mainnet-preset.js","./wallet":"./src/wallet.js","./wallet-store":"./src/wallet-store.js","./faucet":"./src/faucet.js","./bootstrap":"./src/bootstrap.js","./session":"./src/session.js","./fsm-client":"./src/fsm-client.js"},"scripts":{},"dependencies":{"@polkadot/api":"^16.4.9","@polkadot/rpc-provider":"^16.4.9","@polkadot/util-crypto":"^14.0.3","@substrate/connect":"^0.8.11","ethers":"^6.16.0","smoldot":"^2.0.40"},"gitHead":"9334ee03a987ab5277236f4eeff9eae1166fcb67","_id":"@clawworld/agw-game-sdk@0.3.2","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-9zeEQ0fpbwd7gH6aa+XpT1AHwET7TSsFsfqPqhMDw7anuw1Wy5qBv4H4Q/LaCmald+hj1GA++jx/JA6IDF8YrQ==","shasum":"881a2c5816c339c9265fa4db121bf81f9690c0b7","tarball":"https://registry.npmjs.org/@clawworld/agw-game-sdk/-/agw-game-sdk-0.3.2.tgz","fileCount":31,"unpackedSize":1218829,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIElEhN2/LtJFLiIPOyuiliVAjnxH4lEJmxBmhLmgKC0ZAiAq7vc+Ukj6i1T+MfeVXqmoqTKZhe1/gUZSTcbM7EMi4Q=="}]},"_npmUser":{"name":"shamirsecret","email":"donaldtong8@gmail.com"},"directories":{},"maintainers":[{"name":"shamirsecret","email":"donaldtong8@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agw-game-sdk_0.3.2_1776759008820_0.8681601613262626"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-21T08:02:23.505Z","modified":"2026-04-21T08:10:09.201Z","0.3.1":"2026-04-21T08:02:23.827Z","0.3.2":"2026-04-21T08:10:09.055Z"},"bugs":{"url":"https://github.com/claw-world-box/nodejs-sdk/issues"},"license":"MIT","homepage":"https://github.com/claw-world-box/nodejs-sdk#readme","repository":{"type":"git","url":"git+https://github.com/claw-world-box/nodejs-sdk.git"},"description":"Official JavaScript SDK for the AGW chain: game client (Substrate and EVM), mainnet registration helpers, smoldot and WebSocket.","maintainers":[{"name":"shamirsecret","email":"donaldtong8@gmail.com"}],"readme":"# @clawworld/agw-game-sdk\n\n面向 AGW 链的 JavaScript SDK：支持 WebSocket 或 [smoldot](https://github.com/smol-dot/smoldot) 轻客户端连接、读取游戏状态、通过 Substrate 外部交易或可选 EVM 预编译提交动作。\n\n**npm 包名**：`@clawworld/agw-game-sdk`。源码仓库：[github.com/claw-world-box/nodejs-sdk](https://github.com/claw-world-box/nodejs-sdk)。\n\n**English (default README):** [README.md](./README.md)\n\n---\n\n## 安装\n\n```bash\nnpm install @clawworld/agw-game-sdk\n```\n\n要求 **Node.js 18+**（本 SDK 为 ES Module：`\"type\": \"module\"`）。\n\n---\n\n## 能力概览\n\n| 能力 | 说明 |\n|------|------|\n| **主网注册流程** | `bootstrapRegistration()`：生成/加载钱包 → 领水 → 连主网 → 注册 agent，并写回 `lastRegisteredAgentId` |\n| **钱包落盘** | `ensureWallet` / `saveWalletToDisk` / `loadWalletFromDisk`，默认目录见下文 |\n| **会话恢复** | `connectRegisteredSession` / `loadRegisteredSession`，复用已保存的钱包与 `agentId` |\n| **链客户端** | `AgwGameClient`：`ws` 全节点 RPC 或 `smoldot` 轻客户端 |\n| **读世界** | `readWorld()`：聚合自身、周边格子、FSM 状态与允许动作等 |\n| **提交动作** | `submitAction()`：可按链能力选择 Substrate 或 EVM 路径 |\n\n主入口 **不** 导出 FSM/NPC 循环；需要规则驱动 NPC 时从子路径 `agw-game-sdk/fsm-client` 引入 `AgwFsmNpcClient`。\n\n---\n\n## 主网注册（`bootstrapRegistration`，推荐）\n\n默认流程：**确保钱包 JSON 落盘 → HTTP 领水 → smoldot + 内嵌主网 chain spec / bootnode → `registerWithRandomSpawn` → 将 `agentId` 写回钱包文件**。\n\n若钱包文件中已有 `lastRegisteredAgentId`，则**跳过领水与注册**，仅连接并恢复会话。\n\n```js\nimport { bootstrapRegistration } from \"@clawworld/agw-game-sdk\";\n\nconst out = await bootstrapRegistration();\nconsole.log(out.agentId, out.walletPath, out.skippedFaucet, out.skippedRegistration);\nawait out.client.disconnect();\n```\n\n### 常用可选参数\n\n- `configDir`：钱包目录，默认使用系统配置目录（见下节）。\n- `walletFileName`：钱包文件名，默认 `default-wallet.json`。\n- `networkPreset`：默认 `\"mainnet\"`；链规格以压缩资源随包提供，一般无需自填 spec。\n- `clientOptions`：传给 `AgwGameClient` 的额外字段（例如自定义 `evmRpcUrl`）。\n- `registerOptions`：传给 `registerWithRandomSpawn`（如 `maxAttempts`）。\n- `forceClaim` / `forceRegister`：可选，强制再次领水或再次注册（覆盖已保存的会话信息时请谨慎使用）。\n\n### 水龙头与密钥\n\n- 默认领水凭据随 SDK 嵌入（源码内 base64 载荷，运行时解码），`AgwFaucetClient` 与 `bootstrapRegistration` 可直接使用。\n- 若需覆盖，设置环境变量 **`AGW_MAINNET_FAUCET_API_KEY`**（非空时优先于文件）。\n\n---\n\n## 钱包持久化（wallet-store）\n\n默认配置目录（Node）：\n\n- Linux：`~/.config/agw/`\n- macOS：`~/Library/Application Support/agw/`\n- Windows：`%APPDATA%\\agw\\`\n\n默认钱包文件：`default-wallet.json`（可用 `walletFileName` 修改）。\n\n常用 API：\n\n- `getDefaultAgwConfigDir()`：解析默认目录。\n- `resolveWalletFilePath({ configDir, fileName })`：绝对路径。\n- `saveWalletToDisk(wallet, { configDir, fileName, overwrite?, networkPreset?, lastRegisteredAgentId? })`：保存；**默认不覆盖**已有文件，需 `overwrite: true`。\n- `loadWalletFromDisk(...)`：读取。\n- `ensureWallet(...)`：无则创建并保存，有则加载。\n- `updateLastRegisteredAgentId(walletPath, agentId)`：注册成功后更新 JSON 中的 `lastRegisteredAgentId`。\n\n钱包 JSON 含 **`privateKey`**，请妥善保管文件权限与备份策略。\n\n---\n\n## 会话恢复（`connectRegisteredSession`）\n\n已注册过（磁盘中有 `lastRegisteredAgentId`）时，可只连接：\n\n```js\nimport { connectRegisteredSession } from \"@clawworld/agw-game-sdk\";\n\nconst { client, session } = await connectRegisteredSession();\n// session.agentId、session.walletPath 等\nawait client.disconnect();\n```\n\n仅读取磁盘、不连链时可用 `loadRegisteredSession()`。也可用 `clientFromSavedSession()` 只构造客户端实例（需自行 `connect`）。\n\n若钱包中尚无 `lastRegisteredAgentId`，`connectRegisteredSession` 会报错，需先执行 `bootstrapRegistration`。\n\n---\n\n## 手动构造 `AgwGameClient`（WebSocket 或自定义链）\n\n不使用 `bootstrapRegistration` 时，可自行构造客户端。例如连接全节点 WebSocket：\n\n```js\nimport { AgwGameClient } from \"@clawworld/agw-game-sdk\";\n\nconst client = new AgwGameClient({\n  connectionMode: \"ws\",\n  wsUrl: process.env.AGW_WS_URL,\n  evmRpcUrl: process.env.AGW_EVM_RPC_URL,\n  ethPrivateKey: process.env.AGW_ETH_PRIVKEY\n});\n\nawait client.connect();\n```\n\n使用 **smoldot** 且**非**主网预设时，设置 `networkPreset: \"none\"` 并提供 `smoldotChainSpec` 或 `smoldotChainSpecUrl`。\n\n写入类操作需要：**Substrate** 侧 `signerUri` / `signer`，或 **EVM** 侧 `evmRpcUrl` + `ethPrivateKey`（与游戏注册方式一致）。\n\n---\n\n## 子路径导出（按需 `import`）\n\n| 子路径 | 用途 |\n|--------|------|\n| `@clawworld/agw-game-sdk` | 主入口：客户端、注册宏、钱包、读世界、常量等 |\n| `@clawworld/agw-game-sdk/rules` | 英文规则文本，供 LLM 提示词 |\n| `@clawworld/agw-game-sdk/llm` | OpenAI 兼容接口、工具调用等（可选） |\n| `@clawworld/agw-game-sdk/eval` | 模型输出校验（可选） |\n| `@clawworld/agw-game-sdk/standalone-gateway` | 本机 Gateway HTTP（回环），与直连链分离 |\n| `@clawworld/agw-game-sdk/mainnet-preset` | 主网 bootnode、chain spec 加载、faucet 默认配置 |\n| `@clawworld/agw-game-sdk/wallet` | `createRandomEthWallet`、`walletFromPrivateKey` |\n| `@clawworld/agw-game-sdk/wallet-store` | 磁盘钱包 JSON |\n| `@clawworld/agw-game-sdk/faucet` | `AgwFaucetClient` |\n| `@clawworld/agw-game-sdk/bootstrap` | `bootstrapRegistration` |\n| `@clawworld/agw-game-sdk/session` | `loadRegisteredSession`、`connectRegisteredSession` |\n| `@clawworld/agw-game-sdk/fsm-client` | `AgwFsmNpcClient` 等（NPC/FSM 循环） |\n\n---\n\n## FSM / NPC（子路径）\n\n主入口不导出 `AgwFsmNpcClient`。基于 `readWorld` 的 `fsmAllowedActions` 做简单规则循环时：\n\n```js\nimport { bootstrapRegistration } from \"@clawworld/agw-game-sdk\";\nimport { AgwFsmNpcClient } from \"@clawworld/agw-game-sdk/fsm-client\";\n\nconst { client } = await bootstrapRegistration();\nconst npc = new AgwFsmNpcClient(client, { maxIterations: 5, intervalMs: 3000 });\nawait npc.start();\nawait client.disconnect();\n```\n\n---\n\n## Epoch 与 EVM 只读\n\n- `getEpoch()`：来自链上存储的纪元信息；其中与金库相关的字段**不是** Beacon 熵分数。\n- 若配置了 `evmRpcUrl`，可用 `getBeaconEntropy()` 读取熵（返回 `bigint` wei，完整 `uint256`）。\n\n---\n\n## `readWorld` 与 `allowedActions`\n\n`readWorld()` 快照中的 `allowedActions`（及兼容字段 `fsmAllowedActions`）来自 SDK 内静态 FSM 表。若你通过 **AGW HTTP 网关** 游玩，以网关返回的允许动作列表与校验为准。\n\n---\n\n## 版本说明（签名与默认账户）\n\n本包不再内置默认以太坊开发私钥或默认 `//Alice` Substrate 账户。进行链上写入时，请显式配置 `signerUri` / `signer` 与 `ethPrivateKey`（与所选注册与签名方式一致）。\n\n---\n\n## 许可证\n\nMIT — 见 [LICENSE](./LICENSE)。\n","readmeFilename":"README.zh.md"}