Click actions

A clicks map binds click types to lists of actions.

clicks:
  left:
    - type: select
  shift-left:
    - type: select
    - type: command
      command: "warp <entry_id>"
      cooldown-ticks: 60
      cooldown-message: "<red>Wait a moment before warping again."
  shift-right:
    - type: clear-selection

The four click types are left, right, shift-left and shift-right.

Actions run as a chain

The list runs in order and stops at the first failure. That is what makes click-to-confirm work: the confirmation returns a denial, so the actions after it do not fire on the arming click, and do fire on the second one.

Add continue-on-failure: true to an action to carry on regardless.

Guards every action accepts

These are checked by the dispatcher before the action itself runs, so no action has to remember them.

permissionnode

Refuse unless the clicker holds the node. Use this when a control should be visible but refuse; use visible-if when it should not be there at all.

denied-messageMiniMessage

Shown when permission refuses. Defaults to a red "You cannot use that."

cooldown-ticksticksdefault 0

Per player, per action, per entry. Only a successful run starts the cooldown.

cooldown-messageMiniMessage

Shown while the cooldown is running.

confirm-messageMiniMessage

Turns the action into click-to-confirm. The first click stores an expiry on the session and returns a denial; a second click within the window runs it.

confirm-secondsnumberdefault 5

How long the armed confirmation lasts.

continue-on-failurebooleandefault false

Carry on down the chain even if this action fails or is denied.

Navigation

selectaction

Select the clicked entry. panel: names which panel's selection to set; without it, the panel that was clicked.

clear-selectionaction

Drop the selection. Takes the same optional panel:.

open-viewaction

Move this board, for this viewer only, to another view. Takes view: <namespace:id>.

next-pageaction

Advance a list panel. panel: names which one, since without it a pager would try to page itself.

previous-pageaction

The other direction, same panel: argument.

set-pageaction

Jump to page: <n>, counted from 1. Takes the same panel:.

resetaction

Return the board to its root-view and clear this player's selection, paging and state.

refreshaction

Redraw, dropping cached provider content so a provider is asked again.

closeaction

Stop rendering this board for this viewer.

Telling the player something

messageaction

Send message: to chat. Templated.

action-baraction

The same, on the action bar.

titleaction

title: and subtitle:, with fade-in-ms (250), stay-ms (2000) and fade-out-ms (250).

linkaction

Offer url: as a clickable chat link, labelled with message:. A link can only be handed to a player, never opened for them.

Doing something

commandaction

Run command:. executor: console runs it from console rather than as the player, which is how you grant something the player has no permission to grant themselves.

teleportaction

Takes world, x, y, z, yaw and pitch. Anything omitted keeps the player's current value, so y on its own lifts them where they stand.

set-stateaction

Write key: = value: (default true) on this viewer's session. Read it back with <state:key> in any templated string, or gate on it with a session-state condition.

toggle-stateaction

Flip key: between true and false. This is what a tab strip is built from.

customaction

Hand off to an ActionHandler another plugin registered, named by id:. Every other key on the action is passed through to it as an argument.

A worked example: click to confirm

- id: claim
  text: "<dark_gray>[ <green>Claim kit</green> <dark_gray>]"
  clicks:
    left:
      - type: command
        executor: console
        command: "kit starter <player>"
        permission: example.kits.starter
        denied-message: "<red>You have not unlocked this kit."
        confirm-message: "<yellow>Click again to claim."
        confirm-seconds: 4
        cooldown-ticks: 1200
        cooldown-message: "<red>You have already claimed this."
      - type: title
        title: "<green>Kit claimed"

The title never fires on the arming click, because the confirmation returned a denial and the chain stopped there.

Test an action safely

1. Use a non-destructive message action first to confirm the click type and hit region.
2. Add the action's permission and denial text, then test with an allowed and denied account.
3. Add confirmation and cooldown guards before a console command, teleport or external custom action.
4. Run /holopanels validate, reload, and test both the success and failure path.

For commands with irreversible effects, keep the confirm-message after testing. Confirmation and cooldown state is scoped to the viewer, board, view, panel, action type and selected entry.