Custom Functions

Argument resolution

Always resolve the wrapper through the context (context.parseWrapper(wrapper)) — never call wrapper.get() directly, since only the context knows the player and placeholder parser for the running invocation.

Return value

In most contexts the returned Object is converted to a string via String.valueOf(result) and substituted into the surrounding placeholder string. When a standalone $fn(...) call is the entire value of a text/component field (menu and item names/lore, titles, dialog labels — anywhere ComponentWrapper runs), the raw return value is integrated type-aware instead: an Adventure ComponentLike is spliced in directly, a StyleBuilderApplicable is applied as styling for the rest of the line, a single-element List is unwrapped, and a nested PlaceholderWrapper is resolved one level. Anything else becomes a string — and a string containing a MiniMessage tag (matched by <[^<>]+>) is deserialized and spliced in as a component, so a returned <red>, <#FFFFFF>, <gradient:…> or </bold> renders as formatting instead of literal text; strings with no tag are inserted as plain text and inherit the surrounding style. The same rule applies to every lore line. Note the detection is purely "contains a <…> pair", so literal angle-bracketed text in a returned value is handed to MiniMessage too. This lets a custom function return rich text rather than its toString().

A returned Component survives both paths: as a standalone value it is spliced in as a component, and when the $fn(...) call is embedded in surrounding text — where only a string can be substituted — it is serialized back to MiniMessage rather than dumped through toString(), so the formatting round-trips. Returning null still produces the literal "null", so prefer throwing ExecutableRunException for error cases.

Lifecycle — one instance per call site

A function instance is built once per inline call site and reused for every render. The wrapper that owns a $name(...) occurrence asks the factory to prepare the call, then keeps that prepared function and runs it again for each subsequent render, so the class lookup, constructor reflection, and argument wrapping (which for an $e(...) argument means recompiling the expression) happen once for the config string rather than once per render.

Preparation happens on first run, not at config-parse time: a config string is wrapped while it is read, which can be before the plugin is up and before the function registry exists. Two threads racing to prepare the same call is benign — the two instances are equivalent and the loser is dropped.

The consequence for function authors: your record is long-lived and shared across players and renders, possibly concurrently.

• Keep implementations stateless and thread-safe. Never cache per-player data (the executor, a resolved value, a running total) in a field — per-run state belongs to run(context) locals.

• Any mutable helper must be thread-confined or replaced by an immutable one. FormatNumberFunction keeps its DecimalFormat cache in a ThreadLocal<Map<String, DecimalFormat>> because DecimalFormat is mutable; FormatDateFunction uses a plain ConcurrentHashMap<String, DateTimeFormatter> because DateTimeFormatter is immutable and one instance per pattern serves every thread. Follow whichever pattern matches your helper.

The prepare SPI

Only relevant when implementing a custom PlatformFunctionFactory — the Paper factory already does this for you.

The default implementation simply delegates back to compute(name, rawArgs, parser), so a platform with nothing worth reusing needs no changes; the owner-aware overload defaults to the owner-blind one for the same reason. DefaultPaperFunctionFactory overrides both and caches the built PaperFunction behind a volatile field, building it lazily on the first compute call.

The owner is read from PluginContext.current() while the configuration file is deserialized and captured by the wrapper that claims the call — a render happens far from that read and cannot recover it. PluginContext.with(plugin, …) is what ConfigurationManager wraps every deserialization in; nesting is honoured, so one plugin's configuration pulling in another's does not misattribute either.