Context-Menu

🧭 Menu Types: Context vs. Menu

Before diving into the functions, it's important to understand the two distinct ways you can display data using ak47_lib:

1. Context Menus (RegisterContext & ShowContext): Best for static lists of actions where the user clicks an option to trigger an event, server event, or function. Usually mouse-driven.

2. Interactive Menus (RegisterMenu & ShowMenu): Best for complex interactions like checkboxes, side-scrolling lists, and real-time navigation feedback. Completely keyboard-driven (Arrow Keys, Enter, Backspace).

---

🛠️ Core Functions

RegisterContext

Registers a mouse-driven context menu. This data is cached and can be called anytime using ShowContext.

Syntax:

exports.ak47_lib:RegisterContext(data)

Example:

exports.ak47_lib:RegisterContext({
    id = 'player_actions',
    title = 'Player Actions', 
    position = 'top-right',
    canClose = true,
    options = {
        {
            title = 'Heal Player',
            description = 'Restores health to **100%**',
            icon = 'heart',
            iconColor = '#ff5555',
            onSelect = function() print("Heal button pressed!") end
        },
        {
            title = 'Give Weapon',
            description = 'Triggers a client event',
            icon = 'gun', 
            event = 'my_custom_client_event',
            args = { weapon = 'WEAPON_PISTOL', ammo = 250 }
        }
    }
})

RegisterMenu

Registers a keyboard-driven interactive menu. Features a master callback that triggers when the user presses Enter on an item.

Syntax:

exports.ak47_lib:RegisterMenu(data, callback(selected, scrollIndex, args))

Example:

exports.ak47_lib:RegisterMenu({
    id = 'settings_menu',
    title = 'Server Settings',
    position = 'top-left',
    onClose = function(keyPressed)
        print('Menu closed using: ' .. tostring(keyPressed))
    end,
    options = {
        { label = 'Godmode', icon = 'shield', checked = false, args = { setting = 'godmode' } },
        { label = 'Time of Day', icon = 'clock', values = {'Morning', 'Noon', 'Night'}, defaultIndex = 2 }
    }
}, function(selected, scrollIndex, args)
    print(('Selected Item: %s, Scroll Index: %s'):format(selected, tostring(scrollIndex)))
    if args then print('Args: ', json.encode(args)) end
end)

Display & Hide Functions

Function	Description	Example Usage
ShowContext	Opens a registered context menu. You can specify if it should be keyboard only.	exports.ak47_lib:ShowContext('player_actions', false)
ShowMenu	Opens a registered menu in strict keyboard-only mode.	exports.ak47_lib:ShowMenu('settings_menu')
HideContext	Closes the active context menu.	exports.ak47_lib:HideContext(true)
HideMenu	Closes the active interactive menu.	exports.ak47_lib:HideMenu(true)
GetOpenMenu	Returns the string id of the currently open menu, or nil.	local current = exports.ak47_lib:GetOpenMenu()

SetMenuOptions

Dynamically updates the options of a registered menu without needing to re-register it.

Syntax:

-- Update ALL options
exports.ak47_lib:SetMenuOptions('menu_id', newOptionsTable)

-- Update a SINGLE option (e.g., updating the 2nd item)
exports.ak47_lib:SetMenuOptions('menu_id', updatedOptionData, 2)

---

⚙️ Configuration Properties

Menu Configuration (data table)

These properties are used at the root level of RegisterContext or RegisterMenu.

Property	Type	Description
id	string	Required. A unique identifier for the menu.
title	string	The display title at the top of the menu.
position	string	'top-left', 'top-right', 'bottom-left', or 'bottom-right'.
canClose	boolean	If true, the user can press ESC/Backspace to close.
disableInput	boolean	If true, disables all player controls while the menu is open.
options	table	Required. An array of option objects (see below).
onClose	function	Triggers when the menu is closed (receives the key pressed).
onSelected	function	(RegisterMenu only) Triggers when an item is hovered.
onSideScroll	function	(RegisterMenu only) Triggers when a side-scrolling list changes.
onCheck	function	(RegisterMenu only) Triggers when a checkbox is toggled.

