RptPlaceholder —— PAPI 变量短名映射，支持嵌套、文字混排与在线调试 [1.21 ~ 26.2]

R***

关于这个插件​RptPlaceholder 解决的是一个很小、但几乎每个服都会遇到的事：变量太长、太难记。
计分板写一遍、TAB 写一遍、聊天插件里再写一遍，同一个 %xxx_yyy_zzz% 抄得到处都是；哪天变量名变了，还得满配置地找。RptPlaceholder 让你在一个文件里给它起个短名字：
[size=1.2]YAML：
mappings:  "000": "%123456789%"

之后任何支持 PlaceholderAPI 的地方，写 %rpt_000% 就等于写 %123456789%。
它只做这一件事，所以做得很薄：不调度任何任务、不碰实体和世界状态，只在 PlaceholderAPI 来问变量时转发一次。这也是它能原生跑在 Folia 上的原因。
功能说明​1. 一条配置，一个短变量​[size=1.2]YAML：
mappings:  "000": "%123456789%"          # 别处写 %rpt_000%  money: "%vault_eco_balance%"  # 别处写 %rpt_money%

• 别名（左边）不区分大小写，写 MONEY 和 money 是一回事。
• 别名里可以带下划线：%rpt_my_name% 整体当作别名 my_name。
• 别名也可以纯数字（000、123），随你喜欢。
  

2. 目标可以再套变量：嵌套与文字混排​值（右边）不限于"一个变量"，它会再交给 PlaceholderAPI 解析一遍，所以：
[size=1.2]YAML：
mappings:  # ① 一对一转发  money: "%vault_eco_balance%"  # ② 文字 + 变量，直接出一整句  welcome: "欢迎 %player_name% 来到 %player_world%"  # ③ 指向本插件自己的另一个别名  balance: "%rpt_money%"

写	得到
%rpt_money%	1234.5
%rpt_welcome%	欢迎 Steve 来到 world
%rpt_balance%	1234.5（先转到 money 再解析）

3. 配完就能验，不用靠猜​

指令	权限	说明
/rptp list	rptp.use（默认所有玩家）	列出全部映射：%rpt_000% -> %123456789%
/rptp test 000	rptp.use（默认所有玩家）	当场解析一次，显示输入 / 输出 / 耗时
/rptp test %player_name% 你好	rptp.use（默认所有玩家）	直接测一段文本也行
/rptp reload	rptp.admin（默认 OP）	重载 config.yml，不必重启服务端
/rptp help	无	显示指令帮助

/rptp test 还会主动告诉你两种最常见的"没生效"原因：别名没配过，或者变量压根没被任何扩展解析。

主指令 /rptp，兼容别名 /rptplaceholder。

4. 变量前缀可自定义​想更短就把 identifier 改掉：
[size=1.2]YAML：
identifier: x      # 写法从 %rpt_000% 变成 %x_000%

前缀只允许小写字母、数字、下划线，别和其它已装扩展重名（vault / essentials / player / craftengine 之类）即可。
5. 加载时就替你挑错​配置写错不会等到玩家触发才炸 —— 插件在启动与 reload 时就会检查，并在控制台说清楚是哪一条、为什么：

• 映射没配目标值 → 跳过并提示；
• 别名大小写不一致 → 按小写注册并提示；
• 别名里混了 % 或空格 → 提示（空格这条仍然注册，但建议换掉）；
• 两条别名大小写重复 → 提示按后一条生效；
• 目标里引用了本插件自己的变量 → 提示注意别配成互相指向。
  

6. 循环引用保护​如果两个别名不小心配成互相指向，解析会在 8 层处停下并返回原始目标值，同时打一条节流过的控制台警告（同一变量 10 秒内只提醒一次），不会把线程栈打穿、也不会刷爆控制台。
7. 完全适配 Folia​

• 已声明 folia-supported: true。
• 全插件不调度任何任务，不读也不写实体、方块、世界状态，因此不存在跨区域线程的问题。
• 配置在重载时是整体换新（每次 load 生成一份新的映射表再一次性发布），不会出现"读到一半的配置"。
• 解析深度计数按线程隔离，多区域线程同时解析互不干扰。
  

8. 依赖与数据​

• 前置：PlaceholderAPI（softdepend）。没装时插件会自我停用并在控制台说明，不会连累服务端启动。
• 不写数据库、不生成额外文件，只读自己的 plugins/RptPlaceholder/config.yml。
• 除 PlaceholderAPI 外无任何外部依赖。
  

支持版本与环境​

