Placeholder API

https://placeholders.pb4.eu
Admin
Placeholder API is a JIJ-able API for creating and parsing placeholders within strings and Minecraft...
Tokens:18,259
Snippets:76
Trust Score:6.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Placeholder API Developer Guide

Source: https://placeholders.pb4.eu/dev/getting-started

This section outlines the developer-focused aspects of the Placeholder API. It covers essential steps for getting started, adding custom placeholders, and understanding the parsing mechanisms.

```APIDOC
Getting Started:
  - Provides initial setup and integration steps for developers.

Adding Placeholders:
  - Details on how to create and register new placeholder types.
  - Includes information on placeholder definitions and their properties.

Parsing Placeholders:
  - Explains the process of how text with placeholders is parsed.
  - Covers the logic for resolving placeholder values.

Text Nodes and Node Parsers:
  - Describes the internal structure for handling text and parsing nodes.
  - Information on creating custom node parsers for specific text formats.

Using Simplified Text Format/TextParser:
  - Guide on utilizing the simplified text format for easier placeholder integration.
  - Details on the TextParser class and its methods.
```

--------------------------------

### Placeholder API - Developer Guide

Source: https://placeholders.pb4.eu/user/quicktext

Outlines the developer-focused aspects of the Placeholder API, covering getting started, adding and parsing placeholders, text nodes, and using the Simplified Text Format.

```plaintext
Placeholder API - Developer Guide:
  - Getting Started
  - Adding placeholders
  - Parsing placeholders
  - Text Nodes and Node Parsers
  - Using Simplified Text Format/TextParser
```

--------------------------------

### Placeholder API - User Guide

Source: https://placeholders.pb4.eu/user/quicktext

Provides an overview of the Placeholder API for users, including sections on using placeholders, default and mod-specific placeholder lists, and the QuickText format.

```plaintext
Placeholder API - User Guide:
  - Using placeholders
  - Default placeholder list
  - Mod placeholders list
  - QuickText Format:
    - Structure
    - List of available tags:
      - Colors
      - Decorations
      - Click events
      - Hover
      - Fonts
      - Inserting
      - Translations
      - Control keys
      - Gradients
      - Clear
  - Simplified Text Format
```

--------------------------------

### Placeholder API Developer Resources

Source: https://placeholders.pb4.eu/user/general

Provides links to developer-focused documentation for the Placeholder API, covering getting started, adding new placeholders, parsing placeholders, and working with text nodes and parsers.

```en
Getting Started: /dev/getting-started/
Adding Placeholders: /dev/adding-placeholders/
Parsing Placeholders: /dev/parsing-placeholders/
Text Nodes and Node Parsers: /dev/text-nodes/
Using Simplified Text Format/TextParser: /dev/text-format/
```

--------------------------------

### Java Node Parser Example with Player Context

Source: https://placeholders.pb4.eu/dev/text-nodes

Demonstrates how to use Node Parsers in Java with player context. It shows parsing a text node with a placeholder and converting it to formatted text.

```java
public class Example {

    // With player context
    public static void exampleContext(ServerPlayerEntity player) {
        NodeParser parser = NodeParser.merge(TextParserV1.DEFAULT, Placeholders.DEFAULT_PLACEHOLDER_GETTER);

        TextNode output = parser.parseNode("<rb>Hello %player:name%");
        // or
        // TextNode output = parser.parseNode(TextNode.of("<rb>Hello %player:name%"));
        // or (only way before 2.0.0-beta.4)
        // TextNode output = TextNode.asSingle(parser.parseNodes(TextNode.of("<rb>Hello %player:name%")));

        Text text = output.toText(PlaceholderContext.of(player));
        // or
        // Text text = output.toText(PlaceholderContext.of(player).asParserContext());
        // or
        // Text text = output.toText(ParserContext.of().with(PlaceholderContext.KEY, PlaceholderContext.of(player)));
        // or (only way before 2.0.0-beta.4)
        // Text text = output.toText(PlaceholderContext.of(player).asParserContext(), true);
    }

    // Without context
    public static void example() {
        NodeParser parser = NodeParser.merge(TextParserV1.DEFAULT, Placeholders.DEFAULT_PLACEHOLDER_GETTER);

        TextNode output = parser.parseNode("<rb>Hello user!");

        Text text = output.toText();
        // or
        // Text text = output.toText(ParserContext.of());
        // or (only way before 2.0.0-beta.4)
        // Text text = output.toText(ParserContext.of(), true);
    }
}
```

--------------------------------

### DirectTextNode Implementation

Source: https://placeholders.pb4.eu/dev/text-nodes

Example of implementing a DirectTextNode in Java, which represents non-transformable text and can be used for static placeholders. It implements the TextNode interface.

```Java
publicrecord DirectTextNode(Texttext)implementsTextNode{
@Override
publicTexttoText(ParserContextcontext,booleanremoveBackslash){
returnthis.text;
}
}
```

--------------------------------

### Get Off My Lawn ReServed Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

Placeholders for the 'Get Off My Lawn ReServed' mod, providing information about land claims. This includes lists of claim owners and trusted players, both as names and UUIDs, and detailed claim information with customizable text for different states.

