WiFlow的PlaceholderAPI

 

Hytale 的集中式占位符系统。 解析占位符、创建扩展、在插件之间共享数据。

可以将其理解为 Hytale 版的 PlaceholderAPI。

---

功能特性

• 通用占位符 - 在所有兼容插件中使用 {标识符_占位符} 语法
• 内置扩展 - 开箱即用地包含玩家和服务器占位符
• 远程扩展 - 在游戏中使用 /WPAPI exp 下载扩展
• 热加载 - 无需重启服务器即可加载和卸载扩展
• 高性能 - 模板缓存和 MethodHandle 反射，实现最小开销
• 公开 API - 其他插件可以解析占位符并创建自定义扩展

---

快速上手

/WPAPI list                     - 列出所有已加载的扩展
/WPAPI parse {player_name}      - 测试占位符解析
/WPAPI exp list                 - 浏览可用扩展
/WPAPI exp download luckperms   - 安装一个扩展
/WPAPI reload                   - 重新加载所有扩展

---

内置占位符

玩家

占位符	描述
{player_name}	玩家的用户名
{player_uuid}	玩家的 UUID
{player_world}	当前世界名称
{player_x}	X 坐标
{player_y}	Y 坐标
{player_z}	Z 坐标
{player_online}	"true" 或 "false"

服务器

占位符	描述
{server_online}	在线玩家数量
{server_max}	最大玩家容量
{server_tps}	服务器 TPS
{server_memory_used}	已用内存 (MB)
{server_memory_max}	最大内存 (MB)
{server_memory_percent}	内存使用率 %

---

可用扩展

直接在游戏内下载更多扩展：

扩展	占位符	必需插件
LuckPerms	prefix, suffix, group	LuckPerms
OrbisGuard	region, region_owners, region_members, flag_*	OrbisGuard
Economy	balance, balance_formatted	EconomySystem
Hyfaction	name, power, members, claims, role	Hyfaction
Essentials	homes, homes_max, warps	Essentials
CombatLog	active, time, attacker, attacker_type	CombatLog
KillingSpree	current, best, kills, deaths, kdr	KillingSpree
OrbisMines	name, reset_time, resetting, blocks_broken	OrbisMines
SimpleClaims	claim_owner, is_claimed, can_build, party_*	SimpleClaims

/WPAPI exp download all  - 安装所有可用扩展

---

第三方下载与数据存储

此插件从第三方网站下载扩展文件。工作原理如下：

下载源

扩展文件从 WiFlow 官方文档站点下载：

• API 端点: https://docs.wiflow.dev/api/ecloud/
• 扩展列表: https://docs.wiflow.dev/api/ecloud/expansions

所有扩展文件都托管在支持 HTTPS 加密的 Cloudflare Pages 基础设施上。

下载内容

• 扩展 JAR 文件（Java 插件代码）
• 扩展元数据（名称、版本、作者、描述）

数据存储位置

下载的扩展会保存在您服务器的本地：

mods/WiFlowPlaceholderAPI/expansions/   <- 下载的 JAR 文件
mods/WiFlowPlaceholderAPI/cache/        <- 缓存的扩展数据（自动过期）

不会向外部服务器上传或发送任何数据。该插件仅发起只读的 GET 请求以获取扩展文件。

安全措施

• 仅 HTTPS - 所有下载均使用加密的 HTTPS 连接
• 校验和验证 - 下载的文件在加载前会与 SHA-256 校验和进行比对验证
• 沙盒加载 - 扩展在具有有限权限的隔离类加载器中运行
• 开源 - 所有官方扩展的源代码均可在 GitHub 上获取
• 人工审查 - 所有市场扩展在发布前均经过人工审查

当您使用 /WPAPI exp download 命令时，扩展文件会从云端的 docs.wiflow.dev 下载。

---

所有命令

命令	描述
/WPAPI list	列出已加载的扩展
/WPAPI info <id>	显示扩展详情
/WPAPI parse <text>	解析文本中的占位符
/WPAPI reload	重新加载所有扩展
/WPAPI exp list [page]	浏览扩展
/WPAPI exp info <id>	显示扩展信息
`/WPAPI exp download <id	all>`
`/WPAPI exp update <id	all>`
/WPAPI exp status	显示扩展状态
/WPAPI exp refresh	刷新扩展列表
/WPAPI exp search <query>	搜索扩展

别名: /placeholderapi, /papi, /wfpapi

---

安装

Hytale/
└── mods/
    ├── WiFlowPlaceholderAPI-1.0.1.jar  <- 主插件
    └── WiFlowPlaceholderAPI/
        └── expansions/                  <- 下载的扩展存放于此
            ├── luckperms-1.1.0.jar
            └── orbisguard-1.1.0.jar

---

面向开发者

使用占位符

import com.wiflow.placeholderapi.WiFlowPlaceholderAPI;
import com.wiflow.placeholderapi.context.PlaceholderContext;

// 为玩家创建上下文
PlaceholderContext context = PlaceholderContext.builder()
    .player(player)
    .playerUuid(player.getPlayerRef().getUuid())
    .playerName(player.getPlayerRef().getUsername())
    .worldName(player.getWorld().getName())
    .build();

// 解析占位符
String result = WiFlowPlaceholderAPI.setPlaceholders(context, "Hello {player_name}!");
// 结果: "Hello Steve!"

创建自定义扩展

public class MyExpansion extends PlaceholderExpansion {

    @Override
    public String getIdentifier() { return "myplugin"; }

    @Override
    public String getAuthor() { return "YourName"; }

    @Override
    public String getVersion() { return "1.0.0"; }

    @Override
    public String onPlaceholderRequest(PlaceholderContext context, String params) {
        return switch (params) {
            case "score" -> getScore(context.getPlayerUuid());
            case "level" -> getLevel(context.getPlayerUuid());
            default -> null;
        };
    }
}

通过 ServiceLoader 注册：META-INF/services/com.wiflow.placeholderapi.expansion.PlaceholderExpansion

完整 API 文档 →

---

支持

有疑问或问题？加入 Discord 服务器 或联系 w1fl0w。