Click Actions
Click actions allow holograms to respond when players interact with them. Actions are defined per page and per click type.
Click Types
| Click Type | Trigger |
|---|---|
LEFT |
Left-click (attack) |
RIGHT |
Right-click (interact) |
SHIFT_LEFT |
Shift + left-click |
SHIFT_RIGHT |
Shift + right-click |
In a hologram file the click types under actions are written exactly as above. Another key (a typo such as RIGHTT, or right in lower case) is kept in the file with its actions but never runs; the server log names it when the hologram loads and /mh page info lists it.
How Clicks Are Counted
- One action run per click. A vanilla right-click on an entity sends several packets (both hands, two interaction kinds); only the main-hand one counts. A left-click counts once.
- Reach. The player's eyes must be within
clickRange(default 6 blocks) of the hologram's origin, one of the page's lines, or the nearest point of the page's visible height. Clicks from farther away are ignored. - Cooldown. Each player has a cooldown of
clickCooldownTicks(default 5 ticks = 0.25 s) between counted clicks, so holding the button down does not repeat the actions. - Which page. The actions of the page the player is currently viewing run.
- Server thread. Actions run on the server thread, like commands, so they can safely change the world.
A page with actions gets invisible click targets over its whole visible height, so clicking anywhere on the hologram works, including the gaps between lines; icon, head and entity lines are clickable as well. The NPC of a #PLAYER: line is a real Taterzens entity and does not trigger hologram actions; click the lines above or below it.
Managing Actions
Add an Action
An unknown action type is refused with a list of the known types.
Remove an Action
The index is 1-based, the same number /mh page actions shows. An index past the last action is refused.
Clear All Actions
List Actions
Lists the actions with their 1-based index; click an entry to fill in its removeaction command.
Action Types
MESSAGE
Sends a chat message to the clicking player. Supports color codes.
Info
{player} is replaced with the clicking player's name after the color codes are processed, so the name is always shown exactly as written. Other placeholders are not resolved in messages.
COMMAND
Executes a command as the clicking player.
The command runs with the player's own permissions. The leading / is optional. {player} is not replaced in COMMAND actions; use CONSOLE when the command needs the player's name.
CONSOLE
Executes a command as the server console. Use {player} for the clicking player's name.
CONSOLE:give {player} diamond 1
CONSOLE:effect give {player} minecraft:speed 60 1
CONSOLE:say {player} clicked the hologram!
{player} becomes the player's name only when it is a plain Minecraft name (letters, digits and _, at most 16 characters). Any other name (possible on offline-mode servers) is replaced by the player's UUID instead, so a crafted name can never inject a selector or extra command arguments.
Warning
Console commands run with full server permissions. Be careful with what commands you expose to players via hologram clicks.
TELEPORT
Teleports the player to the given coordinates.
TELEPORT:minecraft:overworld:100:65:-200
TELEPORT:minecraft:the_nether:50:70:50:90:0
TELEPORT:the_end:0:64:0
TELEPORT:100:65:-200
Format: TELEPORT:[dimension:]x:y:z[:yaw[:pitch]]
- The numbers are read from the right, so namespaced dimension ids (
minecraft:the_nether,mymod:my_dimension) work. - A dimension without a namespace gets
minecraft:(the_end=minecraft:the_end). - Without a dimension, the player stays in their current dimension.
- Without yaw and pitch, the player keeps their current view direction.
- Invalid arguments or an unknown dimension are logged as a warning and skipped; the rest of the chain still runs.
SOUND
Plays a sound for the clicking player only.
SOUND:minecraft:entity.experience_orb.pickup:1.0:1.0
SOUND:minecraft:block.note_block.pling:0.5:2.0
SOUND:minecraft:ui.button.click
SOUND:mymod:custom.sound:0.8
Format: SOUND:sound_id[:volume[:pitch]]
| Parameter | Default | Description |
|---|---|---|
sound_id |
Required | Sound event id; namespaced ids from any mod work |
volume |
1.0 |
Volume (1.0 = normal, higher = audible from farther away) |
pitch |
1.0 |
Pitch (0.5 = low, 1.0 = normal, 2.0 = high) |
The numbers are read from the right, so one number is the volume and two numbers are volume and pitch. An id without a namespace gets minecraft:.
PERMISSION
Gates the action chain: if the player doesn't have the permission, they get the noPermission message from lang.json and all following actions are skipped.
This is useful for creating VIP-only click actions:
/mh page addaction shop 1 RIGHT PERMISSION:my.server.vip
/mh page addaction shop 1 RIGHT MESSAGE:&aWelcome, VIP!
/mh page addaction shop 1 RIGHT COMMAND:/vip-shop
If the player doesn't have my.server.vip, neither the message nor the command executes. See Permissions for how permission strings are checked.
NEXT_PAGE
Shows the next page of the hologram. Wraps from the last page back to page 1.
PREV_PAGE
Shows the previous page. Wraps from page 1 to the last page.
PAGE
Jumps to a specific page number (1-indexed). A page number that does not exist does nothing.
Custom Types
Other mods can register their own action types; see the Developer API. A hologram file that names a type which is not registered (for example after removing that mod) keeps the action: it does nothing, the server log names it each time the hologram is loaded, /mh page actions marks it as not registered, and saving the hologram writes it back under the same type name. Reinstalling the mod brings the action back. (1.3.0 saved such actions as NONE, losing the type; those cannot be restored.)
Action Chains
When a player clicks, all actions for that click type execute in order. If any action returns false (like a failed PERMISSION check), the chain stops and remaining actions are skipped.
Example: VIP Shop
# Right-click actions (executed in order):
/mh page addaction shop 1 RIGHT SOUND:minecraft:ui.button.click:1.0:1.0
/mh page addaction shop 1 RIGHT PERMISSION:my.server.vip
/mh page addaction shop 1 RIGHT MESSAGE:&aOpening VIP shop...
/mh page addaction shop 1 RIGHT COMMAND:/vip-shop
Execution flow:
- Play click sound (always)
- Check VIP permission
- Has permission: continue to message and command
- No permission: chain stops, no message or command
Example: Multi-Action Button
/mh page addaction portal 1 RIGHT SOUND:minecraft:block.portal.trigger:0.5:1.5
/mh page addaction portal 1 RIGHT MESSAGE:&5Teleporting...
/mh page addaction portal 1 RIGHT TELEPORT:minecraft:the_nether:0:70:0
Click Cooldown
A per-player cooldown keeps a held button from repeating the actions. Default: 5 ticks (0.25 seconds).
Configure in config.json:
Setting it to 10 means a player can trigger actions at most every 0.5 seconds. Config files from before 1.3.0 that still have the old default 1 are raised to 5 once when they are loaded.
Disabling Actions
Per Hologram
Clicks on a hologram with this flag are ignored.
Complete Example: Interactive Menu
# Create hologram
/mh hologram create menu
# Page 1 - Main Menu
/mh line set menu 1 1 &6&l=== Main Menu ===
/mh line add menu 1 #ICON:COMPASS
/mh line add menu 1 &eRight-click to browse
/mh line add menu 1 &7Shift+Right for VIP options
# Page 2 - Warps
/mh page add menu &b&l=== Warps ===
/mh line add menu 2 &7Left: Spawn | Right: Shop
/mh line add menu 2 &8Shift+Left: Back
# Page 3 - VIP
/mh page add menu &d&l=== VIP Menu ===
/mh line add menu 3 &7Right-click for rewards
/mh line add menu 3 &8Shift+Left: Back
# Page 1 actions
/mh page addaction menu 1 RIGHT NEXT_PAGE
/mh page addaction menu 1 SHIFT_RIGHT PERMISSION:server.vip
/mh page addaction menu 1 SHIFT_RIGHT PAGE:3
# Page 2 actions
/mh page addaction menu 2 LEFT COMMAND:/spawn
/mh page addaction menu 2 LEFT MESSAGE:&aTeleporting to spawn...
/mh page addaction menu 2 RIGHT COMMAND:/warp shop
/mh page addaction menu 2 RIGHT MESSAGE:&aTeleporting to shop...
/mh page addaction menu 2 SHIFT_LEFT PAGE:1
# Page 3 actions
/mh page addaction menu 3 RIGHT CONSOLE:give {player} diamond 1
/mh page addaction menu 3 RIGHT SOUND:minecraft:entity.experience_orb.pickup:1.0:1.0
/mh page addaction menu 3 RIGHT MESSAGE:&a+1 Diamond!
/mh page addaction menu 3 SHIFT_LEFT PAGE:1