```APIDOC
Get Off My Lawn ReServed Placeholders:

%goml:claim_owners [no owners text]% - Returns a list of claim owners. If no owners, displays the provided text.
%goml:claim_owners_uuid [no owners text]% - Returns a list of claim owners as UUIDs. If no owners, displays the provided text.
%goml:claim_trusted [no trusted text]% - Returns a list of trusted players. If no trusted players, displays the provided text.
%goml:claim_trusted_uuid [no trusted text]% - Returns a list of trusted players as UUIDs. If no trusted players, displays the provided text.
%goml:claim_info [no claim text]:[can build text]:[can't build text]% - Returns the info for a claim. Uses provided text for different states and populates variables: ${owners}, ${owners_uuid}, ${trusted}, ${trusted_uuid}, ${anchor}.
```

--------------------------------

### Include Placeholder API Dependency

Source: https://placeholders.pb4.eu/dev/getting-started

Add the placeholder-api as a dependency to your project using Groovy syntax. Replace `[VERSION]` with the desired version.

```groovy
dependencies{
// You will have other dependencies here too

modImplementationinclude("eu.pb4:placeholder-api:[VERSION]")
}
```

--------------------------------

### Placeholder API for Users

Source: https://placeholders.pb4.eu/index

Details on how users can leverage the Placeholder API for configuring mods and styling text.

```APIDOC
User Guide:
  - Configure mods uniformly without losing compatibility.
  - Utilize placeholders to dynamically change information display.
  - Simplified Text Format for readable styling without manual JSON.

Key Sections:
  - Using placeholders
  - Default placeholder list
  - Mod placeholder list
  - QuickText Format
  - Simplified Text Format
```

--------------------------------

### Add Nucleoid Maven Repository

Source: https://placeholders.pb4.eu/dev/getting-started

Configure your build file to include the Nucleoid maven repository. This allows your project to download artifacts from the Nucleoid repository.

```groovy
repositories{
// There might be other repos there too, just add it at the end
maven{url"https://maven.nucleoid.xyz/"
name"Nucleoid"
}
}
```

--------------------------------

### Placeholder Syntax and Usage

Source: https://placeholders.pb4.eu/user/general

Explains the general syntax for using placeholders, including the common `%placeholder%` format and variations like `{placeholder}` or `${placeholder}`. It details how placeholders can include categories, arguments, and how the format depends on the providing mod.

```en
Usage: `%placeholder%` or `{placeholder}` or `${placeholder}`
Format: `category:placeholder` or `category:placeholder argument`
Example: `%player:name%`
Argument Example: `%player:ping some_argument%`
```

--------------------------------

### Include Placeholder API Dependency (Kotlin)

Source: https://placeholders.pb4.eu/dev/getting-started

Add the placeholder-api as a dependency to your project using Kotlin syntax. Replace `[VERSION]` with the desired version.

```kotlin
dependencies{
// You will have other dependencies here too

modImplementation(include("eu.pb4:placeholder-api:[VERSION]"))
}
```

--------------------------------

### Add Nucleoid Maven Repository (Kotlin)

Source: https://placeholders.pb4.eu/dev/getting-started

Configure your build file to include the Nucleoid maven repository using Kotlin syntax. This allows your project to download artifacts from the Nucleoid repository.

```kotlin
repositories{
// There might be other repos there too, just add it at the end
maven("https://maven.nucleoid.xyz/"){name="Nucleoid"}
}
```

--------------------------------

### QuickText Format Structure

Source: https://placeholders.pb4.eu/user/quicktext

Explains the tag-based structure of the QuickText format, similar to HTML. It covers opening and closing tags, optional closing tags, and how arguments are handled, including inline and key-value pairs with various quoting mechanisms.

