> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://aetherskywarswiki.netlify.app/api/mcp` to find what you need. # Menus The `menus` folder holds what players click on inside a menu. `items.yml` holds what they carry. A double chest menu with its 54 slots numbered row by row The split is about slots. A hotbar item needs a hotbar slot, a menu button needs a slot in its own menu, and the two numbers mean different things. Menu buttons also carry lore that describes what an option does, rather than naming it, so that text belongs with the menu rather than in a language file. Every menu the plugin opens is in the folder. A file is named after its menu, and menus that belong together share one: | File | The menu | | --- | --- | | `shared.yml` | The background, paging, the way back, and the filter. Every menu draws these | | `vote.yml` | What players vote on while they wait in their cage | | `shop.yml` | The shop, and the spectator shop that reuses it | | `wardrobe.yml` | The wardrobe hub, behind the lobby wardrobe item | | `kits.yml` | The wardrobe pages, the kit preview, and a kit's settings | | `maps.yml` | The arena list, an arena's settings, its dashboard, and its events | | `profile.yml` | A player's own profile, and the matches they have finished | | `achievements.yml` | The statistic picker, and the milestone list behind each one | | `player-info.yml` | Another player's card, from shift right clicking them | | `admin.yml` | `/asw menu`, and what a chest tier drops | | `settings.yml` | The plugin settings browser | | `player-settings.yml` | A player's own settings | | `social.yml` | The friend list and the requests waiting to be answered | | `quests.yml` | The daily and weekly quest list | | `challenges.yml` | The challenges a player can take on for a match | | `mysterybox.yml` | The mystery box menu | ## How items are spread out A menu is given the room its items may use, not a slot each. The plugin then spreads them over as few rows as they need, centres those rows top to bottom, and centres each row left to right. That is why switching a shop category off closes the gap instead of leaving a hole in the middle of the row, and why eight challenges are drawn as four and four rather than seven and one. The practical effect is that you set the area and stop thinking about it. Give the challenge list three rows and it looks right with one challenge in it or with twenty. Two shapes of key do this: | Key | What it holds | | --- | --- | | `Slots`, `Daily-Slots`, `Reels`, `Buttons`, `Category-Bar`, `Category-Grid` | The room items may use | | `Main`, `Back`, `Info`, `Daily-Header` | One fixed slot, for a single button | Category buttons share one ordered list per menu rather than a slot each. `Category-Bar` is the bottom row of a shop or wardrobe page, and `Category-Grid` is the three by three block in the middle of either hub. What each button looks like still lives under `Categories`, one entry per category, and the order they are drawn in is the order they are listed. :::note There is no separate kit menu. `/asw kits`, the kit item in the cage, and the wardrobe pages all open the same one, which is why `kits.yml` has a section called `Kits` that draws cage blocks and bow particles too. ::: :::note This used to be a single `menus.yml`. It is split into the folder on the first start after updating, keeping everything you had set, and the old file is left behind as `menus.yml.migrated` in case you want to look at it. Delete that when you are happy. Anything in the folder that is not one of the files above is folded back into the ones that are, the same way and with the same `.migrated` suffix. So if these ever get regrouped again, or you rename one by hand, nothing you set is lost. Nothing you write elsewhere has to change: a button's route is the same, it just lives in a smaller file now. ::: ## The item format The same keys as everywhere else, described in full on [Items and slots](/configuration/items-and-slots), plus one that only makes sense in a menu. ```yaml MATERIAL: CHEST # required SLOT: 22 # which slot of this menu it occupies, counting from 0 AMOUNT: 1 NAME: "E9FD4Save Settings" LORE: - " BA6B2Writes these settings to the arena." CUSTOM_MODEL_DATA: 1001 ``` Colours work in `NAME` and `LORE`: `&` codes, `&#RRGGBB`, gradients, rainbows and the named palette. See [Colors](/configuration/colors) for the whole syntax and the palette. Deleting an item's block falls back to what the plugin would have used anyway, so removing a few lines is how you reset one. Two items sharing a slot in the same menu means one lands on top of the other. Many blocks carry no `NAME`. That is on purpose: the wording comes from the language files, so it stays translated. Setting `NAME` here overrides every language at once. ## Slots, and lists of them Some menus take lists rather than single numbers. | Key | What it does | | --- | --- | | `Slots` | Where the menu draws its entries, in order. The length is the page size | | `Border` | Slots filled with `Shared.Filler`. Anything placed later sits on top | | `Paging.Back` and `Paging.Next` | Where the paging buttons go, usually twice down one side | `Slots` being the page size matters. Shortening the list gives you more pages rather than dropping the entries that no longer fit. ```yaml [plugins/AetherSkyWars/menus/shop.yml] Shop: Slots: [10, 11, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23, 24, 25] Border: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 17, 18, 26, 27, 35, 36, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53] Paging: Back: [18, 27] Next: [26, 35] ``` A slot outside the menu is ignored, and an empty list means none. ## Live values Some buttons show something that changes: whether a setting is on, how many seconds a timer runs, how many players are in an arena. Those go in as placeholders, so you can move the value inside the name, put it in the lore, or leave it out. | Placeholder | Where it works | What it holds | | --- | --- | --- | | `%state%` | arena settings, the dashboard, kit settings, plugin settings, player settings | `ON` or `OFF`, coloured | | `%raw%` | player settings | The same answer with no colours and no brackets, for when you are colouring the line yourself. The wording lives in the language files under `Menus.Player-Settings.State` | | `%value%` | arena settings, plugin settings | The number the setting holds | | `%setting%` | plugin settings | The name of the setting | | `%language%` | the profile menu | The language the player is reading | | `%goal%` `%progress%` `%remaining%` `%reward%` `%currency%` `%statistic%` | achievements | One milestone's numbers | | `%equipped%` | the wardrobe hub | What the player is wearing in that category, or the wording for nothing | | `%type%` `%players%` `%spectators%` `%tier%` `%runtime%` | the dashboard info card | Live arena state | ```yaml MapSettings: MaxGameTime: NAME: "E9FD4Max Game Time &#E6EDF3%value%" LORE: - " BA6B2How long a match runs before it is called off." ``` ## What each section covers | Section | The menu | | --- | --- | | `Vote` | What players vote on while they wait in their cage | | `Shop` | `/asw shop`, and the spectator shop, which hides the category buttons | | `Kits` | The wardrobe pages, one per kind of cosmetic | | `Wardrobe` | The wardrobe hub, behind the lobby wardrobe item | | `Profile` | The menu behind the lobby profile item | | `GameHistory` | The matches a player has finished, behind the profile history item | | `Achievements` | The four statistics you can browse achievements for | | `KitPreview` | Looking inside a kit before buying it | | `PlayerInfo` | Another player's card, from shift right clicking them | | `Admin` | `/asw menu` | | `TierViewer` | What one chest tier drops, from `/asw tiers` | | `Settings` | The plugin settings browser, for whoever runs the server | | `PlayerSettings` | A player's own settings, from the lobby hotbar or their profile | | `Friends` | A player's friend list | | `FriendRequests` | The friend requests waiting for them | | `MapsList` | The arena list players join from | | `MapSettings` | An arena's settings | | `MapDashboard` | A running arena, changed mid match | | `MapEvents` | The events an arena runs partway through a match | | `KitSettings` | A kit's settings, while making one | | `Shared` | The background, paging, the way back, and the filter | `Shared` buttons have no `SLOT`, since each menu places them where it needs them. The slot lives in that menu's own section instead. ## Categories The shop and the kit menu both have four category buttons along the bottom, one per thing you can own. A category whose shop is turned off in `config.yml` is not drawn, and the border shows through instead. ```yaml Shop: Categories: CageBlocks: MATERIAL: SPAWNER SLOT: 47 LORE: - " BA6B2The block your cage is built from." - " BA6B2Bought once and kept." ``` The two menus keep separate blocks on purpose. One is where you buy, the other is where you pick what you already own, and they are worth wording differently. The wardrobe hub uses the same shape under `Wardrobe.Categories`, with one button per kind rather than a row along the bottom. Its lore takes `%equipped%`. ```yaml Wardrobe: Back: 22 Categories: CageBlocks: MATERIAL: SPAWNER SLOT: 10 LORE: - "&#E6EDF3> %equipped%" - " BA6B2The block your cage is made of." ``` ## Achievements `Achievements.Viewer` is the list that opens when you pick a statistic. It takes `Slots`, `Border` and `Paging` like the other lists, plus one entry per state of a milestone: ```yaml [plugins/AetherSkyWars/menus/achievements.yml] Achievements: Viewer: Earned: MATERIAL: GREEN_CONCRETE LORE: - " BA6B2Reward: &#FFC857%reward% %currency%" Locked: MATERIAL: RED_CONCRETE LORE: - " BA6B2Progress: AC8FA%progress% BA6B2/AC8FA%goal%" ``` Both take the placeholders in the table above, in the name as well as the lore, so you can show as much or as little of the numbers as you like. ## The other paged menus `MapsList`, `GameHistory` and `TierViewer` are lists too, and take the same `Slots`, `Border` and `Paging` keys. Their entries draw themselves, so there is no item block for them: an arena carries its own icon and state, a finished match carries its own summary, and a piece of tier loot is drawn as the item it is. What is left is the layout, plus the one or two buttons each of them adds. | Key | Menu | What it is | | --- | --- | --- | | `MapsList.Filter` | The arena list | Cycles which arenas are listed. Left click forwards, right click back | | `GameHistory.Stats` | Game history | Wins, kills and the rest, totalled across every match | | `GameHistory.Back` | Game history | Back to the profile | Both buttons reuse a shared item, so only the slot lives in the section. ```yaml [plugins/AetherSkyWars/menus/maps.yml] MapsList: Slots: [10, 11, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23, 24, 25] Border: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 17, 18, 26, 27, 35, 36, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53] Paging: Back: [18, 27] Next: [26, 35] Filter: SLOT: 49 ``` ## Adding to the file The file carries `menus-version`. When a release adds a button, the version goes up and the new keys are merged into your file on the next start. Anything you have changed is kept, and anything you have deleted stays deleted. Values you have not touched are never overwritten either, which is the other half of that rule: if a release changes a default you already have in your file, your copy wins. Delete the block to take the new one. ## Related pages * [Items and slots](/configuration/items-and-slots) * [Messages and languages](/configuration/messages-and-languages) * [Shop and cosmetics](/features/shop-and-cosmetics) * [Voting and events](/features/voting-and-events)