Choose how players pick an effect
Open the effect menu, switch to the 3D selector, and let players favourite, filter, randomise and buy effects.
/hiteffect opens a menu where players wear, preview, favourite and buy hit effects. You choose between an inventory window and a 3D selector standing in the world.
Before you start#
The menu only opens when players are allowed to pick effects in it. With behaviour.mode: weapon it answers that it is disabled instead of opening: see Modes and tokens. Players also need an effect to wear, see Your first hit effect.
Steps#
Open the menu
Run /hiteffect. You get the inventory window: categories down the left, the effects of the open category in the grid.
Wear, preview or favourite an effect
Left-click an effect to wear it (left-click it again to take it off). Right-click to preview it. Shift-click to favourite it.
Try the 3D selector
Run /hiteffect 3d. It opens the 3D selector whatever the setting says. /hiteffect classic opens the inventory window.
Make one of them the default
In plugins/ExyliaHitEffect/config.yml set menu.style to CLASSIC (the default) or SPATIAL, then run /hiteffectsadmin reload.
Check that it works#
Run /hiteffect, left-click an effect and hit a player or a zombie: the effect plays on the body you hit. With menu.style: SPATIAL, /hiteffect opens the 3D selector, and a player on a client older than 1.21.4 gets the inventory window instead.
Going further#
The 3D selector#
The same catalogue drawn in the world in front of the player. The categories run along the top as tabs, the effect being looked at is named over a pedestal where a mannequin takes the hits, and the effects stand in an arc round it.
| Piece | What it does |
|---|---|
| The arc | Look at an effect to read about it, click it to try it on the mannequin. Trying costs nothing and changes nothing yet. |
| EQUIP | Puts the effect being tried on the player's hits. On a locked effect that is for sale it reads BUY, then CONFIRM with the price, and the second click pays and equips. |
| The icons | Favourite, unequip, revert, random, replay, the crate, help and leave. |
| The tabs | Filter by category, with favourites (★) and every effect at once. |
It follows the same rules as the inventory menu, so the two never disagree about what a player owns. Without exyliahiteffect.preview clicking an effect still picks it, but the mannequin stays still. Without exyliahiteffect.favourites the ★ tab refuses in both screens. The first open plays a short guided tour; the ? icon shows it again, and /hiteffectsadmin spatial tour <player> replays it for someone.
To leave a selector in the world for players to click, stand where it should go and run /hiteffectsadmin spatial place. Move its pieces with /hiteffectsadmin spatial edit. See Commands.
The 3D selector needs a 1.21.4 client or newer. A player on an older client gets the inventory menu instead, with nothing to configure.
Does the menu have a "screen" style?#
Not in this plugin's own setting: menu.style only accepts CLASSIC and SPATIAL. ExyliaHitEffect does ship a full-screen version of the effect menu (screens/effects.html), which ExyliaLib's SCREEN menu style draws for players whose client can show screens. That style is chosen in ExyliaLib, not here: see Screens and Menus. A screen file that cannot be read keeps the inventory menu.
Favourites#
The first tab is the player's own shortlist. Starring is free: a player does not need to own an effect to star it, so a lapsed rank does not wipe the list. Stars stay in the order they were added. Locked favourites are still drawn on this tab even on a server that hides locked effects elsewhere. To empty it, Shift-click the tab while it is open (it asks first) or run /hiteffect favourites clear. Players need exyliahiteffect.favourites.
Show only what players own#
The Filter button (top of the window) switches the grid between every effect and only the ones the player owns. The choice is remembered like the open tab. To drop locked effects from the grid for everyone, set behaviour.hide-without-permission: true (default false); the favourites tab still shows them.
Random effect#
The Random effect button makes every hit play a different effect, drawn from the ones the player owns. Players need exyliahiteffect.random.
Let players buy locked effects#
With shop.enabled on and an economy installed, a locked effect with a price shows its price and a left-click asks the player to confirm, charges them and unlocks it. Players without exyliahiteffect.buy see the locked effect with no price. Set prices and currencies in Configuration; economies are covered in ExyliaLib economy.
Change how the menu looks#
The window is plugins/ExyliaHitEffect/lang/<code>/menus/effects.yml: titles, icons and lore use ExyliaLib colours, and the words are translated per language, see Messages and languages. Edits are kept across updates. The general rules for menu files are in Menus. The 3D layout is spatial/effects.yml, and its words are under spatial in messages.yml.
Technical details
Fixed buttons: Your effect at slot 3 (click to take the effect off), Filter at 4, Crate at 5, Particle visibility at 48, Close at 49, Random effect at 50. Categories sit at slots 9,18,27,36 (paged at 0 and 45), the grid at 11-16,20-25,29-34,38-43 (paged at 47 and 52). An effect a player plays because their rank gives it carries menu.default-marker (see behaviour.defaults in Configuration). Effects the player may use are drawn first, then locked ones. The menu redraws whatever windows a player has open when their row changes (their click, a command, an admin, or an expired rank).
Extra tokens not in the tables below: placeholders %effect_default%, %current_default%, %filter_status%, template none_owned_template (what a tab shows when the filter leaves nothing) and action hiteffect:filter.
Templates#
Each list picks a template per row. item_template is the plain state and must stay first.
| Section | Template | Used when |
|---|---|---|
categories | item_template | Another tab is open. |
open_template | This is the tab being looked at. | |
favourites_template | The shortlist tab, while another tab is open. | |
favourites_open_template | The shortlist tab while it is open — the only one carrying the "empty the list" action. | |
grid | item_template | An effect the player owns. |
selected_template | The effect currently worn. | |
locked_template | An effect they do not own. | |
purchasable_template | An effect they do not own that the shop sells, while an economy can take its price. | |
empty_template | Drawn on the favourites tab when nothing is starred. |
Placeholders#
These are the menu's own tokens, filled in while the screen is drawn. They are not PlaceholderAPI placeholders and only work inside this file.
| Placeholder | Where | What it draws |
|---|---|---|
%category_id% | categories | The tab's id — favourites on the shortlist tab. |
%category_name% | categories | The tab's display name. |
%category_material% | categories | The material its icon is drawn with. |
%category_total% | categories | How many effects the tab holds. |
%category_owned% | categories | How many of those the player owns. |
%category_status% | categories | menu.tab-open or menu.tab-closed, depending on whether this is the tab being looked at. |
%effect_id% | grid | The effect's id. |
%effect_name% | grid | Its display name, with its colours. |
%effect_material% | grid | The material it is drawn with. |
%effect_description% | grid | Its description from effects.yml. |
%effect_weapons% | grid | What it may be bound to, in words. |
%effect_favourite% | grid | menu.favourite-on or menu.favourite-off, depending on whether it is starred. |
%effect_tier% | grid | The rarity's name, in the rarity's colour. |
%effect_tier_id% | grid | The rarity's id. |
%effect_tier_color% | grid | That colour on its own. |
%effect_price% | grid | What it sells for, with its currency. Empty when it is not for sale. |
%current_effect% | Anywhere | The effect the player is wearing, menu.random-name on random, or menu.empty. |
%random_status% | Anywhere | menu.random-on or menu.random-off. |
%favourites_count% | Anywhere | How many effects they have starred. |
%keys% | Anywhere | Crate keys they hold. |
%unlocked_count% | Anywhere | How many effects they have won from the crate. |
%catalogue_count% | Anywhere | How many effects the server declares. |
%particle_visibility% | Anywhere | The player's current visibility mode, named as particles.name-* says. |
%visibility_all% | Anywhere | The name of the "everyone" mode, for a button that offers it. |
%visibility_none% | Anywhere | The name of the "nobody" mode. |
%visibility_self_only% | Anywhere | The name of the "only me" mode. |
%visibility_others_only% | Anywhere | The name of the "only others" mode. |
Actions#
| Action | What it does |
|---|---|
hiteffect:open | Opens the screen. |
hiteffect:category <id> | Switches tab. favourites is a valid id. |
hiteffect:choose <id> | Wears an effect, or takes it off when it is already worn. |
hiteffect:clear | Takes the effect off. |
hiteffect:favourite <id> | Stars or unstars. |
hiteffect:favourites_clear | Empties the shortlist. |
hiteffect:buy <id> | Asks the player to confirm, then buys a locked effect the shop sells. |
hiteffect:preview <id> | Previews an effect and reopens the menu afterwards. |
hiteffect:visibility | Steps the viewer's visibility on by one. |
hiteffect:random | Turns the random choice on. |
hiteffect:crate | Opens the crate. |
hiteffect:crate_open <amount> | Spends that many keys and opens that many reels. |
Wording#
The few strings one template draws for every row live in messages.yml, because no menu file can
spell them out row by row:
menu:
empty: "{muted}Nothing"
tab-open: "{success}✔ You are here"
tab-closed: "{warning}➥ Click to open"
weapons-any: "Any weapon"
favourites-name: "Favourites"
favourite-on: "{highlight}★ In your favourites"
favourite-off: "{muted}☆ Not in your favourites"
random-name: "{highlight}Random"
random-on: "{success}✔ Every hit is a surprise"
random-off: "{warning}➥ Click to surprise yourself"Something missing on this page? Tell us on Discord