```APIDOC
QuickText Format:
  Structure:
    - Tag-based, similar to HTML.
    - Opening tags: `<tag>`
    - Closing tags: `</tag>` (closes last tag of type) or `<‍/‍>` (closes last opened tag).
    - Closing tags are optional; formatting continues until end of input or `</*>`.
    - Arguments:
      - Inline: `<tag#argument>`
      - Key-value: `<tag key:'value'>`
      - Mixed: Allowed, key-value arguments take precedence.
      - Argument quoting: `'`, `"`, ```. Matching start/end symbols.
      - Escaping quote characters: Prefix with `\` or double the character.
    - Plain text tags: Prefix with `\`.
    - Self-contained tags: Do not require closing tags (e.g., `<lang'item.minecraft.diamond'>`, `<key'key.jump'>`).

  Examples:
    - `<color#11dddd>%player</color><dark_gray>»</dark_gray><color#cccccc>${message}`
    - `<red>Hello<blue>world</blue>!</red>`
    - `<rainbow>Some`
    - `<color#FF3333>`
    - `<hovervalue:'Hello!'>`
```

--------------------------------

### Decoration Tags

Source: https://placeholders.pb4.eu/user/quicktext

Tags for applying text decorations like strikethrough, underline, italics, obfuscation, and bold.

```APIDOC
Decoration Tags:
  <strikethrough>/<st>
  <underline>/<underlined>
  <italic>/<i>
  <obfuscated>/<obf>
  <bold>/<b>
    - Note: These tags should be closed.
```

--------------------------------

### Click Event Tags

Source: https://placeholders.pb4.eu/user/quicktext

Tags that make text interactive, allowing actions like opening URLs, running commands, suggesting commands, copying to clipboard, or changing book pages.

```APIDOC
Click Event Tags:
  <clicktype:[TYPE]value:'[VALUE]'> or <click[TYPE]'[VALUE]'> or direct shortcut tags.
  Available Actions:
    - <clickopen_urlvalue'[VALUE]'>/<open_url'[VALUE]'>/<url'[VALUE]'>: Opens the provided URL.
    - <clickrun_command'[VALUE]'>/<run_cmd'[VALUE]'>: Runs a command as the player.
    - <clicksuggest_command'[VALUE]'>/<suggest_command'[VALUE]'>/<cmd'[VALUE]'>: Suggests a command to the player.
    - <clickcopy_to_clipboard'[VALUE]'>/<copy_to_clipboard'[VALUE]'>/<copy'[VALUE]'>: Copies text to the clipboard.
    - <clickchange_page'[VALUE]'>/<change_page'[VALUE]'>/<page'[VALUE]'>: Changes the page in a book.
    - [VALUE]: Targeted value (e.g., 'gamemode creative').
    - Danger: Limit to admin usage as they can cause harm.
    - Note: These tags should be closed.
```

--------------------------------

### Placeholder API Supported Mods

Source: https://placeholders.pb4.eu/user/general

Lists various Minecraft mods that integrate with and support the Placeholder API for displaying placeholders. Includes links to CurseForge, Modrinth, and GitHub for each mod.

```en
Styled Player List: CurseForge, Modrinth, Github
Styled Chat: CurseForge, Modrinth, Github
Holograms: CurseForge, Modrinth, Github
Player Events: CurseForge, Github
Discord4Fabric: CurseForge, Modrinth, Github
Fuji: Modrinth, Github
Solstice Essentials: CurseForge, Modrinth, Github
```

--------------------------------

### Placeholder API Overview

Source: https://placeholders.pb4.eu/index

Provides a general overview of the Placeholder API's functionality, including its placeholder format and support for simplified text formatting.

```APIDOC
Placeholder Format:
  %modid:type%
  %modid:type data% (prior to 1.19: %modid:type/data%)

Features:
  - Creation and parsing of placeholders within strings and Minecraft Text Components.
  - Simplified Text Format for user-friendly input in configs and chats.
  - Enhances mod compatibility by providing a unified placeholder system.
```

--------------------------------

### Control Key Tag

Source: https://placeholders.pb4.eu/user/quicktext

Displays information about player control keys, respecting their configurations.

```APIDOC
Control Key Tag:
  <keybind'[VALUE]'> or <keybindvalue:'[VALUE]'>
    - [VALUE]: Control key identifier.
    - Note: This tag is self-containing.
```

--------------------------------

### Placeholder API for Developers

Source: https://placeholders.pb4.eu/index

Information for developers on integrating and utilizing the Placeholder API within their mods.

```APIDOC
Developer Guide:
  - Achieve high mod compatibility by implementing a single API.
  - Use the placeholder parsing system for custom static or dynamic placeholders.
  - Leverage Simplified Text Format for enhanced user/admin experience.

Key Sections:
  - Getting Started
  - Adding placeholders
  - Parsing placeholders
  - TextNodes and NodeParsers
  - Using Simplified Text Format (TextParserV1)
```

--------------------------------

### Registering a Placeholder (Kotlin)

Source: https://placeholders.pb4.eu/dev/adding-placeholders

Shows the Kotlin equivalent of registering a placeholder using the `Placeholders.register` method. It highlights the concise syntax for lambda expressions in Kotlin.

```kotlin
Placeholders.register(Identifier("example","placeholder")){ctx,arg->
PlaceholderResult.value(Text.literal("Hello World!"))
}
```

--------------------------------

### Server Placeholders

Source: https://placeholders.pb4.eu/user/default-placeholders

Provides access to various server-specific information and metrics. These placeholders can be used to display real-time data about the server's performance, configuration, and player activity.

```APIDOC
Server Placeholders:

%server:tps%
  - Description: The server's Ticks Per Second (TPS).
  - Usage: Displays the current TPS. A value below 20 indicates server lag.

%server:tps_colored%
  - Description: The server's TPS, displayed with color coding.
  - Usage: Shows TPS with visual indicators for performance.

%server:mspt%
  - Description: The server's Milliseconds Per Tick (MSPT).
  - Usage: Displays the current MSPT. A value above 50 indicates server lag.

%server:mspt_colored%
  - Description: The server's MSPT, displayed with color coding.
  - Usage: Shows MSPT with visual indicators for performance.

%server:time [formatting]%
  - Description: The server's current time.
  - Parameters:
    - formatting (optional): A format string for the time display.
  - Usage: Displays server time, with optional custom formatting.

%server:uptime [formatting]%
  - Version: 2.1.2+
  - Description: The server's uptime.
  - Parameters:
    - formatting (optional): A format string for the uptime display.
  - Usage: Shows how long the server has been running, with optional custom formatting.

%server:version%
  - Description: The server's current version.
  - Usage: Displays the software version of the server.

%server:name%
  - Description: The server's configured name.
  - Usage: Displays the name assigned to the server.

%server:motd%
  - Description: The server's Message of the Day (MOTD).
  - Usage: Shows the message displayed to players upon joining.

%server:used_ram [gb]%
  - Description: The amount of RAM currently used by the server.
  - Parameters:
    - gb (optional): If present, displays RAM usage in gigabytes.
  - Usage: Shows current server RAM consumption, with an option for GB display.

%server:max_ram [gb]%
  - Description: The maximum amount of RAM allocated to the server.
  - Parameters:
    - gb (optional): If present, displays max RAM in gigabytes.
  - Usage: Shows the total available server RAM, with an option for GB display.

%server:online%
  - Description: The current number of players online.
  - Usage: Displays the count of active players.

%server:max_players%
  - Description: The maximum number of players allowed on the server.
  - Usage: Shows the server's player capacity.

%server:brand%
  - Version: 2.1.3+
  - Description: Returns the server's software brand (e.g., 'fabric', 'quilt').
  - Usage: Identifies the server's core software distribution.

%server:mod_count%
  - Version: 2.1.3+
  - Description: Returns the total number of installed mods.
  - Usage: Displays the count of active modifications.

%server:mod_version [modid]%
  - Description: Returns the version of a specified mod.
  - Parameters:
    - modid: The unique identifier of the mod.
  - Usage: Retrieves the version number for a particular mod.

%server:mod_name [modid]%
  - Description: Returns the name of a specified mod.
  - Parameters:
    - modid: The unique identifier of the mod.
  - Usage: Retrieves the display name for a particular mod.

%server:mod_description [modid]%
  - Description: Returns the description of a specified mod.
  - Parameters:
    - modid: The unique identifier of the mod.
  - Usage: Retrieves the descriptive text for a particular mod.

%server:objective_name_top [objective] [position]%
  - Description: Shows the name of the player at a specific rank in a scoreboard objective.
  - Parameters:
    - objective: The name of the scoreboard objective.
    - position: The rank (e.g., 1st, 2nd) to retrieve the player's name from.
  - Usage: Displays the name of the player holding a certain position in a scoreboard.

%server:objective_score_top [objective] [position]%
  - Description: Shows the score of the player at a specific rank in a scoreboard objective.
  - Parameters:
    - objective: The name of the scoreboard objective.
    - position: The rank (e.g., 1st, 2nd) to retrieve the score from.
  - Usage: Displays the score of the player holding a certain position in a scoreboard.

%server:objective_score_player [objective] [player]%
  - Description: Shows the score of a specified player in a scoreboard objective.
  - Parameters:
    - objective: The name of the scoreboard objective.
    - player: The username of the player whose score to retrieve.
  - Usage: Retrieves the score of a specific player for a given scoreboard objective.
```

--------------------------------

### Parse Text with TextParser

Source: https://placeholders.pb4.eu/dev/text-format

Demonstrates how to use the TextParserUtils.parseText method to format a given input string. This method is suitable for admin-provided configurations.

```java
String inputString="<red>Hello <rb>World</rb>!"

Text output=TextParserUtils.parseText(inputString);
```

--------------------------------

### Translation Tag

Source: https://placeholders.pb4.eu/user/quicktext

Inserts text from a lang file, supporting translation keys and optional arguments.

```APIDOC
Translation Tag:
  <lang[key][optionalarg1]...> or <langkey:[key]fallback:[fallback][optionalarg1]...>
    - [key]: Translation key.
    - [fallback]: Fallback text if key is missing.
    - [optional arg X]: Formatted arguments.
    - Note: This tag is self-containing.
```

--------------------------------

### Default Placeholder Contexts

Source: https://placeholders.pb4.eu/user/default-placeholders

This section outlines the default placeholders available in the Placeholder API, categorized by their context. It covers Player, World, and Server placeholders, along with notes on argument separation and version compatibility.

```APIDOC
Player Placeholders:
  - Description: Placeholders related to the player.
  - Usage: Typically used in contexts where a player is involved.

World Placeholders:
  - Description: Placeholders related to the game world.
  - Usage: Typically used in contexts where the world is relevant.

Server Placeholders:
  - Description: Placeholders related to the server.
  - Usage: Typically used in contexts where the server is relevant.

Notes:
  - Prior to version 1.19, arguments were separated with a slash ('/').
  - Ensure placeholders are used in the correct context with valid arguments and the latest API version.
```

--------------------------------

### PlaceholderResult Creation

Source: https://placeholders.pb4.eu/dev/adding-placeholders

Demonstrates how to create PlaceholderResult instances for valid and invalid placeholder returns. Use static methods like `value()` for successful returns and `invalid()` for errors.

```APIDOC
PlaceholderResult:
  value(text: Text) -> PlaceholderResult
    Creates a valid result with the provided Text object.

  value(text: String) -> PlaceholderResult
    Creates a valid result by parsing the input String with TextParser.

  invalid() -> PlaceholderResult
    Creates an invalid result without a specific reason.

  invalid(reason: String) -> PlaceholderResult
    Creates an invalid result with a specified reason string.
```

--------------------------------

### Control Key Tag

Source: https://placeholders.pb4.eu/user/text-format

Displays player control keybinds respecting their configuration.

```text-formatting
<keybind:[value]>
```

--------------------------------

### Color Tags

Source: https://placeholders.pb4.eu/user/quicktext

These tags are used to apply colors to text. They include specific color names and a universal tag for RGB values.

```APIDOC
Color Tags:
  <yellow>, <dark_blue>, <dark_purple>, <gold>, <red>, <aqua>, <gray>, <light_purple>, <white>, <dark_gray>, <green>, <dark_green>, <blue>, <dark_aqua>, <black>
  <color[VALUE]>, <colorvalue:[VALUE]>, <c[VALUE]>, <cvalue:[VALUE]>
    - [VALUE]: Vanilla color name or RGB color (e.g., #AABBCC).
    - Note: These tags should be closed.
```

--------------------------------

### Insert Tag

Source: https://placeholders.pb4.eu/user/quicktext

Creates clickable text that inserts its value into the player's chat message.

```APIDOC
Insert Tag:
  <insert'[VALUE]'>
    - [VALUE]: Text to insert (wrapped in single quotes).
    - Note: This tag should be closed.
```

--------------------------------

### Placeholder Context Variants

Source: https://placeholders.pb4.eu/dev/parsing-placeholders

Defines the different variants for creating a PlaceholderContext, specifying the dependencies and available placeholders for each context.

```APIDOC
PlaceholderContext.of(...)
  Variants:
    MinecraftServer:
      - May use placeholders that depend on the server
      - May use placeholders that depend on ServerCommandSource (Note: uses the command source from MinecraftServer.getCommandSource())
    GameProfile:
      - May use placeholders that depend on the server
      - May use placeholders that depend on ServerCommandSource (Note: creates a new dummy command source at (0,0,0))
      - May use placeholders that depend on GameProfile
    ServerPlayerEntity:
      - May use placeholders that depend on the server
      - May use placeholders that depend on ServerCommandSource
      - May use placeholders that depend on ServerWorld
      - May use placeholders that depend on ServerPlayerEntity
      - May use placeholders that depend on Entity
      - May use placeholders that depend on GameProfile
    ServerCommandSource:
      - May use placeholders that depend on the server
      - May use placeholders that depend on ServerCommandSource
      - May use placeholders that depend on ServerWorld
      - May use placeholders that depend on ServerPlayerEntity _only if the source has a player_
      - May use placeholders that depend on Entity _only if the source has an entity_
      - May use placeholders that depend on GameProfile _only if the source has a player_
    Entity:
      - May use placeholders that depend on the server
      - May use placeholders that depend on ServerCommandSource
      - May use placeholders that depend on ServerWorld
      - May use placeholders that depend on ServerPlayerEntity _only if the source has a player_
      - May use placeholders that depend on Entity
      - May use placeholders that depend on GameProfile _only if the source has a player_
```

--------------------------------

### Registering a Placeholder

Source: https://placeholders.pb4.eu/dev/adding-placeholders

Demonstrates how to register a new placeholder using the `Placeholders.register` method. This involves providing a unique identifier and a lambda function that handles the placeholder's logic.

```java
Placeholders.register(
newIdentifier("example","placeholder"),
(ctx,arg)->PlaceholderResult.value(Text.literal("Hello World!"))
);
```

--------------------------------

### PlayerEx Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

Provides placeholders for retrieving player level and ranking information using the PlayerEx mod.

```plaintext
%playerex:level%
%playerex:name_top [position]%
%playerex:level_top [position]%
```

--------------------------------

### Gradient Tags

Source: https://placeholders.pb4.eu/user/quicktext

Allows adding gradients to text with different types and color mixing options. Supports static text only.

```text
<gradient(type:[type])[color1][color2]...>
<gr(type:[type])[color1][color2]...>
  - Types: type:oklab (default), type:hvs, type:hard
  - Allows smooth color transitions.

<hard_gradient[color1][color2]...>
<hgr[color1][color2]...>
  - Allows color transitions without mixing.

<rainbow[frequency][saturation][offset]>
<rainbow f:[frequency] s:[saturation] o:[offset]>
<rb[...]> 
  - Simple rainbow gradient. Arguments are optional and take values between 0 and 1.
```

--------------------------------

### Color Tags

Source: https://placeholders.pb4.eu/user/text-format

Applies colors to text. Supports vanilla color names, aliases, and RGB values.

```text-formatting
<yellow>
<dark_blue>
<dark_purple>
<gold>
<red>
<aqua>
<gray>
<light_purple>
<white>
<dark_gray>
<green>
<dark_green>
<blue>
<dark_aqua>
<dark_green>
<black>
<color:[value]>
<c:[value]> (e.g., <color:#AABBCC>)
```

--------------------------------

### Fuji Mod Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

Placeholders for the Fuji mod, tracking player and server statistics related to mining, kills, movement, and playtime. Also includes placeholders for displaying items, inventory, and ender-chest contents.

```APIDOC
Fuji Mod Placeholders:

%fuji:player_mined% - Sum of mining blocks of a player.
%fuji:server_mined% - Sum of mining blocks of a server.
%fuji:player_placed% - Sum of placed blocks of a player.
%fuji:server_placed% - Sum of placed blocks of a server.
%fuji:player_killed% - Sum of killed entities of a player.
%fuji:server_killed% - Sum of killed entities of a server.
%fuji:player_moved% - Sum of moved distance of a player.
%fuji:server_moved% - Sum of moved distance of a server.
%fuji:player_playtime% - Sum of playtime of a player.
%fuji:server_playtime% - Sum of playtime of a server.
%fuji:item% - Create the display of main-hand item.
%fuji:inv% - Create the display of inventory.
%fuji:ender% - Create the display of ender-chest.
```

--------------------------------

### Translation Tag

Source: https://placeholders.pb4.eu/user/text-format

Inserts text from a language file, supporting optional arguments.

```text-formatting
<lang:[key]:[optionalarg1]:[optionalarg1]:...>
```

--------------------------------

### Parse Text with TextParser

Source: https://placeholders.pb4.eu/dev/text-format

Demonstrates how to use the TextParserUtils.parseText method to format a given input string in Kotlin. This method is suitable for admin-provided configurations.

```kotlin
val inputString="<red>Hello <rb>World</rb>!"

val output=TextParserUtils.parseText(inputString);
```

--------------------------------

### Hover Tags

Source: https://placeholders.pb4.eu/user/quicktext

Tags for adding hover effects to text, displaying additional information when the mouse hovers over the text.

```APIDOC
Hover Tags:
  <hovershow_text'[VALUE]'>/<hover'[VALUE]'>: Adds a simple text hover.
  <hovershow_item'[VALUE]'>: Adds a simple ItemStack hover (sNBT format).
  <hovershow_entity[type][UUID]'DisplayName'>: Adds an entity hover.
    - [VALUE]: Formatted text for hover.
    - Note: These tags should be closed.
```

--------------------------------

### Decoration Tags

Source: https://placeholders.pb4.eu/user/text-format

Applies text decorations like strikethrough, underline, italic, obfuscated, and bold.

```text-formatting
<strikethrough> or <st>
<underline> or <underlined>
<italic> or <i>
<obfuscated> or <obf>
<bold> or <b>
```

--------------------------------

### LuckPerms Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

Provides placeholders for retrieving player information managed by LuckPerms, such as prefixes, suffixes, group memberships, permissions, and meta values. Requires the LuckPerms Fabric PlaceholderAPI addon.

```plaintext
%luckperms:prefix%
%luckperms:suffix%
%luckperms:meta [meta key]%
%luckperms:meta_all [meta key]%
%luckperms:prefix_element [element]%
%luckperms:suffix_element [element]%
%luckperms:context%/%luckperms:context [context key]%
%luckperms:groups%
%luckperms:inherited_groups%
%luckperms:primary_group_name%
%luckperms:has_permission [permission]%
%luckperms:inherits_permission [permission]%
%luckperms:check_permission [permission]%
%luckperms:in_group [group]%
%luckperms:inherits_group [group]%
%luckperms:on_track [track]%
%luckperms:has_groups_on_track [track]%
%luckperms:highest_group_by_weight%
%luckperms:lowest_group_by_weight%
%luckperms:highest_inherited_group_by_weight%
%luckperms:lowest_inherited_group_by_weight%
%luckperms:current_group_on_track [track]%
%luckperms:next_group_on_track [track]%
%luckperms:previous_group_on_track [track]%
%luckperms:first_group_on_tracks [tracks]%
%luckperms:last_group_on_tracks [tracks]%
%luckperms:expiry_time [permission]%
%luckperms:inherited_expiry_time [permission]%
%luckperms:group_expiry_time [group name]%
%luckperms:inherited_group_expiry_time [group name]%
```

--------------------------------

### Insert Tag

Source: https://placeholders.pb4.eu/user/text-format

Creates clickable text that inserts a specified value into the player's chat message.

```text-formatting
<insert:[value]>
```

--------------------------------

### Placeholder API Simplified Text Format Structure

Source: https://placeholders.pb4.eu/user/text-format

Explains the fundamental structure of the Simplified Text Format, including the use of opening and closing tags, optional closing tags, and how to pass arguments to tags. It also covers escaping special characters and self-contained tags.

```APIDOC
Placeholder API Simplified Text Format:

Structure:
Formatting is built on the concept of tags.

Nesting Quotations:
In the rare circumstance you need to nest quotations, they must be escaped: `\'`. For example:
`<lang:'chat.type.team.sent':'<hover:\'<lang:chat.type.team.hover>\'><suggest_command:\'/teammsg '>${team}':'${displayName}':'${message}'>`

Tag Pairs:
Most tags come in pairs of a starting (`<tag>`) and closing one (`</tag>` for direct or `<‍/‍>` (2.1.3+) for automatic).
Closing tags are technically optional; without them, formatting continues until the end of the input text or a special `<reset>` tag.

Tag Arguments:
Some tags support arguments, passed by adding `:` after the tag name in the starting tag (e.g., `<color:#FF3333></color>`).
Arguments containing symbols like `:`, `<`, `>`, `%`, and spaces should be wrapped in single quotes (`'`). For example: `<hover:show_text:'<red>Hello!'>...`.

Escaping Tags:
To type `<tag>` as plain text, prefix it with a `\` symbol.

Examples:
* `<color:#11dddd>%player:displayname%</color><dark_gray>»</dark_gray><color:#cccccc>${message}`
* `<red>Hello<blue>world</blue>!</red>`
* `<rainbow>Some`

Self-Contained Tags:
These tags do not require closing ones and can also take arguments.

Few examples:
* `<lang:'item.minecraft.diamond'>`
* `<reset>`
```

--------------------------------

### PlaceholderAPI Static Patterns

Source: https://placeholders.pb4.eu/dev/parsing-placeholders

Describes the static patterns available in PlaceholderAPI for parsing placeholders. These patterns define the syntax for identifying placeholders within text.

```APIDOC
PlaceholderAPI Static Patterns:

- `Placeholders.PREDEFINED_PLACEHOLDER_PATTERN` (`${placeholder}`): Recommended for most cases, minimizes collision with other formatting.
- `Placeholders.ALT_PLACEHOLDER_PATTERN_CUSTOM` (`{placeholder}`): Alternative, but has a higher chance of colliding with user formatting.
- `Placeholders.PLACEHOLDER_PATTERN_CUSTOM` (`%placeholder%`): Similar to the default, but does not require a colon.
- `Placeholders.PLACEHOLDER_PATTERN` (`%category:placeholder%`): Used for default global placeholders, requires a category.
- `Placeholders.PLACEHOLDER_PATTERN_ALT` (`{category:placeholder}`): Alternative formatting for global placeholders, requires a category.
```

--------------------------------

### Hover Tags

Source: https://placeholders.pb4.eu/user/text-format

Adds hover effects to text, displaying additional information.

```text-formatting
<hover:show_text:[value]>
<hover:[value]>
<hover:show_item:[value]>
<hover:show_entity:[type]:[UUID]:'DisplayName'> (e.g., <hover:show_entity:minecraft\:bee:[UUID]:'DisplayName'>)
```

--------------------------------

### Click Event Tags

Source: https://placeholders.pb4.eu/user/text-format

Makes text interactive by triggering actions when clicked. Use with caution, recommended for admin usage.

```text-formatting
<click:open_url:[value]> or <open_url:[value]> or <url:[value]>
<click:run_command:[value]> or <run_cmd:[value]>
<click:suggest_command:[value]> or <suggest_command:[value]> or <cmd:[value]>
<click:copy_to_clipboard:[value]> or <copy_to_clipboard:[value]> or <copy:[value]>
<click:change_page:[value]> or <change_page:[value]> or <page:[value]>
```

--------------------------------

### AfkPlus Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

This section details the placeholders provided by the AfkPlus mod. These placeholders allow access to player AFK status, display names, AFK duration, reason, and invulnerability status, with configurable formatting options.

```APIDOC
AfkPlus Placeholders:

%afkplus:afk%
  - Returns a configurable "[AFK]" tag if the player is marked as AFK.

%afkplus:name% / %afkplus:display_name%
  - Returns a configurable replacement for %player:displayname% if the player is marked as AFK. This allows for backport formatting, and it can fully support LuckPerms Prefixes, and other mods. By default, it returns the standard %player:displayname% when not AFK, which is also configurable.

%afkplus:duration%
  - Returns the (HH-mm-SS.ss) duration since a player went AFK, or nothing. Configurable in a more human-readable format, i.e., 5 minutes, 3 seconds.

%afkplus:time%
  - Returns the time (yyyy-MM-dd_HH.mm.ss) since a player went AFK, or nothing.

%afkplus:reason%
  - Returns the reason why a player went AFK, or nothing.

%afkplus:invulnerable%
  - Returns a basic tag to display the status if a player is marked as "invulnerable" using the "disableDamage" features. It is also used internally under the default "[AFK]" tag method, with "[AFK:I]", for example.
```

--------------------------------

### World Placeholders

Source: https://placeholders.pb4.eu/user/default-placeholders

Provides access to various world-specific information. This includes game time, day, player counts, and mob populations. Some placeholders accept an optional group argument to filter mob counts.

```APIDOC
World Placeholders:

Valid Groups for mob counts: `monster`, `creature`, `ambient`, `axolotls`, `underground_water_creature`, `water_creature`, `water_ambient`, and `misc`.

%world:time%
  - The world's time (Format: `HH:MM`).

%world:time_alt%
  - The world's time (alternative formatting) (Format: `HH:MM AM/PM`).

%world:day%
  - The world's day.

%world:player_count%
  - The world's player count.

%world:mob_count% / %world:mob_count [group]%
  - Shows amount of spawned mobs.

%world:mob_cap% / %world:mob_cap [group]%
  - Shows maximum amount of mobs that can spawn is player's world.

%world:id%
  - The world's ID.

%world:name%
  - The world's name.
```

--------------------------------

### Java ColorNode Implementation

Source: https://placeholders.pb4.eu/dev/text-nodes

Demonstrates the implementation of a ColorNode in Java, which extends ParentNode to apply a specific text color. It includes methods for applying formatting, creating copies with new children, and handling dynamic sub-values.

```java
public final class ColorNode extends ParentNode {
    private final TextColor color;

    public ColorNode(TextNode[] children, TextColor color) {
        super(children);
        this.color = color;
    }

    @Override
    protected Text applyFormatting(MutableText out, ParserContext context) {
        return out.setStyle(out.getStyle().withColor(this.color));
    }

    @Override
    public ParentTextNode copyWith(TextNode[] children) {
        return new ColorNode(children, this.color);
    }

    // This one should be only override if you have dynamic sub-values, like HoverNode
    @Override
    public ParentTextNode copyWith(TextNode[] children, NodeParser parser) {
        return new ColorNode(children, this.color);
    }
}
```

--------------------------------

### Player Pronouns Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

Displays formatted or raw player pronouns. Supports a default value if pronouns are not set.

```plaintext
%playerpronouns:pronouns%
%playerpronouns:pronouns [default]%
%playerpronouns:raw_pronouns%
%playerpronouns:raw_pronouns [default]%
```

--------------------------------

### Text Placeholder API Expressions

Source: https://placeholders.pb4.eu/user/mod-placeholders

Enables mathematical expressions, conditional logic, and string padding within placeholders. Supports various comparison and formatting operations.

```plaintext
%expr:math [Math expressions and ${placeholder}s]%
%expr:ifeq [aIsMath] [a] [bIsMath] [b] [cIsMath] [c] [dIsMath] [d]%
%expr:iflt [a] [b] [cIsMath] [c] [dIsMath] [d]%
%expr:math [a] [b] [cIsMath] [c] [dIsMath] [d]%
%expr:pad [length] [str] [c]%
%expr:padleft [length] [str] [c]%
%expr:padright [length] [str] [c]%
%expr:padmatch [match] [str] [c]%
%expr:padmatchleft [match] [str] [c]%
%expr:padmatchright [match] [str] [c]%
```

--------------------------------

### Parse Text with Selected Tags

Source: https://placeholders.pb4.eu/dev/text-format

Shows how to parse text using only a selected set of tags by providing a TagParserGetter to the TextParserUtils.parseText method. This allows for more controlled text formatting.

```APIDOC
TextParserUtils.parseText(String, TextParserV1.TagParserGetter)
```

--------------------------------

### Font Tag

Source: https://placeholders.pb4.eu/user/quicktext

Allows changing the font of the text to any built-in or resource pack provided font.

```APIDOC
Font Tag:
  <font'[VALUE]'>
    - [VALUE]: Font name (e.g., 'default', 'uniform', 'alt').
    - Note: This tag should be closed.
```

--------------------------------

### Register Placeholder with Player Context (Java)

Source: https://placeholders.pb4.eu/dev/adding-placeholders

Registers a placeholder that requires player context. It checks if a player is present and returns their display name. If no player is found, it returns an invalid result.

```java
Placeholders.register(newIdentifier("player","displayname"),(ctx,arg)->{
if(!ctx.hasPlayer())
returnPlaceholderResult.invalid("No player!");

returnPlaceholderResult.value(ctx.getPlayer().getDisplayName());
});
```

--------------------------------

### Solstice Essentials AFK Placeholder

Source: https://placeholders.pb4.eu/user/mod-placeholders

Shows an AFK tag if the player is away from keyboard. This behavior is configurable.

```plaintext
%solstice:afk%
```

--------------------------------

### Format Player Message

Source: https://placeholders.pb4.eu/dev/parsing-placeholders

Formats a player message by replacing placeholders like `${playerName}` and `${message}` with actual player and message data. It takes the input text template, the player entity, and the message text as arguments.

```kotlin
objectStaticPlaceholders{
/**
     * Formats a player message according to [inputText]
     *
     * Example input:
     * ```
     * ${playerName} says "${message}"!
     * ```
     *
     * @param inputText The text that is parsed for placeholders.
     *                  Example input:
     *                  `${playerName} says "${message}"`
     *
     * @param player The player name used to replace the `${playerName}` variable in the input.
     *               Example input:
     *               the player who's name is `ThePlayerUsername`
     *
     * @param messageText The text used to replace the `${message}` variable in the input.
     *                    Example input:
     *                    `this is the message`
     *
     * @return The formatted message.
     *         Example return:
     *     ```
     *         ThePlayerUsername says "this is the message"!
     *     ```
     */
