Add amxx-new-menu-api/en.md
Browse Source
Daemon666 committed
parent 94f018f46a
commit 3dbae2529feecfc1d54bdfa35da701debc00085d
1 changed file
with 90 additions and 0 deletions
amxx-new-menu-api/en.md
A
| @@ -0,0 +1,90 @@ | ||
| 1 | +--- | |
| 2 | +title: "Creating Menus with the New Menu API (menu_create)" | |
| 3 | +excerpt: "Build interactive menus with menu_create, menu_additem and menu_display, handle selections and paging, and destroy menus so they do not leak." | |
| 4 | +category: "plugin-dev" | |
| 5 | +tags: "menus, amxmodx" | |
| 6 | +image: "" | |
| 7 | +read_time: "7 min read" | |
| 8 | +--- | |
| 9 | +<p>AMX Mod X has two menu systems. The old one (<code>show_menu</code> with a keys bitmask and <code>register_menucmd</code>) still compiles, but it is fiddly and caps at ten items with manual paging. The new menu API — <code>menu_create</code>, <code>menu_additem</code>, <code>menu_display</code> — handles paging, back/next/exit, and access control for you. It is what every modern plugin uses. This guide builds a working menu end to end and covers the one thing people forget: destroying it.</p> | |
| 10 | + | |
| 11 | +<h2>1. Create the menu</h2> | |
| 12 | +<p><code>menu_create(title, handler)</code> returns a menu id and registers the callback that receives selections. Build the menu when you are about to show it, not once at plugin load, because the item list is usually dynamic:</p> | |
| 13 | +<pre>#include <amxmodx> | |
| 14 | + | |
| 15 | +public plugin_init() | |
| 16 | +{ | |
| 17 | + register_plugin("Menu Demo", "1.0", "CSB") | |
| 18 | + register_clcmd("say /tools", "cmd_tools") | |
| 19 | +} | |
| 20 | + | |
| 21 | +public cmd_tools(id) | |
| 22 | +{ | |
| 23 | + show_tools_menu(id) | |
| 24 | + return PLUGIN_HANDLED | |
| 25 | +}</pre> | |
| 26 | + | |
| 27 | +<h2>2. Add items and display</h2> | |
| 28 | +<p><code>menu_additem(menu, text, info)</code> adds a selectable line. The <code>info</code> string is an opaque payload handed back to your handler when that item is picked — use it to encode what the item means:</p> | |
| 29 | +<pre>show_tools_menu(id) | |
| 30 | +{ | |
| 31 | + new menu = menu_create("\yCSB Tools\w", "tools_handler") | |
| 32 | + | |
| 33 | + menu_additem(menu, "Heal to 100", "heal") | |
| 34 | + menu_additem(menu, "Give armor", "armor") | |
| 35 | + menu_additem(menu, "Teleport to spawn", "tp") | |
| 36 | + | |
| 37 | + menu_display(id, menu, 0) // 0 = first page | |
| 38 | +}</pre> | |
| 39 | +<p>Colour codes work in item text: <code>\y</code> yellow, <code>\w</code> white, <code> </code> red, <code>\d</code> dim (used automatically for disabled items). <code>menu_display</code>'s third argument is the page number.</p> | |
| 40 | + | |
| 41 | +<h2>3. Handle the selection</h2> | |
| 42 | +<p>The handler receives the player, the menu, and the chosen item index. Two special values matter: <code>MENU_EXIT</code> when the player closes the menu, and the item index otherwise. Read the item's info string with <code>menu_item_getinfo</code>, act on it, then <strong>destroy the menu</strong>:</p> | |
| 43 | +<pre>public tools_handler(id, menu, item) | |
| 44 | +{ | |
| 45 | + if (item == MENU_EXIT) | |
| 46 | + { | |
| 47 | + menu_destroy(menu) | |
| 48 | + return PLUGIN_HANDLED | |
| 49 | + } | |
| 50 | + | |
| 51 | + new info[16], name[64], access, callback | |
| 52 | + menu_item_getinfo(menu, item, access, info, charsmax(info), | |
| 53 | + name, charsmax(name), callback) | |
| 54 | + | |
| 55 | + if (equal(info, "heal")) | |
| 56 | + set_user_health(id, 100) | |
| 57 | + else if (equal(info, "armor")) | |
| 58 | + set_user_armor(id, 100) | |
| 59 | + else if (equal(info, "tp")) | |
| 60 | + // teleport logic here | |
| 61 | + client_print(id, print_chat, "[CSB] Teleported.") | |
| 62 | + | |
| 63 | + menu_destroy(menu) | |
| 64 | + return PLUGIN_HANDLED | |
| 65 | +}</pre> | |
| 66 | +<p>Returning <code>PLUGIN_HANDLED</code> tells AMXX you consumed the selection. If you want the menu to stay open after a pick, re-display it instead of destroying, but for most action menus one selection is the end.</p> | |
| 67 | + | |
| 68 | +<h2>4. Paging is automatic</h2> | |
| 69 | +<p>Add more than seven items and the new API inserts <em>Next</em> and <em>Back</em> entries and pages them for you — no bitmask arithmetic. Slot 8 becomes <em>Next</em>, slot 9 <em>Back</em>, slot 0 <em>Exit</em> by default. You can change the reserved slots and labels with <code>menu_setprop</code>:</p> | |
| 70 | +<pre>menu_setprop(menu, MPROP_EXITNAME, "Close") | |
| 71 | +menu_setprop(menu, MPROP_BACKNAME, "Previous") | |
| 72 | +menu_setprop(menu, MPROP_NEXTNAME, "More")</pre> | |
| 73 | + | |
| 74 | +<h2>5. Access control and disabled items</h2> | |
| 75 | +<p>The fourth argument to <code>menu_additem</code> is an access flag — the item is greyed out and unselectable for players without it. Combine with <code>get_user_flags</code> to build an admin menu whose entries adapt to the viewer:</p> | |
| 76 | +<pre>menu_additem(menu, "Ban player", "ban", ADMIN_BAN) | |
| 77 | +menu_additem(menu, "Slay player", "slay", ADMIN_SLAY)</pre> | |
| 78 | +<p>A player lacking <code>ADMIN_BAN</code> sees "Ban player" dimmed and cannot pick it, without any check in your handler.</p> | |
| 79 | + | |
| 80 | +<h2>Common errors</h2> | |
| 81 | +<ul> | |
| 82 | +<li><strong>Menus stop appearing after a while</strong> — you never called <code>menu_destroy</code>. Every <code>menu_create</code> allocates; leaking them exhausts the menu pool and new menus silently fail. Destroy in the handler on both <code>MENU_EXIT</code> and every real selection.</li> | |
| 83 | +<li><strong>Wrong action runs</strong> — you compared <code>item</code> (a page-relative index) instead of the info string. With paging, item 0 on page 2 is not your first item. Always branch on the info string from <code>menu_item_getinfo</code>.</li> | |
| 84 | +<li><strong>Handler never called</strong> — the callback name passed to <code>menu_create</code> does not match a <code>public</code> function, or you displayed the menu to a disconnected/invalid id.</li> | |
| 85 | +<li><strong>Colour codes printed literally</strong> — you escaped the backslash wrong. In Pawn a single <code>\y</code> is the code; a doubled <code>\y</code> prints the letters.</li> | |
| 86 | +<li><strong>Menu closes instantly</strong> — you returned <code>PLUGIN_CONTINUE</code> from a <code>register_clcmd</code> that also matches another handler. Return <code>PLUGIN_HANDLED</code>.</li> | |
| 87 | +</ul> | |
| 88 | + | |
| 89 | +<h2>Verification</h2> | |
| 90 | +<p>Bind the open command, type it in chat, and confirm the menu shows with correct colours and your items. Pick each item and confirm the right action runs. Add ten items and confirm <em>Next</em>/<em>Back</em> appear and page correctly. Finally, open and close the menu a few dozen times and confirm it still opens — that is the leak test for missing <code>menu_destroy</code> calls. To learn the language fundamentals behind this, see <a href="/tutorials/pawn-basics-for-amxx">Pawn basics for AMXX</a>; for a real admin menu built on this API, look at <a href="/plugins/csb-admin-menu">CSB Admin Menu</a>.</p> | |
| 0 | 91 |
