占位符

Hytale 占位符插件

一款为 Hytale 提供占位符系统的插件，类似于 Minecraft 的 PlaceholderAPI。此插件允许你在文本中使用占位符，它们将被替换为动态值。

版本

此模组/插件适用于游戏版本 "2026.01.17-4b0f30090"。它很可能也适用于其他版本——使用时请自行承担风险。一旦发布稳定版游戏，所有版本都将得到支持。

功能特性

• 解析格式为 %placeholder% 的占位符
• 注册来自其他插件的自定义占位符
• 内置常用值的占位符
• 为开发者提供简单的 API

服务器管理员使用指南

只需将插件安装到你的 Hytale 服务器中。该插件会自动注册默认占位符，你可以在服务器中使用它们。

默认占位符：

• %current_time% - 当前时间
• %current_date% - 当前日期
• %current_year% - 当前年份
• %current_datetime% - 当前日期时间

服务器占位符：

• %server_name% - 服务器名称
• %server_motd% - 服务器 MOTD（每日提示）
• %server_password% - 服务器密码
• %server_max_players% - 服务器玩家上限
• %server_max_view_radius% - 最大视野半径
• %server_default_world_name% - 默认世界名称
• %server_default_gamemode% - 默认游戏模式

玩家占位符（当提供玩家对象作为上下文时 → 必须是 PlayerRef）：

• %player_uuid% - 玩家的 UUID
• %player_name% - 玩家的名称
• %player_fall_distance% - 玩家当前下落距离
• %player_gamemode% - 玩家的游戏模式
• %player_language% - 玩家的语言
• %player_world_name% - 玩家当前所在的世界名称
• %player_world_uuid% - 玩家当前所在世界的 UUID
• %player_player_is_first_spawn% - 是否为玩家首次出生
• %player_x% - 玩家的 X 坐标
• %player_y% - 玩家的 Y 坐标
• %player_z% - 玩家的 Z 坐标
• %player_x_exact% - 玩家的精确 X 坐标
• %player_y_exact% - 玩家的精确 Y 坐标
• %player_z_exact% - 玩家的精确 Z 坐标
• %player_health% - 玩家的生命值
• %player_max_health% - 玩家的最大生命值
• %player_min_health% - 玩家的最小生命值
• %player_mana% - 玩家的魔力值
• %player_max_mana% - 玩家的最大魔力值
• %player_min_mana% - 玩家的最小魔力值
• %player_oxygen% - 玩家的氧气值
• %player_max_oxygen% - 玩家的最大氧气值
• %player_min_oxygen% - 玩家的最小氧气值
• %player_stamina% - 玩家的体力值
• %player_max_stamina% - 玩家的最大体力值
• %player_min_stamina% - 玩家的最小体力值
• %player_ammo% - 玩家的弹药量
• %player_max_ammo% - 玩家的最大弹药量
• %player_min_ammo% - 玩家的最小弹药量

配置文件

配置文件每 10 秒自动更新一次。

{
  "TimeFormat": "HH:mm:ss",
  "DateFormat": "dd.MM.yyyy",
  "DateTimeFormat": "dd.MM.yyyy HH:mm:ss"
}

命令

• /testplaceholders - 向玩家显示所有占位符及其值

开发者使用指南

将插件添加为依赖项

Gradle

在你的 build.gradle.kts 文件中添加插件作为依赖项：

dependencies {
    compileOnly(files("libs/Placeholders-1.1.0.jar"))
}

Maven

在你的 pom.xml 文件中添加插件作为依赖项：

<dependencies>
    <dependency>
        <groupId>com.texisoft</groupId>
        <artifactId>placeholderapi</artifactId>
        <version>1.1.0</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/libs/Placeholders-1.1.0-.jar</systemPath>
    </dependency>
</dependencies>

将名称更改为 .jar 文件的名称。如果需要，同时更改版本号（仅限 Maven）。.jar 文件必须放在 /libs 文件夹中。如果该文件夹不存在，请创建它。libs 文件夹与 src 文件夹位于同一层级。

注册自定义占位符

import com.texisoft.plugin.api.PlaceholderAPI;
import com.texisoft.plugin.api.Placeholder;
import com.texisoft.plugin.placeholders.DefaultPlaceholder;

// 获取 PlaceholderAPI 实例
PlaceholderAPI api = PlaceholderAPI.getInstance();

// 注册一个具有静态值的简单占位符
api.registerPlaceholder(DefaultPlaceholder.ofStatic("my_placeholder", "My Value"));

// 注册一个具有动态值的占位符
api.registerPlaceholder(new DefaultPlaceholder("my_dynamic_placeholder", context -> {
    // 你可以使用上下文来确定值
    // 例如，如果上下文是玩家，你可以获取玩家特定的值
    return "Dynamic Value";
}));

使用占位符解析文本

import com.texisoft.plugin.api.PlaceholderAPI;

// 获取 PlaceholderAPI 实例
PlaceholderAPI api = PlaceholderAPI.getInstance();

// 解析带有占位符的文本
String text = "Welcome to %server_name%!";
String parsed = api.parse(text, null);

// 如果你有玩家特定的占位符，你可以将玩家作为上下文传递。目前必须是 `PlayerRef`
// String parsed = api.parse(text, playerRef);

创建自定义占位符实现

你可以创建自己的 Placeholder 接口实现：

import com.texisoft.plugin.api.Placeholder;

public class MyCustomPlaceholder implements Placeholder {
    @Override
    public String getIdentifier() {
        return "my_custom_placeholder";
    }

    @Override
    public String getValue(Object context) {
        // 在此实现你的自定义逻辑
        return "Custom Value";
    }
}

// 注册你的自定义占位符
PlaceholderAPI.getInstance().registerPlaceholder(new MyCustomPlaceholder());

使用 PlayerPlaceholder 进行动态数据提取

插件包含一个 PlayerPlaceholder 类，可以使用反射从玩家对象中动态提取数据。当你希望在事先不知道玩家对象具体结构的情况下访问其属性时，这非常有用。

import com.texisoft.plugin.placeholders.PlayerPlaceholder;

// 创建一个从玩家对象中提取 "name" 属性的占位符
PlayerPlaceholder namePlaceholder = PlayerPlaceholder.of("player_name", "name", "Unknown Player");

// 创建一个提取嵌套属性（例如 "location.x"）的占位符
PlayerPlaceholder xPlaceholder = PlayerPlaceholder.of("player_x", "location.x", "0");

// 注册占位符
PlaceholderAPI api = PlaceholderAPI.getInstance();
api.registerPlaceholder(namePlaceholder);
api.registerPlaceholder(xPlaceholder);

// 在文本中使用占位符
String text = "Player %player_name% is at X: %player_x%";
String parsed = api.parse(text, playerObject);

PlayerPlaceholder 类尝试多种方法来提取数据：

1. 使用 getter 方法（例如，对于 "name" 属性使用 getName()）
2. 对于布尔属性使用 "is" 方法（例如，对于 "op" 属性使用 isOp()）
3. 如果方法不可用，则直接访问字段

它还支持遍历对象层级以获取嵌套属性（例如 "location.x"）。