funformatPlayerMessage(inputText:Text?,player:ServerPlayerEntity,messageText:Text):Text{
valplaceholders=mapOf(
"message"tomessageText,// replace ${message} with the messageText
"playerName"toplayer.name,// replace ${playerName} with the player's name
)
returnPlaceholders.parseText(inputText,Placeholders.PREDEFINED_PLACEHOLDER_PATTERN,
placeholders)// parse the inputText
}
}
```

--------------------------------

### Clear Tag

Source: https://placeholders.pb4.eu/user/quicktext

Clears formatting within the tag without leaving visible tags, supporting placeholders. Can clear all formatting or specific types.

```text
<clear>
  - Removes all formatting.

<clearhover>
  - Removes all hovers.

<clearhovercolor>
  - Removes all hovers and colors.

Supported arguments: color, bold, italic, strikethrough, underline, hover, click, insertion, font, all.
```

--------------------------------

### Spark Server Performance Placeholders

Source: https://placeholders.pb4.eu/user/mod-placeholders

Provides server performance metrics including TPS, tick duration, and CPU usage for the system and process. Supports various time durations for data aggregation.

```plaintext
%spark:tps
%spark:tps duration%
%spark:tickduration%
%spark:tickduration [duration]%
%spark:cpu_system%
%spark:cpu_system [duration]%
%spark:cpu_process%
%spark:cpu_process [duration]%
```

--------------------------------

### Gradient Tags

Source: https://placeholders.pb4.eu/user/text-format

Allows adding gradients to text with different types: smooth multi-color, hard multi-color, and rainbow. Note that dynamic values are not supported.

```text-format
<gradient:[color1]:[color2]:...>
<gr:[color1]:[color2]:...>
<hard_gradient:[color1]:[color2]:...>
<hgr:[color1]:[color2]:...>
<rainbow:[frequency]:[saturation]:[offset]>
<rb:[...]> (Optional arguments: frequency, saturation, offset between 0 and 1)
```

--------------------------------

### Dynamic Placeholder Parsing in Java

Source: https://placeholders.pb4.eu/dev/parsing-placeholders

Demonstrates how to parse text using dynamic placeholders with a custom context in Java. This involves creating a map of identifiers to placeholder handlers and a pattern object, then utilizing the parseText method.

```java
PlaceholderMap<PlaceholderHandler> handlers = new HashMap<>();
// Add your custom handlers to the map

Pattern pattern = new Pattern();
// Configure your pattern

String textToParse = "Your text with placeholders";
PlaceholderContext context = new PlaceholderContext();
// Configure your context

PlaceholderGetter getter = new PlaceholderGetter(handlers, pattern);
String parsedText = getter.parseText(textToParse, context);

System.out.println(parsedText);
```
Tokens:
Raw