变量解析

变量解析让机器人读取服务器与玩家信息，并将结果用于群消息、条件判断和图片卡片。你可以查询在线人数和玩家名单，也可以结合 PlaceholderAPI 获取经济、权限组、技能等数据。

使用前，请先完成单服配置或代理集群部署，确保机器人扩展核心与插件连接正常。

插件内置变量

下列 8 个占位符由 StellarAnchorBot 子服插件直接提供，不依赖 PlaceholderAPI。服务器相关数据均来自实际处理请求的子服。

变量	作用	使用条件与结果
%online_count%	当前子服在线人数	无需玩家名，单独使用时返回整数
%player_list%	当前子服在线玩家名称列表	无需玩家名，返回逗号加空格分隔的文本，如 Steve, Alex；无人在线时为空字符串
%online_players%	在线玩家名称列表的另一种写法	与 %player_list% 相同，返回文本，不是 JSON 数组
%server_name%	服务端实现名称	无需玩家名，调用 Bukkit 的 Server#getName()，例如 Paper；不是配置中的 server_id 或 RCON 自定义名称
%player_name%	查询玩家的游戏名称	需要填写玩家名称；支持离线上下文，查不到已记录名称时使用请求中的名称
%player_uuid%	查询玩家的 UUID	需要填写玩家名称，返回当前服务端为该玩家解析到的 UUID
%player_ping%	玩家网络延迟，单位毫秒	玩家必须在处理请求的子服在线；当前服务端无法读取延迟时返回 0
%player_health%	玩家当前生命值	玩家必须在处理请求的子服在线；返回生命值数值，通常 20 点相当于 10 颗心

在线与离线的区别

服务器变量不需要玩家在线。玩家名称和 UUID 可使用离线玩家上下文；延迟、生命值则要求玩家在实际解析的子服在线。

未提供玩家名，或玩家不满足在线条件时，对应内置变量不会被替换。若安装了 PlaceholderAPI，剩余文本还会交给它继续解析，最终结果取决于对应扩展；不要把未解析的占位符当成真实数据。

PlaceholderAPI 扩展变量

安装 PlaceholderAPI 及相应扩展、业务插件后，可以在同一个变量组中继续使用第三方占位符。插件先处理自身内置变量，再将剩余文本交给 PlaceholderAPI。

下面这些来自默认玩家信息与金币排行配置，不属于 StellarAnchorBot 内置变量：

占位符示例	作用	相关能力
%statistic_time_played%	玩家游玩时间数据	Statistic，配套玩家信息模板按 tick 换算
%advancements_completedAmount%	玩家进度 / 成就完成数量	Advancements 对应扩展
%mcmmo_power_level%	mcMMO 总技能等级	mcMMO
%vault_eco_balance%	玩家经济余额	Vault 及实际经济插件
%luckperms_primary_group_name%	玩家主要权限组名称	LuckPerms
%playerpoints_points%	玩家点券数量	PlayerPoints
%townyadvanced_town%	玩家所属小镇	Towny 相关支持
%xconomy_balance_value%	当前玩家的 XConomy 余额	XConomy
%xconomy_top_player_1%	XConomy 金币排行第 1 名玩家	XConomy，默认配置使用第 1–10 名
%xconomy_top_balance_1%	XConomy 金币排行第 1 名余额	XConomy，默认配置使用第 1–10 名

占位符名称、可用扩展和离线支持会随第三方插件版本变化，请以服务器实际解析结果为准。安装 PlaceholderAPI 后建议重启服务端，确保 StellarAnchorBot 加载时检测到它。

可先在游戏中测试，例如：

/papi parse Steve %vault_eco_balance%

将 Steve 换成实际玩家名。StellarAnchorBot 的内置变量由自身解析器提供，不能用 /papi parse 作为它们是否可用的判断依据。

创建与修改变量组

变量组是一个 YAML 文件，用来指定一次需要读取哪些数据。文件放在子服：

plugins/StellarAnchorBot/variables/

调用时填写文件名，不带 .yml，例如 server_status.yml 对应 server_status。名称只使用英文字母、数字、下划线和横线，不填写目录路径。

示例：服务器在线情况

在上述目录创建 server_status.yml：

# 当前子服的在线情况，不需要提供玩家名称。
Bindings:
  # 服务端实现名称，例如 Paper，不是 server_id。
  server: '%server_name%'
  # 在线人数，单独使用内置占位符时保留数字类型。
  online: '%online_count%'
  # 在线玩家名称，返回逗号加空格分隔的文本。
  players: '%player_list%'
  # 占位符嵌入一段文字后，结果为字符串。
  summary: '当前共有 %online_count% 位玩家在线'

保存后，在子服执行：

