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.