PlaceholderAPI——用于在 Minecraft 中替换动态数据的插件
PlaceholderAPI(PAPI)是一款 Minecraft 服务器插件,可将玩家名称、余额等动态数据显示在聊天、计分板中。本文介绍占位符格式、通过 eCloud 安装扩展的方法,以及主要命令和配置项。
PlaceholderAPI(PAPI)是一款 Minecraft 服务器插件,可将玩家名称、余额等动态数据显示在聊天、计分板中。本文介绍占位符格式、通过 eCloud 安装扩展的方法,以及主要命令和配置项。
PlaceholderAPI——用于在 Minecraft 中替换动态数据的插件
本文测试与撰写时所用的 Minecraft 版本:26.1.2
支持的版本范围:1.8.x – 26.1.x
PlaceholderAPI(简称 PAPI)是一款 Minecraft 服务器插件,用于将文本中的特殊标记替换为动态数值。它本身不会输出任何内容:它是一个在字符串中查找形如 %player_name% 这样标记的引擎,并将其替换为实际数值——玩家名称、余额、等级、服务器在线人数等。数据本身由各个模块(扩展)提供,PAPI 只负责执行替换。因此,聊天、计分板、Tab 列表和菜单插件都能以同一种格式读取数值,而无需自己的语法。
占位符格式
占位符写在两个百分号之间: %<розширення>_<параметр>%。下划线前面的部分是扩展名称,后面是具体参数。例如, %player_name% 返回玩家名称,而 %server_online% 返回在线玩家数量。
只有在接收方插件主动调用时,替换才会生效。如果某个插件不支持 PAPI,其消息中的标记将保留为普通文本。可以用解析命令检查单个占位符:
/papi parse me %player_name%
如果返回的是标记文本本身而不是数值,说明所需的扩展不存在,或者来源插件被禁用了。
扩展与 eCloud
PlaceholderAPI 开箱即用时不包含任何占位符——它们全部来自扩展。有些内置于来源插件中,会在服务器启动时自动注册;另一些则以独立的 jar 文件形式存放在扩展云(eCloud)中,需要安装到 /plugins/PlaceholderAPI/expansions/ 目录。
所需的扩展可以直接在游戏内下载:
/papi ecloud download <розширення>
/papi reload
通过该命令只能下载经过验证的扩展——这是防范恶意代码的保护措施。未经验证的扩展需要手动安装:从网站下载 jar 文件并放入扩展目录。
关于访问 eCloud:如果主机或防火墙阻止了外部连接,通过命令下载将无法工作——此时需要手动添加扩展。
命令
所有命令都以 /papi 开头。默认情况下仅管理员可用;单独的权限通过 placeholderapi.* 节点分配。
命令 | 用途 |
| 为指定玩家解析文本中的占位符 |
| 为两名玩家解析关系型占位符 |
| 显示当前启用的扩展 |
| 查看指定扩展的信息 |
| 从云端下载扩展 |
| 列出某个扩展的占位符 |
| 重新加载插件和配置 |
| 查看已安装插件的版本 |
配置
在 config.yml 中,只有少数几个参数值得修改:
参数 | 作用 |
| 与 eCloud 的连接。 |
| 占位符逻辑值的显示文本;可替换为“是/否” |
| 相应占位符的日期和时间格式 |
| 启动时检查插件更新并通知管理员 |
文件中其余的值均为内部使用(扩展保护、Adventure 组件中的替换模式、调试),默认情况下无需改动。
结语
PlaceholderAPI 提供了一种数百个插件都能识别的统一数据替换格式:无需为每个插件单独开发对接,只需一行包含占位符的文本即可。对于依赖动态数据实现聊天、Tab 列表、计分板或菜单功能的 Minecraft 服务器管理员而言,这是必备工具;而在单人游戏中则没有用武之地。
安装
一次典型安装大约 5 分钟。流程相同，只是 Loader 和对应构建不同。
- 1Stop your Minecraft server.
- 2Drop the plugin .jar into the server /plugins folder.
- 3Start the server once so the plugin generates its config files.
- 4Edit /plugins/<name>/config.yml as needed, then run /reload confirm or restart.
