这页专门回答一个问题：

HNEconomy 当前到底提供了哪些占位符、外部展示时该怎么写、动态货币又该怎么写？

如果你现在是在做：

• 计分板
• TAB / HUD
• 菜单显示
• 系统资金池看板
• 排行榜展示
• 多货币金额回显

那这一页就是最快入口。

---

一、先说最重要的：当前前缀不是 %hneconomy_xxx%

当前版本的 HNEconomy 是通过 HNCore 占位符桥 注册经济命名空间 economy。

为了避免概念混淆，这页统一这样称呼：

• HNCore 占位符桥：HNEconomy 当前真正对外暴露的经济命名空间能力
• PlaceholderAPI 外部环境：你在别的插件、计分板、菜单等位置实际填写 %...% 的使用场景

所以在 PlaceholderAPI 外部环境 中，正确写法是：

%hncore_economy_<params>%

例如：

%hncore_economy_balance%
%hncore_economy_balance_gold%
%hncore_economy_treasury_total_fee_point%
%hncore_economy_top_balance_name_gold_1%

不要和内部模板占位符混淆

在 gui/*.yml、消息模板或 HNCore 渲染上下文里，你经常还会看到这种写法：

{economy.balance_formatted}
{economy.currency_display}
{economy.pay_receive_text}

两者区别是：

• PlaceholderAPI 外部调用：%hncore_economy_xxx%
• HNCore 内部模板渲染：{economy.xxx}

---

二、启用条件

当前同时满足下面两个条件时，外部 PlaceholderAPI 才能正常访问这些占位符：

• 服务器已安装 PlaceholderAPI
• config.yml 中 placeholderapi.enabled: true

如果你只是修改 gui/*.yml 或消息模板里的 {economy.xxx}，那走的是 HNCore 内部占位符提供器，不等同于你在别的插件里直接写 %...%。

---

三、基础信息占位符

这些占位符不依赖当前玩家：

占位符	说明	返回示例
%hncore_economy_main_currency%	当前主货币 ID	gold
%hncore_economy_currency%	main_currency 的别名	gold
%hncore_economy_main_currency_display%	当前主货币显示名	金币
%hncore_economy_currency_display%	main_currency_display 的别名	金币
%hncore_economy_treasury_name%	系统资金池显示名	系统国库

---

四、玩家相关占位符

下面这些占位符默认作用于当前玩家：

占位符	说明	返回示例
%hncore_economy_pay_receive%	是否允许接收转账	on / off
%hncore_economy_pay_receive_text%	是否允许接收转账的中文说明	允许接收转账
%hncore_economy_balance%	主货币余额（纯数字）	12500
%hncore_economy_balance_formatted%	主货币余额（格式化）	12,500
%hncore_economy_default_balance%	主货币余额（balance 别名）	12500
%hncore_economy_default_balance_formatted%	主货币余额格式化（别名）	12,500
%hncore_economy_rank%	主货币余额排名	3
%hncore_economy_today_pay_fee%	主货币今日转账手续费支出（纯数字）	200
%hncore_economy_today_pay_fee_formatted%	主货币今日转账手续费支出（格式化）	200

你最需要记住的一点是：

不带货币 ID 的玩家金额类占位符，默认都基于当前主货币。

---

五、动态货币占位符怎么写

HNEconomy 的多货币占位符不是为每个货币写死，而是按 currencyId 动态解析。

也就是说，只要你在 currencies.yml 里新增了：

currencies:
  diamond:
    display-name: "钻石币"

你就可以直接写：

%hncore_economy_balance_diamond%
%hncore_economy_balance_formatted_diamond%
%hncore_economy_treasury_balance_diamond%

动态货币模板表

占位符模板	说明
%hncore_economy_balance_<currencyId>%	指定货币余额（纯数字）
%hncore_economy_balance_formatted_<currencyId>%	指定货币余额（格式化）
%hncore_economy_rank_<currencyId>%	指定货币余额排名
%hncore_economy_today_pay_fee_<currencyId>%	指定货币今日转账手续费支出（纯数字）
%hncore_economy_today_pay_fee_formatted_<currencyId>%	指定货币今日转账手续费支出（格式化）
%hncore_economy_treasury_balance_<currencyId>%	指定货币系统资金池余额（纯数字）
%hncore_economy_treasury_balance_formatted_<currencyId>%	指定货币系统资金池余额（格式化）
%hncore_economy_treasury_today_fee_<currencyId>%	指定货币系统资金池今日手续费收入（纯数字）
%hncore_economy_treasury_today_fee_formatted_<currencyId>%	指定货币系统资金池今日手续费收入（格式化）
%hncore_economy_treasury_total_fee_<currencyId>%	指定货币系统资金池累计手续费收入（纯数字）
%hncore_economy_treasury_total_fee_formatted_<currencyId>%	指定货币系统资金池累计手续费收入（格式化）
%hncore_economy_treasury_rank_<currencyId>%	指定货币中系统资金池的余额排名

例子

%hncore_economy_balance_gold%
%hncore_economy_balance_formatted_point%
%hncore_economy_rank_diamond%
%hncore_economy_treasury_total_fee_gold%
%hncore_economy_treasury_balance_formatted_point%

这里最容易写错的是：

• 写成显示名，而不是 currencyId
• 写错大小写或拼写
• 以为新增货币后还要额外注册一遍 PAPI

推荐始终使用 currencies.yml 里的小写货币 ID。

---

六、几个方便但容易忽略的别名写法

当前实现里，还支持把货币 ID 直接当成键名使用。

例如如果你有 gold 这个货币，那么下面这些写法也能生效：

%hncore_economy_gold%
%hncore_economy_gold_formatted%
%hncore_economy_gold_raw%

含义分别近似于：

• %hncore_economy_gold% → 当前玩家 gold 余额
• %hncore_economy_gold_formatted% → 当前玩家 gold 格式化余额
• %hncore_economy_gold_raw% → 当前玩家 gold 纯数字余额

不过从可读性和团队协作角度，仍更推荐优先使用 balance_<currencyId> 这一组标准写法。

---

七、系统资金池相关占位符

下面这些占位符在不带货币 ID 时，默认基于当前主货币：

占位符	说明
%hncore_economy_treasury_balance%	主货币系统资金池余额（纯数字）
%hncore_economy_treasury_balance_formatted%	主货币系统资金池余额（格式化）
%hncore_economy_treasury_today_fee%	主货币系统资金池今日手续费收入（纯数字）
%hncore_economy_treasury_today_fee_formatted%	主货币系统资金池今日手续费收入（格式化）
%hncore_economy_treasury_total_fee%	主货币系统资金池累计手续费收入（纯数字）
%hncore_economy_treasury_total_fee_formatted%	主货币系统资金池累计手续费收入（格式化）
%hncore_economy_treasury_fee_7d%	主货币系统资金池最近 7 天手续费收入（纯数字）
%hncore_economy_treasury_fee_7d_formatted%	主货币系统资金池最近 7 天手续费收入（格式化）
%hncore_economy_treasury_fee_30d%	主货币系统资金池最近 30 天手续费收入（纯数字）
%hncore_economy_treasury_fee_30d_formatted%	主货币系统资金池最近 30 天手续费收入（格式化）
%hncore_economy_treasury_rank%	主货币中系统资金池的余额排名

如果你希望明确指定货币，就改用上一节的动态货币模板。

---

八、排行榜占位符

排行榜占位符同时依赖：

• <currencyId>：货币 ID
• <position>：名次，从 1 开始

模板表

占位符模板	说明
%hncore_economy_top_balance_name_<currencyId>_<position>%	指定货币余额榜第 <position> 名玩家名称
%hncore_economy_top_balance_amount_<currencyId>_<position>%	指定货币余额榜第 <position> 名余额（格式化）
%hncore_economy_top_pay_name_<currencyId>_<position>%	指定货币近 7 天转账支出榜第 <position> 名玩家名称
%hncore_economy_top_pay_amount_<currencyId>_<position>%	指定货币近 7 天转账支出榜第 <position> 名金额（格式化）
%hncore_economy_top_balance_count%	主货币余额榜当前缓存条目数量

例子

%hncore_economy_top_balance_name_gold_1%
%hncore_economy_top_balance_amount_gold_1%
%hncore_economy_top_pay_name_point_3%
%hncore_economy_top_pay_amount_point_3%

注意：

• <position> 必须是大于 0 的整数
• 排行榜名次超出当前缓存条目时，会返回空值
• top_balance_count 当前是主货币维度，不带货币参数

---

九、当前返回规则

当前实现里，不同类型占位符的回退值并不完全一样，大致可以这样记：

情况	常见返回结果
玩家相关占位符缺少玩家上下文	空字符串
指定货币不存在，且占位符是金额类	0
指定货币不存在，且占位符是排名类	-1
排行榜参数格式不合法	空字符串
主货币不可用时的主货币金额类占位符	0

所以你在面板里看到空白，不一定是插件坏了，也可能是：

• 当前请求没有玩家上下文
• 货币 ID 写错了
• 排名位置超出了榜单范围

---

十、最容易写错的地方

1）把显示名当成货币 ID

错误示例：

%hncore_economy_balance_金币%

正确写法应该是：

%hncore_economy_balance_gold%

这里要写的是 currencies.yml 里的键名，也就是 currencyId，不是中文显示名。

---

2）把旧前缀 %hneconomy_xxx% 继续拿来用

当前版本对外文档应统一按：

%hncore_economy_xxx%

来写。

如果你照旧写：

%hneconomy_balance%

那多半是不会按预期工作的。

---

3）以为每个货币都要额外注册占位符

不需要。

只要货币已经在 currencies.yml 注册，并且插件已重载，动态占位符就能直接按 currencyId 生效。

---

4）把外部 PlaceholderAPI 和内部 GUI 模板语法混了

例如：

• 外部插件 / 计分板：%hncore_economy_balance%
• gui/*.yml / 消息模板：{economy.balance_formatted}

这是两套入口，不要混写。

---

5）以为所有货币元信息都有专门占位符

当前实现主要覆盖：

• 余额
• 排名
• 系统资金池
• 手续费
• 排行榜
• 主货币基础信息

但没有为每个货币提供完整的元信息模板，例如下面这种并不是当前标准能力：

%hncore_economy_currency_symbol_gold%

如果后续这类能力新增了，再同步更新 Wiki。

---

十一、最短排查清单

如果占位符显示不对，建议按这个顺序来：

1. 服务器是否安装了 PlaceholderAPI
2. config.yml 里的 placeholderapi.enabled 是否为 true
3. 你写的是不是 %hncore_economy_xxx%，而不是旧前缀
4. 当前货币 ID 是否和 currencies.yml 一致
5. 如果是玩家相关占位符，当前场景是否有玩家上下文
6. 如果是排行榜占位符，名次是否超出缓存范围
7. 如果是金额显示不对，再回到 HNEconomy 内部检查余额、流水与系统资金池统计

---

十二、这一页最该记住的重点

1. 当前对外 PlaceholderAPI 前缀应写成 %hncore_economy_<params>%
2. 多货币占位符按 currencyId 动态解析，不需要每个货币单独写死
3. 不带货币 ID 的余额 / 系统资金池默认占位符通常基于主货币
4. 排行榜占位符同时需要货币 ID 和名次
5. gui/*.yml 和消息模板里常见的是 {economy.xxx}，不要和外部 %...% 语法混淆

---

推荐阅读

• 集成与 API
• messages.yml 文案与消息说明
• GUI 与玩家面板配置
• 运维排障清单与故障定位顺序
• 常见问题