占位符 (PHAR)

占位符 (PHAR)

一个现代化的占位符应用程序接口

图书馆

Placeholdar (PHAR)

此模组将不再频繁更新，建议改用 Placeholder API

Placeholdar 是为 Hytale 模组设计的简单占位符系统。它提供解析工具和扩展框架，模组可以注册自己的占位符。

如果你曾使用过 Minecraft 的 PlaceholderAPI (papi) 插件，对此会感到熟悉。

快速开始

命令

/phar list
/phar enable
/phar disable
/phar test %player_name%

内置占位符

外部插件

EconomyAPI

我也为部分插件自行添加了支持，如果插件开发者希望实现官方版本，请联系我移除这些实现，以免出现错误。

TheEconomy
EcoTale - Economy
Luckperms

  • 使用 /phar enable (theeconomy 或 ecotale) 启用这些扩展

玩家占位符

标识符：player

所有玩家占位符都需要玩家上下文才能工作。

占位符 描述 示例输出
%player_uuid% 玩家的唯一 ID 123e4567-e89b-12d3-a456-426614174000
%player_name% 玩家显示名称 Sennecoolgames
%player_gamemode% 玩家当前游戏模式 Adventure
%player_language% 玩家语言设置 en_US
%player_world_name% 玩家所在世界名称 default
%player_world_uuid% 玩家所在世界的 UUID 123e4567-e89b-12d3-a456-426614174000
%player_is_first_spawn% 是否为玩家首次出生 true 或 false
%player_fall_distance% 玩家当前下落距离（四舍五入） 15
%player_fall_distance_exact% 玩家当前下落距离（精确值） 15.234

位置占位符

占位符 描述 示例输出
%player_x% 玩家 X 坐标（四舍五入） 125
%player_x_exact% 玩家 X 坐标（精确值） 125.67
%player_y% 玩家 Y 坐标（四舍五入） 64
%player_y_exact% 玩家 Y 坐标（精确值） 64.0
%player_z% 玩家 Z 坐标（四舍五入） -89
%player_z_exact% 玩家 Z 坐标（精确值） -89.12

生命值占位符

占位符 描述 示例输出
%player_health% 玩家当前生命值 20.0
%player_max_health% 玩家最大生命值 20.0
%player_min_health% 玩家最小生命值 0.0

魔法值占位符

占位符 描述 示例输出
%player_mana% 玩家当前魔法值 100.0
%player_max_mana% 玩家最大魔法值 100.0
%player_min_mana% 玩家最小魔法值 0.0

氧气值占位符

占位符 描述 示例输出
%player_oxygen% 玩家当前氧气值 300.0
%player_max_oxygen% 玩家最大氧气值 300.0
%player_min_oxygen% 玩家最小氧气值 0.0

体力值占位符

占位符 描述 示例输出
%player_stamina% 玩家当前体力值 100.0
%player_max_stamina% 玩家最大体力值 100.0
%player_min_stamina% 玩家最小体力值 0.0

弹药占位符

占位符 描述 示例输出
%player_ammo% 玩家当前弹药量 30.0
%player_max_ammo% 玩家最大弹药量 30.0
%player_min_ammo% 玩家最小弹药量 0.0

服务器占位符

标识符：server

服务器占位符无需玩家上下文即可工作。

服务器信息

占位符 描述 示例输出
%server_name% 服务器名称 My Hytale Server
%server_motd% 服务器每日提示 Welcome to my server!
%server_password% 服务器密码（如果设置） secret123
%server_players% 在线玩家数量 4
%server_max_players% 最大玩家数量 10
%server_default_world% 默认世界名称 default
%server_default_gamemode% 默认游戏模式 Adventure

时间与日期占位符

占位符 描述 示例输出
%server_time% 当前时间 14:35:42
%server_date% 当前日期 2026-01-30
%server_datetime% 当前日期和时间 2026-01-30 14:35:42
%server_uptime% 服务器运行时间 02:15:30:45（天数:小时:分钟:秒）

资源使用占位符

占位符 描述 示例输出
%server_memory_used_mb% 当前已用内存（MB） 512
%server_memory_free_mb% 当前可用内存（MB） 1536
%server_memory_max_mb% 最大可用内存（MB） 2048

扩展

EconomyAPI

可以在 EconomyAPI 页面 找到

Ecotale 占位符

/phar enable ecotale

占位符 描述 示例输出
%ecotale_balance% 玩家余额 100.0
%ecotale_formatted_balance% 玩家格式化余额 100.00

TheEconomy 占位符

/phar enable theeconomy

占位符 描述 示例输出
%theeconomy_balance% 玩家余额 100.0
%theeconomy_formatted_balance% 玩家格式化余额 $100

Luckperms 占位符

/phar enable luckperms

占位符 描述 示例输出
%luckperms_prefix% 玩家前缀 [Owner]
%luckperms_suffix% 玩家后缀 (OG)
%luckperms_group% 玩家主权限组 Owner
%luckperms_weight% 玩家最高权重 100
  • 希望你的插件出现在这里？请直接私信我或发表评论！

