Dynamic Content

Dynamic Content

Hudkit supports dynamic content through placeholder resolution and visibility controls, allowing you to display player-specific information and show/hide HUD elements programmatically.

PlaceholderResolver

Create custom placeholder resolvers by extending the abstract PlaceholderResolver class. This allows you to define what happens when a placeholder is referenced in your HUD definition.

Basic Example

Kotlin

import net.hudkit.api.document.placeholder.PlaceholderResolver
import net.kyori.adventure.audience.Audience
import net.kyori.adventure.text.Component
import net.minestom.server.entity.Player

class MyPlaceholderResolver : PlaceholderResolver() {
    override fun resolve(placeholder: String, audience: Audience): Component {
        return when (placeholder) {
            "player_name" -> (audience as Player).name
            "player_level" -> Component.text((audience as Player).level)
            "player_health" -> Component.text(String.format("%.1f", (audience as Player).health))
            "server_online" -> Component.text(MinecraftServer.getConnectionManager().onlinePlayers.size)
            else -> Component.text("?")
        }
    }
}

Java

import net.hudkit.api.document.placeholder.PlaceholderResolver;
import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.text.Component;
import net.minestom.server.entity.Player;

public class MyPlaceholderResolver extends PlaceholderResolver {
    @Override
    public Component resolve(String placeholder, Audience audience) {
        switch (placeholder) {
            case "player_name":
                return ((Player) audience).getName();
            case "player_level":
                return Component.text(((Player) audience).getLevel());
            case "player_health":
                return Component.text(String.format("%.1f", ((Player) audience).getHealth()));
            case "server_online":
                return Component.text(MinecraftServer.getConnectionManager().getOnlinePlayers().size());
            default:
                return Component.text("?");
        }
    }
}

Using Your Resolver

Kotlin

val manager = HudManager(
    studioOptions = StudioOptions.online("your-api-key"),
    renderOptions = RenderOptions.customPlaceholderResolver(MyPlaceholderResolver())
)

Java

HudManager manager = new HudManager(
    StudioOptions.online("your-api-key"),
    RenderOptions.customPlaceholderResolver(new MyPlaceholderResolver())
);

Showing and Hiding Elements

You can dynamically show and hide HUD elements using the show() and hide() methods on a Hud instance. Elements are identified by their key, which you define in Studio or the XML.

Hiding Elements

Kotlin

// Get the player's HUD instance
val hud = hudManager.getHud(player)

hud?.hide("health_bar")

Java

// Get the player's HUD instance
Hud hud = hudManager.getHud(player);

// Hide an element by key
if (hud != null) {
    hud.hide("health_bar");
}

Showing Elements

Kotlin

// Show a previously hidden element
hud?.show("health_bar")

Java

// Show a previously hidden element
if (hud != null) {
    hud.show("health_bar");
}

Visibility Behavior

When you hide an element, all its children (including nested elements) are also hidden. This also goes the other way, as showing an element only affects that specific key, if a parent element is still hidden, children remain hidden.

Triggering Re-renders

When placeholder values change and you want the HUD to update:

Kotlin

// Force all HUDs to re-render
hudManager.rerenderAllHuds()

// Re-render a specific player's HUD
hudManager.getHud(player)?.rerender()

Java

// Force all HUDs to re-render
hudManager.rerenderAllHuds();

// Re-render a specific player's HUD
Hud hud = hudManager.getHud(player);
if (hud != null) {
    hud.rerender();
}

Performance Considerations

• Keep placeholder resolve() functions FAST!
• Cache expensive computations when possible
• Avoid blocking operations or database calls in resolve()