PlaceholderAPI

PlaceholderAPI

一个灵活且强大的占位符系统，专为 Hytale 服务器开发者设计。它支持轻松注册和提取字符串中的动态值，并具备缓存、玩家特定数据、参数和作用域上下文等功能。

更详细的使用示例请参见 GitHub。

功能特性

• 易于使用： 为 Java 和 Kotlin 开发者提供简单 API。
• 动态值： 支持玩家特定的占位符（访客敏感）。
• 缓存： 内置缓存与自动更新支持。
• 参数： 支持带参数的复杂占位符，如 %player_name<lc>%。
• 作用域： 作用域上下文（例如 Chat、Message）仅在需要时提供相关数据。
• Kotlin 优先： 为 Kotlin 开发者提供类型安全的 DSL 和扩展函数。

---

开始使用

要使用 API，首先需要获取 PlaceholderAPI 实例。

Java：

PlaceholderAPI api = PlaceholderAPI.getInstance();

Kotlin：

val api = PlaceholderAPI.getInstance()

---

使用方法

翻译字符串

要自动替换字符串中的所有占位符，请使用 translateString() 方法。

Java：

String result = api.translateString("Hello %player_display_name%!", player);

Kotlin：

val result = "Hello %player_display_name%!".translatePlaceholders(player)

---

注册占位符

静态占位符

返回当前服务器刻（tick）的占位符示例：

Kotlin DSL：

api.build<Int>("tick") {
    loader {
        Server.getInstance().tick
    }
}

访客敏感占位符

返回玩家名称的占位符示例：

Kotlin DSL：

api.build<String>("player_name") {
    visitorLoader {
        player.name
    }
}

---

高级特性

参数

占位符可以使用 %名称<参数1,参数2>% 语法接受参数。 示例：%player_name<lc>% 返回小写格式的名称。

作用域与上下文

作用域允许占位符仅在特定情况下可用（例如，%message% 仅在聊天事件中可用）。

---

内置占位符

占位符	描述	作用域
%player_display_name%	玩家的显示名称	全局
%player_gamemode%	玩家的游戏模式	全局
%player_x%、%player_y%、%player_z%	玩家坐标	全局
%server_online%	在线玩家数量	全局
%server_ram_used%	服务器内存使用量	全局
%time%	当前服务器时间	全局
%message%	聊天/消息内容	聊天/消息
%message_sender%	消息发送者	聊天/消息

---

Kotlin 支持

PlaceholderAPI 提供了用于注册占位符的类型安全 DSL 和便于集成的便捷扩展函数。