实现方法

使用 Placeholdar 解析占位符

使用 Placeholdar.parse() 替换文本中的占位符：

import com.sennecoolgames.placeholdar.Placeholdar;
import com.hypixel.hytale.server.core.universe.PlayerRef;

// 带玩家上下文解析
String message = "Balance: %mymod_balance%";
String parsedPlayer = Placeholdar.parse(message, playerRef);
// 如果作为可选依赖使用：
public static boolean PHARAvailable = false;
try {
   Class.forName("com.sennecoolgames.placeholdar.Placeholdar");
   economyExpansion = new EconomyExpansion();
   economyExpansion.register();
   PHARAvailable = true;
   getLogger().atInfo().log("Placeholdar support enabled!");
} catch (Exception e) {
   getLogger().atInfo().log("Not using Placeholdar because it is not available");
}

String parsedPlayer = PHARAvailable ? Placeholdar.parse(message, playerRef) : message;
// 结果："Balance: 1000.50"

// 不带玩家上下文解析
String parsedNoPlayer = Placeholdar.parse(message);
// 结果："Balance: %mymod_balance%"（无玩家，返回原始文本）

占位符可用于任何文本：

String message = Placeholdar.parse("Hello %player_name%, you are at %player_x%, %player_y%, %player_z%", playerRef);

不带玩家上下文：

String message = Placeholdar.parse("Server: %server_name% | Time: %server_time%");

创建 PlaceholdarExpansion

创建继承 PlaceholdarExpansion 的类：

import com.sennecoolgames.placeholdar.PlaceholdarExpansion;
import com.hypixel.hytale.server.core.universe.PlayerRef;
import javax.annotation.Nullable;
import javax.annotation.Nonnull;

public class EconomyExpansion extends PlaceholdarExpansion {

    @Override
    @Nonnull
    public String getIdentifier() {
        // 这将作为占位符的前缀（%mymod_placeholder%）
        return "MyMod";
    }

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

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

    @Override
    @Nullable
    public String onRequest(@Nullable PlayerRef player, @Nonnull String params) {
        if (player == null) {
            return null;
        }

        if (params.equalsIgnoreCase("balance")) {
            return String.valueOf(getBalance(player));
        }

        if (params.equalsIgnoreCase("formatted_balance")) {
            return String.valueOf(formatBalance(getBalance(player)));
        }

        return null;
    }
}

注册扩展

在插件的初始化中注册扩展：

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;

public class MyPlugin extends JavaPlugin {
    // 全局变量，用于知道 Placeholdar 是否启用/可用
    public static boolean PHARAvailable = false; 

    private EconomyExpansion economyExpansion;

    public MyPlugin(JavaPluginInit init) {
        super(init);
    }

// 如果 Placeholdar 不可用，不要导致插件崩溃
    try {
        Class.forName("com.sennecoolgames.placeholdar.Placeholdar");
        economyExpansion = new EconomyExpansion();
        economyExpansion.register();
        PapiAvailable = true;
        getLogger().atInfo().log("Placeholdar support enabled!");
    } catch (Exception e) {
        getLogger().atInfo().log("Not using Placeholdar because it is not available");
    }

    @Override
    protected void shutdown() {
        if (economyExpansion != null) {
            economyExpansion.unregister();
        }
    }
}

将 Placeholdar 添加为（可选）依赖项

如果你希望插件无论是否安装 Placeholdar 都能正常工作，请在注册前检查它是否存在：

步骤 1：更新 manifest 文件，将 Placeholdar 设为可选

在你的 manifest.json 中：

可选：

{
  "OptionalDependencies": {
    "Sennecoolgames:Placeholdar": ">=1.0.0"
  }
}

必需：

{
  "Dependencies": {
    "Sennecoolgames:Placeholdar": ">=1.0.0"
  }
}

要测试你的占位符，可以使用 /phar test 命令检查是否注册成功。

占位符格式

占位符遵循格式：%identifier_param%

  • identifier - 扩展的标识符（例如 "myeconomy"）
  • param - 传递给 onRequest() 的参数（例如 "balance"）

示例：%myeconomy_balance% 会调用经济扩展，参数为 "balance"。

示例

生命值扩展

public class HealthExpansion extends PlaceholdarExpansion {

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

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

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

    @Override
    @Nullable
    public String onRequest(@Nullable PlayerRef player, @Nonnull String params) {
        if (player == null) {
            return null;
        }

        if (params.equalsIgnoreCase("current")) {
            return String.valueOf(getCurrentHealth(player));
        }

        if (params.equalsIgnoreCase("max")) {
            return String.valueOf(getMaxHealth(player));
        }

        return null;
    }

    private float getCurrentHealth(PlayerRef player) {
        // 获取当前生命值
        return 20.0f;
    }

    private float getMaxHealth(PlayerRef player) {
        // 获取最大生命值
        return 20.0f;
    }
}

用法：%health_current% → "20"，%health_max% → "20"