Option Configuration (Items inside options)

Property	Type	Description
title / label	string	Required. The main text of the button. (title is preferred for Context, label for Menu).
description	string	Secondary text displayed as a tooltip or subtext.
icon	string	FontAwesome icon name (e.g., 'car', 'shield') or an image URL/Path.
iconColor	string	Hex or RGB color for the icon (e.g., '#ff5555').
iconAnimation	string	FontAwesome animation class (e.g., 'spin', 'beat').
disabled	boolean	Grays out the button and prevents interaction.
readOnly	boolean	Prevents hovering/clicking, but doesn't look completely disabled.
progress	number	0-100. Displays a progress bar inside the button.
colorScheme	string	Color used for the progress bar.
args	table	Custom data passed to events/callbacks when this item is interacted with.
close	boolean	Set to false to keep the menu open after clicking. Defaults to true.

Advanced Option Properties (Context Menus)

• event (string): Triggers a client event when clicked. Passes args.

• serverEvent (string): Triggers a server event when clicked. Passes args.

• onSelect (function): Anonymous function executed when clicked. Passes args.

• menu (string): The id of another menu to open when clicked (Submenu).

Advanced Option Properties (Interactive Menus)

• checked (boolean): Turns the option into a Checkbox.

• values (table): Array of strings or {label, description} objects. Turns the option into a Side-Scroller (Left/Right arrows).

• defaultIndex (number): The starting index (1-based) for a values list.

Metadata Panel (Player/Vehicle Stats)

You can attach a beautiful side-panel to any option by adding image and metadata.

{
    label = 'Inspect Vehicle',
    icon = 'magnifying-glass',
    image = 'https://docs.fivem.net/vehicles/t20.webp',
    metadata = {
        { label = 'Model', value = 'T20' },
        { label = 'Plate', value = 'LIB47DEV' },
        { label = 'Engine Health', value = '85%', progress = 85, colorScheme = '#fbc531' }
    }
}

---

📝 Complete Usage Example

Here is a comprehensive example demonstrating submenus, side-scrolling, checkboxes, and metadata all working together seamlessly:

-- 1. Register a Sub-Menu
exports.ak47_lib:RegisterContext({
    id = 'vehicle_options',
    title = 'Vehicle Options',
    position = 'top-right',
    options = {
        { title = 'Toggle Engine', icon = 'power-off', iconColor = '#e1b12c' },
        { title = 'Lock Doors', icon = 'key' }
    }
})

-- 2. Register the Main Menu
exports.ak47_lib:RegisterMenu({
    id = 'main_showcase',
    title = 'Interaction Menu',
    position = 'top-right',
    onSideScroll = function(selected, scrollIndex, args)
        print(("Scrolled item %s to index %s"):format(selected, scrollIndex))
    end,
    options = {
        {
            label = 'Give Weapon',
            description = 'Triggers an event instantly.',
            icon = 'gun',
            args = { weapon = 'WEAPON_APPISTOL' }
        },
        {
            label = 'Vehicle Settings',
            description = 'Open vehicle options menu.',
            icon = 'car',
            menu = 'vehicle_options' -- Links to the submenu created above
        },
        {
            label = 'Select Ammo Type',
            icon = 'box-archive',
            values = {'Standard', 'Tracer', 'Incendiary', 'Armor Piercing'},
            defaultIndex = 2, -- Starts on 'Tracer'
            args = { type = 'ammo_selection' }
        },
        {
            label = 'Player Stats',
            description = 'Hover to view details.',
            icon = 'user',
            metadata = {
                { label = 'Job', value = 'Police' },
                { label = 'Rank', value = 'Captain' },
                { label = 'Hunger', value = '75%', progress = 75, colorScheme = '#e67e22' }
            }
        }
    }
}, function(selected, scrollIndex, args)
    -- Master Callback for RegisterMenu
    print(('You pressed Enter on item #%s'):format(selected))
    if args then
        print('With Arguments: ', json.encode(args))
    end
end)

-- 3. Open the Menu via Command
RegisterCommand('openmenu', function()
    exports.ak47_lib:ShowMenu('main_showcase')
end)