/sab reload

假设该子服实现名称为 Paper，有 Steve、Alex 两名玩家在线，解析结果可能是：

{
  "Bindings": {
    "server": "Paper",
    "online": 2,
    "players": "Steve, Alex",
    "summary": "当前共有 2 位玩家在线"
  }
}

YAML 的嵌套对象与列表会保留在返回 JSON 中，Bindings 也会保留。键名可以自定义，但后续流程与 HTML 模板引用路径需与之对应。

返回数据类型

写法	返回类型
online: '%online_count%'	数字，内置占位符单独使用时保留原类型
summary: '在线：%online_count%'	字符串，包含文字的拼接结果
balance: '%vault_eco_balance%'	PlaceholderAPI 返回的字符串，即使内容看起来像数字
YAML 中直接填写数字、布尔值	保留 YAML 读取到的对应类型
嵌套对象、列表	递归解析其中的值，保留结构

在后台测试解析

打开机器人后台的「服务器管理 → 扩展核心」，找到「变量组测试」：

字段	示例	填写说明
变量组文件名	server_status	文件必须在目标子服的 variables 目录，并已重载
玩家名称（可选）	Steve	使用玩家变量时填写；仅查询在线情况可留空
目标子服（可选）	sub_server_01	集群中填写目标子服的 server_id；留空或 * 请求全部已连接子服

点击「解析变量组」，检查返回 JSON 是否包含预期字段。先把这里的结果测试正确，再接入流程与图片模板。

在流程中使用变量

在流程系统中添加「变量组解析」节点，例如：

配置项	填写内容
变量组文件名	server_status
玩家名称	此示例不使用玩家变量，留空
目标子服	按需指定 server_id
结果保存名称	mc

单个子服成功返回上方示例结构时，后续节点可以这样引用：

流程变量	内容
{mc.Bindings.server}	服务端实现名称
{mc.Bindings.online}	在线人数
{mc.Bindings.players}	在线玩家名称
{mc.Bindings.summary}	已拼接的说明文字
{mc.json}	完整解析结果 JSON，适合传给 HTML 模板
{last_extension_json}	最近一次变量组解析的完整 JSON

例如连接「收到消息 → 变量组解析 → 发送群消息」，在发送节点的普通消息内容中填写：

服务端：{mc.Bindings.server}
在线人数：{mc.Bindings.online}
在线玩家：{mc.Bindings.players}

插件 YAML 使用 %占位符%，机器人流程使用 {流程变量}，两者不要混写。字段名区分大小写；流程中的单个字段会转换成文本，{mc.json} 则保留完整 JSON 数据结构。

插件自带的变量组

文件	用途	配套 HTML 模板
player_info.yml	玩家名称、UUID、游玩时间、余额、权限组、点券等资料	player-info/index.html
money_ranking_xconomy.yml	XConomy 前十名及当前玩家余额	money-ranking-xconomy/index.html

插件首次初始化变量组目录时释放这些默认文件，已有同名文件不会覆盖。当前实现会记录初始化标记；手动删除默认文件后，不保证重启自动补回，需要从匹配版本的插件资源恢复。

在流程中填写对应文件名、玩家名和结果保存名称 mc，后接「HTML 模板渲染」，模板参数使用 {mc.json}。配套模板需已存在于机器人端 HTML 模板目录中。

查看默认 player_info.yml（保留原配置注释）

# 玩家信息 HTML 模板配套变量组。
#
# 使用方法：
# 1. 将本文件放入服务端 plugins/StellarAnchorBot/variables/。
# 2. 执行 /sab reload，或重启服务端。
# 3. 机器人流程“变量组解析”节点填写 player_info，并提供要查询的玩家名。
# 4. HTML 渲染节点选择 player-info/index.html，模板参数填写 {mc.json}。
#
# player_name 与 player_uuid 是 StellarAnchorBot 插件内置变量，不依赖 PlaceholderAPI。
# 其余字段需要安装 PlaceholderAPI 及对应扩展；没有对应扩展时模板会保持内容为空。
Bindings:
  # 玩家ID
  name: '%player_name%'
  # 玩家UUID
  uuid: '%player_uuid%'

  # Minecraft Statistic 扩展通常返回游玩 tick，模板会按 20 tick = 1 秒自动格式化。
  playtime_ticks: '%statistic_time_played%'

  # 玩家成就数量
  achievements: '%advancements_completedAmount%'
  # 玩家MMO技能等级
  skill_level: '%mcmmo_power_level%'
  # 玩家金币数量
  money: '%vault_eco_balance%'
  # 玩家权限组
  group: '%luckperms_primary_group_name%'
  # 玩家点券数量
  points: '%playerpoints_points%'
  # 玩家小镇
  town: '%townyadvanced_town%'

  # 可填写完整 HTTP(S)、file:// 或 data URL；留空时模板使用 uuid 尝试加载全身皮肤。
  skin_url: ''

