Placeholders Plugin for Hytale

A plugin that provides a placeholder system for Hytale, similar to PlaceholderAPI for Minecraft. This plugin allows you to use placeholders in text, which will be replaced with dynamic values.

Version

This mod/plugin is made for the game version "2026.01.17-4b0f30090". It is very likely to be usable for other versions - at your own risk. As soon as a stable game version is released, all versions will be supported.

Features

Parse placeholders in the format %placeholder%
Register custom placeholders from other plugins
Built-in placeholders for common values
Simple API for developers

Usage for Server Owners

Simply install the plugin in your Hytale server. The plugin will automatically register default placeholders that you can use in your server.

Default placeholders:

%current_time% - The current time
%current_date% - The current date
%current_year% - The current year
%current_datetime% - The current datetime

Server placeholders:

%server_name% - The server name
%server_motd% - The server motd
%server_password% - The server password
%server_max_players% - The server player limit
%server_max_view_radius% - The max view radius
%server_default_world_name% - The default world name
%server_default_gamemode% - The default game mode

Player placeholders (when a player object is provided as context → Must be a PlayerRef):

%player_uuid% - The UUID of the player
%player_name% - The name of the player
%player_fall_distance% - The current fall distance of the player
%player_gamemode% - The game mode of the player
%player_language% - The language of the player
%player_world_name% - The current world name the player is in
%player_world_uuid% - The current world UUID the player is in
%player_player_is_first_spawn% - Is first spawn of player
%player_x% - The x coordinate of the player
%player_y% - The y coordinate of the player
%player_z% - The z coordinate of the player
%player_x_exact% - The exact x coordinate of the player
%player_y_exact% - The exact y coordinate of the player
%player_z_exact% - The exact z coordinate of the player
%player_health% - The health of the player
%player_max_health% - The max health of the player
%player_min_health% - The min health of the player
%player_mana% - The mana of the player
%player_max_mana% - The max mana of the player
%player_min_mana% - The min mana of the player
%player_oxygen% - The oxygen of the player
%player_max_oxygen% - The max oxygen of the player
%player_min_oxygen% - The min oxygen of the player
%player_stamina% - The stamina of the player
%player_max_stamina% - The max stamina of the player
%player_min_stamina% - The min stamina of the player
%player_ammo% - The ammo of the player
%player_max_ammo% - The max ammo of the player
%player_min_ammo% - The min ammo of the player

Config

Config updates all 10 seconds automatically.

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

Commands

/testplaceholders - Shows all placeholders with values to the player

Usage for Developers

Adding the Plugin as a Dependency

Gradle

Add the plugin as a dependency in your build.gradle.kts file:

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

Maven

Add the plugin as a dependency in your 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>

Change the name to the name of the .jar file If needed change the version too (maven only) The .jar file has to be in the /libs folder. Create it if it is not present. The libs folder is in the same depth as the src folder

Registering Custom Placeholders

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

// Get the PlaceholderAPI instance
PlaceholderAPI api = PlaceholderAPI.getInstance();

// Register a simple placeholder with a static value
api.registerPlaceholder(DefaultPlaceholder.ofStatic("my_placeholder", "My Value"));

// Register a placeholder with a dynamic value
api.registerPlaceholder(new DefaultPlaceholder("my_dynamic_placeholder", context -> {
    // You can use the context to determine the value
    // For example, if the context is a player, you can get player-specific values
    return "Dynamic Value";
}));

Parsing Text with Placeholders

import com.texisoft.plugin.api.PlaceholderAPI;

// Get the PlaceholderAPI instance
PlaceholderAPI api = PlaceholderAPI.getInstance();

// Parse text with placeholders
String text = "Welcome to %server_name%!";
String parsed = api.parse(text, null);

// If you have player-specific placeholders, you can pass the player as the context. Current it must be a `PlayerRef`
// String parsed = api.parse(text, playerRef);

Creating Custom Placeholder Implementations

You can create your own implementation of the Placeholder interface:

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) {
        // Implement your custom logic here
        return "Custom Value";
    }
}

// Register your custom placeholder
PlaceholderAPI.getInstance().registerPlaceholder(new MyCustomPlaceholder());

Using PlayerPlaceholder for Dynamic Data Extraction

The plugin includes a PlayerPlaceholder class that can dynamically extract data from player objects using reflection. This is useful when you want to access properties of player objects without knowing their exact structure in advance.

import com.texisoft.plugin.placeholders.PlayerPlaceholder;

// Create a placeholder that extracts the "name" property from player objects
PlayerPlaceholder namePlaceholder = PlayerPlaceholder.of("player_name", "name", "Unknown Player");

// Create a placeholder that extracts a nested property (e.g., "location.x")
PlayerPlaceholder xPlaceholder = PlayerPlaceholder.of("player_x", "location.x", "0");

// Register the placeholders
PlaceholderAPI api = PlaceholderAPI.getInstance();
api.registerPlaceholder(namePlaceholder);
api.registerPlaceholder(xPlaceholder);

// Use the placeholders in text
String text = "Player %player_name% is at X: %player_x%";
String parsed = api.parse(text, playerObject);

The PlayerPlaceholder class tries multiple approaches to extract data:

Using getter methods (e.g., getName() for "name" property)
Using "is" methods for boolean properties (e.g., isOp() for "op" property)
Using direct field access if methods are not available

It also supports nested properties (e.g., "location.x") by traversing the object hierarchy.