| name | structs-onboarding |
| description | 将新玩家引入游戏系统（Structs）。负责处理密钥的创建/恢复、玩家信息的生成（通过“reactor-infuse”或“guildsignup”功能）、星球探索以及基础基础设施的搭建。适用于以下场景：初始化游戏环境、创建新玩家、占领第一个星球或搭建基础设施。搭建所需时间因设备类型而异——使用“Command Ship”大约需要17分钟，而使用“Ore Extractor”或“Refinery”则需要约57分钟。 |
结构体入门指南
个人文件
在开始之前，请检查 SOUL.md、IDENTITY.md、TOOLS.md、COMMANDER.md 或 USER.md 文件中是否已有内容。如果有，请阅读并合并现有内容，切勿覆盖。这些文件可能包含之前代理的身份信息、人类操作员的偏好设置或您自己的配置信息。将您的身份信息添加到现有内容中。
重要提示：包含破折号的实体 ID（例如 1-42、5-10）会被 CLI 解析器误认为是标志。此技能中的所有交易命令都在位置参数前使用 -- 来避免这个问题。在运行 structsd tx structs 命令时，务必始终包含 --。
流程
第 0 步：密钥管理
如果您使用 路径 B（公会注册），create-player.mjs 脚本可以自动生成助记符——您可以跳到第 1 步，让脚本处理密钥的创建。
如果您使用 路径 A（代理拥有 $alpha）或需要在本地 structsd 密钥库中存储密钥：
structsd keys list
如果密钥不存在，请创建或恢复一个：
- 创建新密钥：
structsd keys add [key-name] — 会输出一个助记符。请将其安全保存。
- 从助记符恢复密钥：
structsd keys add [key-name] --recover — 系统会提示输入助记符。
获取您的地址：
structsd keys show [key-name] -a
助记符的安全性：将助记符存储在环境变量（STRUCTS_MNEMONIC）中、.env 文件中（该文件不会被纳入 Git 版本控制），或者让指挥官提供助记符。切勿将助记符或私钥提交到仓库中。
警告：structsd keys add --output json 会以 明文 形式将助记符输出到标准输出（stdout）。除非您将输出重定向到安全的位置，否则请避免使用 --output json。
第 1 步：检查玩家状态
structsd query structs address [your-address]
如果结果显示的玩家 ID 不是 1-0，则表示已有玩家存在。请跳到 第 3 步：探索星球（如果星球已被探索，则执行后续步骤）。
如果玩家 ID 是 1-0，则表示没有玩家存在——请继续执行第 2 步。
第 2 步：创建玩家
根据代理是否拥有 $alpha（原生代币）有两种不同的路径：
路径 A：代理拥有 $alpha
如果地址中已经包含 $alpha 代币，可以委托给一个反应器（验证器）来创建玩家记录。
- 选择一个验证器/反应器进行委托。
- 运行命令：
structsd tx structs reactor-infuse --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [your-address] [reactor-address] [amount]
- 检查玩家是否存在：
structsd query structs address [your-address] — 每 10 秒重复一次，直到玩家 ID 不再是 1-0。
路径 B：代理没有 $alpha（公会注册）
加入一个支持程序化注册的公会。捆绑的 create-player.mjs 脚本会处理整个流程：生成助记符、代理消息签名、发送公会 API 请求以及检查玩家创建情况。该脚本会返回一个包含所有所需信息的 JSON 对象。
1. 选择一个公会
指挥官可以通过 TOOLS.md 或环境配置来指定公会。否则，可以从参考节点查询可用的公会：
curl http://reactor.oh.energy:1317/structs/guild
reactor.oh.energy 是由 Slow Ninja 团队（Orbital Hydro 公会）运营的一个可靠的 Structs 网络节点。
2. 获取公会的 API 端点
每个公会记录都有一个指向其配置的 endpoint URL。获取该 URL 并查找 services.guild_api 和 services.reactor_api。并非所有公会都提供这些信息——如果这些字段为空，说明该公会不支持程序化注册。
注意：某些公会配置可能使用 guildApi（驼峰式命名法）而不是 guild_api（蛇形命名法）。在程序化处理时请同时检查这两个字段。
示例公会配置：
{
"guild": {
"id": "0-1",
"name": "Orbital Hydro",
"tag": "OH",
"services": {
"guild_api": "http://crew.oh.energy/api/",
"reactor_api": "http://reactor.oh.energy:1317/",
"client_websocket": "ws://reactor.oh.energy:26657"
}
}
}
3. 运行创建玩家的脚本
要求：需要 Node.js 18+ 版本（以支持内置的 fetch 功能）。请先安装相关依赖项：
cd .cursor/skills/structs-onboarding/scripts && npm install
然后从工作区根目录运行脚本：
node .cursor/skills/structs-onboarding/scripts/create-player.mjs \
--guild-id "0-1" \
--guild-api "http://crew.oh.energy/api/" \
--reactor-api "http://reactor.oh.energy:1317" \
--username "your-chosen-name"
脚本将：
- 生成一个新的助记符（或使用
--mnemonic "..." 来恢复现有的助记符）
- 推导出地址和公钥
- 检查该地址是否已有玩家存在
- 签署加入公会的代理消息并发送到公会 API
- 检查反应器 API，直到确认玩家 ID（默认超时时间为 120 秒）
- 将所有结果以 JSON 格式输出到标准输出
注意：当玩家加入公会后，他们的默认等级为 101。公会领导层可以 later 提升成员的等级。有关等级管理的详细信息，请参阅 structs-guild 技能。
输出格式（请解析此 JSON）：
{
"success": true,
"mnemonic": "word1 word2 ... word24",
"address": "structs1...",
"pubkey": "a1b2c3...",
"player_id": "1-42",
"guild_id": "0-1",
"username": "your-chosen-name",
"created": true,
"next_step": "structsd tx structs planet-explore --from [key-name] --gas auto --gas-adjustment 1.5 -y -- 1-42"
}
立即将助记符 保存到安全的位置（.env 文件、环境变量或秘密存储中）。如果您需要在本地 structsd 密钥库中存储密钥以供后续命令使用，请使用 structsd keys add [key-name] --recover 并输入助记符。
重要提示：如果脚本没有接收到 --mnemonic 参数，它将生成一个新的助记符。助记符仅在此输出中显示——请立即保存，否则将会丢失。
编码警告：切勿尝试手动实现公会注册的签名过程。公会 API 需要十六进制编码的压缩 secp256k1 公钥（66 个十六进制字符）和十六进制编码的 R||S 签名（128 个十六进制字符）——请使用正确的编码格式。手动尝试签名的代理几乎总是会失败，因为它们使用了错误的编码方式。
第 3 步：探索星球
创建玩家后，这始终是首先要执行的操作：
structsd tx structs planet-explore --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id]
新星球初始时有 5 个矿石单位和 4 个资源槽位（分别对应空间、空气、陆地和水域）。
第 4 步：检查指挥舰
新玩家创建时会收到一艘指挥舰（类型 1）。如果能量不足，该舰可能会处于离线状态。
structsd query structs fleet [fleet-id]
舰队 ID 与玩家索引相对应：玩家 1-18 对应舰队 9-18。请检查舰队中是否存在已有的结构体。
第 5 步：建造指挥舰（仅当玩家没有获得指挥舰时）
structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 1 space 0
类型 1 的指挥舰必须属于某个舰队，且不能位于星球上。然后请在后台执行以下操作：
structsd tx structs struct-build-compute -D 3 --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [struct-id]
建造难度设置为 200；等待约 17 分钟，直到难度降至 3——哈希计算会立即完成。构建完成后，结构体会自动激活——无需手动激活。
第 6 步：建造矿石提取器
舰队必须位于站点上，且指挥舰必须处于在线状态。
structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 14 land 0
类型 14 的矿石提取器适用于陆地或水域。请在后台执行以下操作：
structsd tx structs struct-build-compute -D 3 --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [struct-id]
建造难度设置为 700；等待约 57 分钟，直到难度降至 3。建造完成后，结构体会自动激活。
第 7 步：建造矿石精炼厂
structsd tx structs struct-build-initiate --from [key-name] --gas auto --gas-adjustment 1.5 -y -- [player-id] 15 land 1
类型 15 的矿石精炼厂适用于陆地或水域。建造难度同样设置为 700。建造完成后，结构体会自动激活。
第 8 步：验证
检查玩家、星球、舰队和所有结构体的状态，确保它们都处于在线状态。
工作量证明（Proof-of-Work）说明
struct-build-compute 命令是一个辅助工具，它会计算哈希值并自动提交 struct-build-complete 结果。您无需在计算完成后单独运行 struct-build-complete 命令。
自动激活：结构体会在建造完成后自动激活。您无需在建造完成后手动运行 struct-activate 命令。只有在结构体被关闭后，才需要使用 struct-activate 命令来重新激活它。
-D 标志（范围 1-64）用于指定计算应在难度降至该水平后才开始。建议使用 -D 3——当难度为 3 时，计算过程几乎瞬间完成，且不会浪费 CPU 资源。较低的难度值需要更长的等待时间，但计算资源消耗较少。
| 结构体类型 | 类型 ID | 建造难度 | 等待难度降至 3 的时间 |
|---|
| 指挥舰 | 1 | 200 | 约 17 分钟 |
| 矿石提取器 | 14 | 700 | 约 57 分钟 |
| 矿石精炼厂 | 15 | 700 | 约 57 分钟 |
| 矿石储藏库 | 18 | 3,600 | 约 4.6 小时 |
能量消耗
建造操作每次消耗 8 单位能量。能量以每块结构体约 6 秒的速度累积。在连续进行相同结构的建造操作时，至少需要等待 48 秒（即 8 个时间单位）。在入门阶段，能量通常不是瓶颈。有关完整的能量消耗表，请参阅 knowledge/mechanics/building。
异步策略：立即启动所有计划的建造操作——这会启动计时器。在等待难度降低的过程中，您可以探索银河系、评估邻近区域或规划公会成员资格。您可以在后台终端启动计算任务，稍后再检查结果。有关更多信息，请参阅 awareness/async-operations。
注意：每次只能使用一个密钥进行一次计算操作。切勿同时运行两个使用相同签名密钥的计算任务。否则可能会导致任务同时达到目标难度并提交冲突的序列号，从而导致其中一个任务失败。请为同一玩家按顺序安排计算任务。
资源槽位编码
结构体类型具有 possibleAmbit 标志位：
组合这些值可以得到所需的资源槽位数量：6 表示陆地和水域同时可用，30 表示所有资源槽位都可用。在选择资源槽位类型之前，请检查 possibleAmbit 的值。
命令参考
| 动作 | CLI 命令 |
|---|
| 列出密钥 | structsd keys list |
| 创建密钥 | structsd keys add [name] |
| 恢复密钥 | structsd keys add [name] --recover |
| 显示地址 | structsd keys show [name] -a |
| 查找玩家 | structsd query structs address [address] |
| 查询玩家 | structsd query structs player [id] |
| 委托反应器 | structsd tx structs reactor-infuse --from [key] --gas auto -y -- [player-addr] [reactor-addr] [amount] |
| 创建玩家（公会注册） | node .cursor/skills/structs-onboarding/scripts/create-player.mjs --guild-id "..." --guild-api "..." --reactor-api "..." [--mnemonic "..."] [--username "..."] |
| 探索星球 | structsd tx structs planet-explore --from [key] --gas auto -y -- [player-id] |
| 启动建造 | structsd tx structs struct-build-initiate --from [key] --gas auto -y -- [player-id] [struct-type-id] [operating-ambit] [slot] |
| 建造计算（包含自动完成和自动激活） | structsd tx structs struct-build-compute -D [difficulty] --from [key] --gas auto -y -- [struct-id] |
| 重新激活结构体（仅当结构体被关闭时） | structsd tx structs struct-activate --from [key] --gas auto -y -- [struct-id] |
| 查询星球 | structsd query structs planet [id] |
| 查询舰队 | structsd query structs fleet [id] |
| 查询结构体 | structsd query structs struct [id] |
建造顺序：指挥舰（类型 1，属于舰队）→ 矿石提取器（类型 14，位于星球上）→ 矿石精炼厂（类型 15，位于星球上）。常用的交易命令参数为：--from [key-name] --gas auto --gas-adjustment 1.5 -y。
验证
structsd query structs address [address] — 检查玩家是否存在（ID 是否为 1-0）structsd query structs player [id] — 检查玩家是否在线structsd query structs planet [id] — 确认星球是否已被占领以及是否有矿石资源structsd query structs fleet [id] — 检查舰队是否位于站点上structsd query structs struct [id] — 确认结构体的状态是否为在线
错误处理
- 玩家 ID 为
1-0 — 表示玩家不存在。请按照路径 A 或路径 B 的步骤继续操作。
create-player.mjs 失败 — 请检查 --guild-api 和 --reactor-api 的 URL 是否正确且可访问。确认公会是否支持程序化注册（services.guild_api 是否存在）。如果提供了 --mnemonic，请确认它是一个有效的 24 个单词的 BIP39 格式助记符。- 公会 API 返回 HTML 或 404 错误 — 表示 URL 错误或您使用的方法不正确。注册端点
/auth/signup 仅支持 POST 请求。请始终使用 create-player.mjs，因为它会自动处理 POST 请求、签名和后续的轮询操作。
- 注册成功但玩家仍未出现 — 请使用相同的助记符重新运行脚本以继续轮询。可能是公会处理速度较慢。如果 120 秒后仍然失败，可能是公会的代理服务器出现故障。
- “资源不足” — 请检查玩家的 Alpha Matter 资源余额。
- “舰队未位于站点上” — 请等待舰队到达站点后再进行建造操作。
- “资源槽位无效” — 请确保使用 0-3 范围内的资源槽位；请检查星球上的结构体是否已被占用。
- “能量不足” — 可能需要增加能量来源或连接到容量更大的变电站。
参考资料