查看默认 money_ranking_xconomy.yml（保留原配置注释）

# 金币排行榜 HTML 模板配套变量组。
#
# 使用方法：
# 1. 插件首次启动会自动释放到 plugins/StellarAnchorBot/variables/。
# 2. 已安装旧版插件时，更新 JAR 后重启服务端即可生成；已有同名文件绝不会被覆盖。
# 3. 流程“变量组解析”节点填写 money_ranking_xconomy，并按需提供当前玩家名。
# 4. HTML 渲染节点选择 money-ranking-xconomy/index.html，模板参数填写 {mc.json}。
#
# 依赖 PlaceholderAPI 与 XConomy。若服务器使用的 XConomy 版本变量名不同，
# 请以 /papi parse <玩家名> <占位符> 的实际结果为准调整下列内容。
Bindings:
  title: '金币排行榜'
  server_name: '%server_name%'
  currency_name: '金币'

  # 此处使用变量组解析节点提供的玩家名，显示触发人自己的余额。
  current_player:
    name: '%player_name%'
    balance: '%xconomy_balance_value%'

  # XConomy 提供的全服金币前十名。列表结构会原样传给 HTML 模板。
  ranking:
    - name: '%xconomy_top_player_1%'
      balance: '%xconomy_top_balance_1%'
    - name: '%xconomy_top_player_2%'
      balance: '%xconomy_top_balance_2%'
    - name: '%xconomy_top_player_3%'
      balance: '%xconomy_top_balance_3%'
    - name: '%xconomy_top_player_4%'
      balance: '%xconomy_top_balance_4%'
    - name: '%xconomy_top_player_5%'
      balance: '%xconomy_top_balance_5%'
    - name: '%xconomy_top_player_6%'
      balance: '%xconomy_top_balance_6%'
    - name: '%xconomy_top_player_7%'
      balance: '%xconomy_top_balance_7%'
    - name: '%xconomy_top_player_8%'
      balance: '%xconomy_top_balance_8%'
    - name: '%xconomy_top_player_9%'
      balance: '%xconomy_top_balance_9%'
    - name: '%xconomy_top_player_10%'
      balance: '%xconomy_top_balance_10%'

以上为当前插件资源中的原始示例。第三方占位符未解析时，解析器可能保留原文；配套模板是否隐藏它，由模板自身决定。默认配置中的资源释放说明也需结合上文的初始化标记行为理解。

集群解析规则

集群模式下，玩家名只提供解析上下文，目标子服由请求中的目标字段决定，不会仅因填写玩家名就自动路由到玩家所在服。

目标设置	解析范围
指定子服 server_id	只向对应子服请求
留空或填写 *	向代理当前已连接的全部子服请求
单服直连	由当前连接的子服处理

全服请求只有一个子服成功返回时，保留该子服的原始 JSON；多个子服成功返回时，结果按 server_id 分组，例如：

{
  "survival": {
    "Bindings": { "online": 2, "players": "Steve, Alex" }
  },
  "creative": {
    "Bindings": { "online": 1, "players": "Builder" }
  }
}

此时流程引用路径变为 {mc.survival.Bindings.online}、{mc.creative.Bindings.online}。返回结构取决于成功返回的子服数量，需要稳定字段路径时建议指定子服。

各子服未拥有该变量组时，全服请求中不会产生对应占位数据；所有子服都缺少时可能返回空对象，连接或处理失败则需查看错误。全服聚合存在等待窗口，不保证立即返回。

常见问题

现象	检查方法
提示变量组不存在	文件是否位于目标子服 variables 目录、名称是否不带后缀且符合格式、是否执行 /sab reload
返回原样的 %变量%	是否满足玩家上下文 / 在线条件；第三方变量是否安装了对应扩展及插件
在线人数与预期不同	内置人数和玩家名单只统计实际解析的子服，不是整个代理网络
%server_name% 不是自己的服名	该变量表示服务端实现名称；展示自定义名称可直接在 YAML 写固定文字
金币、权限组等字段为空或未解析	先用对应第三方插件支持的方式测试，核对占位符名称与版本
单个字段在流程中无法读取	检查 Bindings 大小写、结果保存名称，以及集群是否增加了 server_id 层
图片卡片没有内容	先确认变量组 JSON 正确，再检查模板读取的数据结构与 {mc.json} 参数

扩展插件也可以调用 resolveVariables(fileName, playerName, serverId) 读取变量组，见服务器扩展开发教程。