Menus and Actions

Menus live in menus.yml. They define chest UI screens, item layout, click actions, cooldowns, filler items, and dynamic content such as cosmetics.

Basic Menu Structure

This is the shape of a normal menu:

menus:
  profile:
    enabled: true
    size: 27
    title: "<gradient:#55ccff:#8ae6ff>Profile</gradient>"
    permission: "atlaslobby.menu.profile"
    click-cooldown-seconds: 1
    filler:
      enabled: true
      material: BLACK_STAINED_GLASS_PANE
      name: " "
      lore: []
    items:
      rewards:
        enabled: true
        slot: 10
        material: CHEST
        name: "&eRewards"
        lore:
          - "&7Open daily rewards."
        actions:
          - "open_menu: rewards"

Menu items can use these fields:

FieldPurpose
enabledTurns the item on or off.
slot / slotsPlaces the item in one slot or multiple slots.
materialMinecraft item material name.
amountStack amount.
custom-model-dataCustom model data for resource-pack models.
enchantmentsList such as ["sharpness:5", "unbreaking:3"].
head-owner / head-url / head-textureCustom player-head icon sources.
nameDisplay name.
loreLore lines.
glowAdds enchant-style glow.
hide-flagsHides item flags.
permissionPermission required to use or see the item.
actionsDefault click actions.
left-click-actionsActions for left click.
right-click-actionsActions for right click.
shift-click-actionsActions for shift click.
lockedMarks the item as locked.
state / statesState-specific item behavior.

Custom Heads

Any item with material: PLAYER_HEAD can use one of these head sources:

head-owner: "%player%"   # a player name; placeholders are allowed
head-url: "http://textures.minecraft.net/texture/..."
head-texture: "<base64 value>"

Action Types

Actions are written as strings inside an action list.

Action typeExample
Player commandplayer_command: spawn
Console commandconsole_command: give %player% diamond 1
Messagemessage: &aHello!
Broadcastbroadcast: &bNews!
Titletitle: &eWelcome
Actionbaractionbar: &7Loading...
Soundsound: UI_BUTTON_CLICK
Open menuopen_menu: rewards
Open cosmetics at a categoryopen_cosmetics: hats
Close menuclose:
Teleport spawnteleport_spawn:
Connect serverconnect: survival
Equip cosmeticequip_cosmetic: atlas-ring
Equip cosmetic aliasselect_cosmetic: atlas-ring
Unequip cosmetic slotunequip_cosmetic: hat
Preview cosmeticpreview_cosmetic: atlas-ring
Clear particle cosmeticclear_cosmetic:
Switch cosmetic categoryset_category: gadgets
Next pagepage_next:
Previous pagepage_prev:
Give coins to clickergive_coins: 100
Toggle visibilitytoggle_visibility:
Claim daily rewardclaim_daily_reward:
Send resource packsend_resource_pack:

Dynamic Cosmetic Menus

The default cosmetics menu does not list every cosmetic by hand. Instead, it uses a content provider that fills a region of slots from cosmetics.yml.

That lets the menu support category tabs and pagination automatically.

cosmetics:
  size: 54
  content:
    source: cosmetics
    default-category: particles     # starting tab
    slots: ["10-16", "19-25", "28-34"]   # ints or "from-to" ranges
    states:
      disabled: { material: BARRIER }    # optional per-state overrides for cards
  items:
    tab-particles:
      slot: 45
      material: BLAZE_POWDER
      name: "&bParticles"
      actions: ["set_category: particles"]
    previous:
      slot: 48
      material: ARROW
      name: "&7Previous Page"
      actions: ["page_prev:"]
    next:
      slot: 50
      material: ARROW
      name: "&7Next Page"
      actions: ["page_next:"]

Cosmetic card behavior:

  • Clicking a card equips the cosmetic.
  • Clicking an already equipped cosmetic unequips it.
  • Shift-right-click previews particle cosmetics.
  • The card material, name, and lore come from that cosmetic’s icon block in cosmetics.yml.

Inside a dynamic menu, these placeholders are available:

PlaceholderMeaning
%page%Current page number.
%pages%Total page count.
%menu_category%Current category id.
%menu_category_display%Current category display name.

Recursion Protection

Bad configs should not crash the server. AtlasLobby limits action recursion:

actions:
  max-recursion-depth: 8

For server selector entries, prefer proxy-server in servers.yml instead of making a server entry call connect to itself.

Previous Commands & Permissions Next Inventory & Protection