Actions
AstralHeads#onEnable registers three PaperActions, one per record class in com.astralrealms.heads.action:
All three use the plain registerAction call, not registerActionGlobally — so, unlike some other products' action sets, they resolve only inside action lists that AstralHeads' own configuration loader parses (its menus/dialogs blueprints). Every argument is declared as a PlaceholderWrapper record component and resolved with context.parseWrapper(...) when the action runs, so each accepts a literal or a placeholder (typically %head_id% from a rendered head item). All three act on context.executor().
search-heads
Searches the catalog for term and opens menu with the results, for the executing player.
Arg | Type | Description |
|---|---|---|
| String placeholder | The search term, passed to |
| String | The menu blueprint id to open with the results (e.g. |
Calls plugin.heads().search(term) (see Overview — indexing & search), then plugin.menus().computeAndOpen(player, menu, Map.of("heads", result)) — the matched HeadEntity collection is passed in as the open parameter heads. On either a search or menu-open failure, the player is sent a literal (non-messages.yml) error string and the failure is logged; there is no messages.yml key for either path — unlike /heads search, which sends unexpected-error for both failure cases.
toggle-favorite
Toggles whether entity is in the executing player's favorites list.
Arg | Type | Description |
|---|---|---|
|
| The head to favorite/unfavorite, typically |
Looks up the executor's HeadPlayerData via SyncAPI#findData; if present, adds or removes the head's uniqueId from its favorites set (mutating the loaded AstralSync data in place — no explicit save call, no success message). If the player has no HeadPlayerData loaded, sends unexpected-error and makes no change. The resulting state is exposed back via %head_favorite% — see Placeholders.
buy-head
Buys head for the executing player, per Configuration — config.yml pricing.
Arg | Type | Description |
|---|---|---|
|
| The head to buy, typically |
Looks up config.yml's prices entry for the head's Source; if none, sends not-for-sale and stops. Otherwise withdraws the price through EconomyService#withdraw (looked up via AstralPaperAPI.getService; if the service isn't registered at all, sends unexpected-error). On a failed or refused withdrawal (async exception, or insufficient funds) sends unexpected-error/not-enough-funds respectively. On success it gives the head's ItemStack via MailboxService if that service is registered, otherwise adds it directly to the player's inventory (dropping any overflow at the player's feet), then sends head-bought with %head_name%, %price%, and %currency% filled in from the price entry.
Action Summary Table
ID | Arguments | Effect |
|---|---|---|
|
| Searches the catalog and opens |
|
| Toggles |
|
| Withdraws its configured price and gives |
See also
AstralCore Actions — the
[action-id] <argument> <param=value>syntax and globaldelay/asyncparameters shared by every action on the network.Configuration —
config.yml— thepricesmapbuy-headreads.Placeholders —
%head_id%,%head_favorite%,%head_price%, typically these actions' arguments or the state they toggle.Commands —
/heads search, the command equivalent ofsearch-heads.