Placeholders - Refinery WIKI

xyz.refineryteam.refinerycore.api.text.Placeholders is a lightweight PlaceholderAPI-style resolver. Plugins register named placeholders once, then any string can reference them as %namespace_key% and get substituted before MiniMessage parsing. Unlike PlaceholderAPI there is no external dependency — the registry lives inside RefineryCore, so suite plugins share one namespace without each shipping their own expansion.

Registering a placeholder

EconomyExpansion.java

// Answers %economy_balance%
Placeholders.register("economy", "balance", (player, args) ->
    String.valueOf(Economy.getBalance(player)));

// With arguments: %myplugin_top:3% passes args = "3"
Placeholders.register("myplugin", "top", (player, args) ->
    Leaderboard.entry(Integer.parseInt(args)));

The resolver receives the viewing player (possibly null for console/global contexts) and anything after a colon in the placeholder body. Return "" rather than null for empty values.

Method	Description
`register(namespace, name, resolver)`	Registers a namespaced placeholder answering `%namespace_name%` — prefer this form to avoid collisions between plugins
`register(name, resolver)`	Registers an unnamespaced placeholder answering `%name%`
`unregister(namespace, name)` / `unregister(name)`	Removes a previously registered placeholder

Rendering placeholders

BroadcastTask.java

// Substitutes placeholders, then parses the result as MiniMessage:
Component text = Placeholders.render("<gray>Balance: <gold>%economy_balance%", player);

// Raw substitution only — for scoreboard lines, Discord webhooks, etc:
String plain = Placeholders.apply("Top player: %myplugin_top:1%", player);

Method	Description
`render(raw, player)`	Substitutes all known placeholders, then parses the result as MiniMessage into a `Component`
`apply(raw, player)`	Substitutes placeholders and returns the raw string, without MiniMessage parsing
`hasPlaceholders(raw)`	Whether any registered placeholder matches in the string

Resolution rules

Names are matched case-insensitively; namespaces are lowercased internally.
For a token like %economy_balance%, the resolver first tries an exact namespace split (economy + balance), then falls back to treating the whole body as a bare unnamespaced name.
Anything after a : inside the token is passed to the resolver as its args string (e.g. %myplugin_top:3% → "3").
Unknown placeholders are left verbatim, so other systems — or PlaceholderAPI itself, if installed — can still handle them.
If a resolver throws, the token resolves to an empty string instead of breaking the render.

Resolvers run synchronously wherever you call render/apply. Keep them cheap — don’t perform database queries or HTTP calls inside a resolver; precompute the value and read it from memory.

​Registering a placeholder

​Rendering placeholders

​Resolution rules

Registering a placeholder

Rendering placeholders

Resolution rules