项目	说明
Minecraft 版本	1.21 ~ 26.2（api-version: 1.21，字节码目标 Java 21）
服务端核心	Folia、Paper（已声明 folia-supported: true）
Java 运行环境	Java 21 及以上
不支持	1.20.x 及以下（api-version 为 1.21，低版本核心会拒绝加载）
前置插件	PlaceholderAPI（必须已安装，且至少有一个能提供目标变量的扩展）

本轮实测环境：Folia 26.2-7 + Java 25 + PlaceholderAPI 2.12.3，插件加载、变量注册（Successfully registered internal expansion: rpt）与控制台输出均正常，无异常与告警。

目标用户​

• 正在维护一大堆长变量的服主 —— 把 %xxx_yyy_zzz% 统一收在一张表里，改一处全服生效。
• 用 TAB、计分板、聊天插件的服主 —— 这些地方的变量都要手打，短变量能省下大量复制粘贴。
• 正在使用 Folia 核心的服主 —— 本插件不调度任务、不碰实体，是 Folia 上最没有负担的那类插件。
• 被"变量没生效"折磨过的人 —— /rptp list 与 /rptp test 让你当场看到解析结果，而不是猜。
  

是否付费​完全免费。 不需要授权、不需要联网校验，下载即用。
获取作者帮助​

途径	内容
交流群	QQ 群 1124248111
作者 QQ	2221899680
游戏内	输入 /rptp help 查看指令与说明

使用教程​安装​

• 确认服务端已安装 PlaceholderAPI（本插件的前置）。
• 将 RptPlaceholder-1.0.0.jar 放入服务端 plugins/ 目录。
• 重启服务端，首次启动会生成 plugins/RptPlaceholder/config.yml。
• 编辑 config.yml 里的 mappings，执行 /rptp reload 即可生效，无需重启。
  

权限节点​

权限	默认值	说明
rptp.use	所有玩家	/rptp list、/rptp test
rptp.admin	仅 OP	/rptp reload 重载配置

/rptp help 免权限。

主要配置项（config.yml）​

配置项	默认值	说明
identifier	rpt	变量前缀，写法为 %<identifier>_<别名>%。可改短（如 x）
mappings	见下	别名 → 目标。左边别名不区分大小写、可含下划线；右边为目标变量或"文字+变量"整句

[size=1.2]YAML：
identifier: rptmappings:  "000": "%123456789%"      # %rpt_000%  name: "%player_name%"     # %rpt_name%  money: "%vault_eco_balance%"

常见问题​

• 问：为什么不能直接写 %000%，非要加个 rpt_？
  因为 PlaceholderAPI 本身不接受不带下划线的变量。它的解析器是在 %...% 里扫「第一个下划线」：找到才切成"标识符 + 参数"去找扩展，一个下划线都没有就整段原样跳过，不交给任何扩展。所以 %000% 这种写法在 PAPI 这一层就不成立 —— 这不是本插件的限制，任何插件都做不到。本插件能提供的最短形式就是 %rpt_000%；嫌长可以把 identifier 改成 x，写法变成 %x_000%。
• 问：那 %rpt%（只有前缀、没有别名）能用吗？
  同样用不了，原因同上（没有下划线）。真要一个"无参数"的槽位，写 %rpt_%（下划线在末尾，参数为空）并在 mappings 里把键留空 "" 即可。
• 问：配好了，但变量显示成一串 %xxx% 没变化？
  说明那个目标变量没被任何扩展解析。用 /rptp test 你的别名 看输出：如果"输入"和"输出"完全一样，就是目标写错了，或者提供该变量的扩展没装（比如 %vault_eco_balance% 需要 Vault 扩展、%player_name% 需要 Player 扩展）。注意本插件只负责转发，不提供任何变量本身。
• 问：改了 config.yml 要重启服务端吗？
  不用，/rptp reload 即可。改 identifier 也在重载范围内。
• 问：别名里带下划线可以吗？
  可以。%rpt_my_name% 会整体当成别名 my_name —— 因为变量是在第一个下划线处切分的，第一个下划线之后的内容都属于别名。
• 问：和 PAPI 的 eCloud 扩展会打架吗？
  不会，只要别名和扩展的标识符不重名。重名时插件会在控制台警告 —— 不过本插件的标识符只有一个（identifier），冲突面很小。
• 问：支持 Folia 吗？
  支持，folia-supported: true，且全插件不调度任何任务，是 Folia 上兼容成本最低的那类插件。
  

声明​

• 本插件为原创作品，保留所有权利，默认不允许转载与整合。如需转载或整合进服务端整合包，请先通过上方交流群或作者 QQ 联系获取授权。
• 本插件未使用任何混淆手段，欢迎安全审查。
• 本插件不含任何后门、病毒或远程控制代码，不收集任何玩家数据。