PlaceholderAPI

PlaceholderAPI

A flexible and powerful placeholder system for Hytale server developers. It allows for easy registration and retrieval of dynamic values in strings, with support for caching, player-specific data, parameters, and scoped contexts.

More detailed usage with examples can be found on github.

Features

• Easy to use: Simple API for both Java and Kotlin developers.
• Dynamic Values: Support for player-specific placeholders (Visitor-Sensitive).
• Caching: Built-in support for caching and automatic updates.
• Parameters: Support for complex placeholders with parameters like %player_name<lc>%.
• Scopes: Scoped contexts (e.g., Chat, Message) to provide relevant data only where needed.
• Kotlin First: Type-safe DSL and extension functions for Kotlin developers.

---

Getting Started

To use the API, you first need to get the PlaceholderAPI instance.

Java:

PlaceholderAPI api = PlaceholderAPI.getInstance();

Kotlin:

val api = PlaceholderAPI.getInstance()

---

Usage

Translating Strings

To replace all placeholders in a string automatically, use the translateString() method.

Java:

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

Kotlin:

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

---

Registering Placeholders

Static Placeholders

Example of a placeholder that returns the current server tick:

Kotlin DSL:

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

Visitor-Sensitive Placeholders

Example of a placeholder that returns the player's name:

Kotlin DSL:

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

---

Advanced Features

Parameters

Placeholders can accept parameters using the %name<param1,param2>% syntax. Example: %player_name<lc>% returns the name in lowercase.

Scopes & Contexts

Scopes allow placeholders to be available only in specific situations (e.g., %message% only available in chat events).

---

Built-in Placeholders

Placeholder	Description	Scope
%player_display_name%	Player's display name	Global
%player_gamemode%	Player's game mode	Global
%player_x%, %player_y%, %player_z%	Player coordinates	Global
%server_online%	Number of players online	Global
%server_ram_used%	Server RAM usage	Global
%time%	Current server time	Global
%message%	Chat/Message content	Chat/Message
%message_sender%	Sender of the message	Chat/Message

---

Kotlin Support

PlaceholderAPI offers a Type-safe DSL for registering placeholders and convenient Extension functions for easy integration.