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.