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

Kotlin Support

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