-- This table stores all player-specific settings for menus with auto-saving enabled.
CREATE TABLE IF NOT EXISTS `masonui_data` (
  `identifier` VARCHAR(60) NOT NULL,
  `data_key` VARCHAR(100) NOT NULL,
  `data_value` TEXT DEFAULT NULL,
  PRIMARY KEY (`identifier`, `data_key`)
);

dependency 'masonui'

Config = {}

-- Choose your Identifier-Type.
-- Possible options: 'esx', 'license', 'steam', 'discord'
Config.IdentifierType = 'license'

-- Client example:
local id = MasonUI.GetIdentifier()
print("My Identifier:", id)

-- Or via export in other resources:
local id = exports["masonui"]:getIdentifier()
print("My Identifier via Export:", id)

-- In your own resource, e.g., my_menus/client.lua

-- IMPORTANT: Ensure your script loads AFTER MasonUI's client scripts.
-- In your resource's fxmanifest.lua:
-- client_scripts {
--     '@masonui/client/main.lua', -- This might not be needed if it's a dependency
--     'client.lua'
-- }

-- 1. Register a function that contains all your menu creation logic.
MasonUI.RegisterMenu(function()
    -- This code is now guaranteed to run safely.
    print("MasonUI is loaded. Creating my menus now!")

    -- You can create all your menus and items inside this function.
    MasonUI.CreateMenu("main", "Main Menu", "banner.png")
    MasonUI.AddItem("main", { label = "A simple button" })
    -- ... more menus and items
end)

-- 2. Your commands or other logic can be in standard threads.
Citizen.CreateThread(function()
    RegisterCommand("menu", function()
        -- This function simply opens a menu you've already created.
        MasonUI.OpenMenu("main")
    end, false)
end)

-- Opens a menu by its unique ID.
-- If the menu has data to load from the database, it will be fetched automatically on first open.
MasonUI.OpenMenu('settings_menu')

-- Navigates back one level in the menu stack.
-- If the user is at the top-level menu, this will close the UI entirely.
MasonUI.BackMenu()

-- Immediately closes all open menus and the UI.
-- Useful for actions that should terminate the menu interaction completely.
MasonUI.CloseAllMenus()

-- A basic menu
MasonUI.CreateMenu("main", "My Awesome Server", "banner.png")

-- A settings menu with auto-saving enabled
MasonUI.CreateMenu("settings", "Player Settings", "banner.png", {
    db_prefix = "player_settings" 
})

-- A long list that will be automatically paginated
MasonUI.CreateMenu("vehicle_list", "Vehicle Spawn", "banner.png", {
    itemsPerPage = 10
})

-- Adds a simple button to the "main" menu.
MasonUI.AddItem("main", {
    label = "Click Me!",
    action = function()
        print("Button was clicked!")
    end
})

MasonUI.AddItem('main', { 
    label = 'Open Settings', 
    decorator = 'submenu', -- Visual hint that this opens another menu
    description = 'Configure your personal in-game settings.',
    action = function() 
        MasonUI.OpenMenu('settings') 
    end 
})

MasonUI.AddItem('main', { 
    label = 'Show Notification', 
    icon = 'fa-solid fa-bell',
    action = function() 
        ESX.ShowNotification('This is a test notification!') 
    end 
})

MasonUI.AddItem('settings', { 
    type = 'checkbox', 
    label = 'Enable Minimap', 
    defaultValue = true,  -- The initial state when the menu is first created.
    onchange = function(isChecked)
        -- Code to show/hide the minimap
        DisplayRadar(isChecked)
        print("Minimap enabled state is now: " .. tostring(isChecked))
    end
})

MasonUI.AddItem('settings', { 
    type = 'slider',
    label = 'Music Volume',
    description = 'Adjust the volume of the in-game background music.',
    min = 0,           -- (Optional) The minimum value. Defaults to 0.
    max = 100,         -- (Optional) The maximum value. Defaults to 100.
    step = 10,         -- (Optional) The increment/decrement amount. Defaults to 1.
    defaultValue = 80, -- The initial value of the slider.
    onchange = function(newValue)
        -- Assume you have a function to set music volume
        SetMusicVolume(newValue / 100) -- Convert to 0.0-1.0 scale
    end
})

MasonUI.AddItem('settings', { 
    type = 'list',
    label = 'Crosshair Style',
    values = {'Dot', 'Cross', 'Circle', 'Disabled'},
    defaultValue = 'Dot', -- Must exactly match one of the strings in the `values` table.
    onchange = function(selectedValue)
        print("User selected crosshair style: " .. selectedValue)
        -- Code to apply the new crosshair style
    end
})

MasonUI.AddItem('controls', { 
    type = 'keybind',
    label = 'Toggle Engine',
    description = 'The key used to turn your vehicle engine on and off.',
    defaultValue = 'G', -- The key to use by default.
    onaction = function()
        -- This code executes when the 'G' key (or whatever the user sets) is pressed,
        -- but only when the MasonUI is NOT open.
        print("Engine keybind pressed!")
        -- Add your engine toggle logic here
    end,
    onchange = function(newKey)
        ESX.ShowNotification("Engine keybind changed to: " .. newKey)
    end
})

-- Example of organizing a settings menu with placeholders
MasonUI.AddItem('settings', { 
    type = 'placeholder', 
    label = '--- Graphics ---' ,
    align = 'center', -- (Optional) Can also be 'left' or 'right'. Default: left
    color = 'white' -- (Optional) You can use hex codes (e.g. #fff) or named CSS colors.
})
MasonUI.AddItem('settings', { type = 'slider', label = 'Field of View', ... })
MasonUI.AddItem('settings', { type = 'checkbox', label = 'Show Shadows', ... })

MasonUI.AddItem('settings', { 
    type = 'placeholder', 
    label = '--- Audio ---',
    align = 'center', -- (Optional) Can also be 'left' or 'right'. Default: left
    color = 'white' -- (Optional) You can use hex codes (e.g. #fff) or named CSS colors
})
MasonUI.AddItem('settings', { type = 'slider', label = 'Master Volume', ... })

MasonUI.AddItem('player_info', {
    type = 'stateText',
    label = 'Job',
    state = 'Unemployed', -- The initial text to display.
    description = 'This is your current occupation.',
    action = function()
        -- Could open a job center menu, for example
        print("Player wants to change jobs.")
    end
})

-- To update this item's state text from another script:
-- MasonUI.SetStateValue('player_info', 'Job', 'Police Officer')

MasonUI.AddItem('status', {
    type = 'progressbar',
    label = 'Hunger',
    min = 0,
    max = 100,
    defaultValue = 65,
    progressText = '65%', -- (Optional) Text to display inside the bar.
    action = function()
        -- Example: Eat a snack if the player has one
        print("Player wants to eat.")
    end
})

-- To update this bar later from another script:
-- MasonUI.SetProgressValue('status', 'Hunger', 75, '75%')

-- Client-Side: A button that triggers the callback

MasonUI.AddItem("main", {
    label = "Show Message of the Day",
    action = function()
        print("[Client] Requesting message from server...")

        -- Trigger the callback. We aren't sending any additional arguments.
        Callback.TriggerServerCallback('myResource:getMessageOfTheDay', function(message)
            -- This code executes after the server responds.
            -- 'message' is the value the server sends back via cb().
            
            print("[Client] Response received!")
            
            -- Display the message in a dialog.
            MasonUI.OpenInputDialog({
                title = "Message of the Day",
                placeholder = message,
                readOnly = true -- Makes the input field non-editable
            }, function() 
                -- This callback is empty, as we don't need to do anything on "Submit".
            end)
        end)
    end
})


-- Server-Side: The callback handler that provides the message

Callback.RegisterServerCallback('myResource:getMessageOfTheDay', function(source, cb)
    -- Log a message in the server console to see that the request arrived.
    print(("[Server] Player %s is requesting the message of the day."):format(source))

    -- Simulate a database query or get the info from somewhere else.
    local message = "Remember to always read the documentation! :)"

    -- Send the message back to the client using the `cb` callback function.
    cb(message)
end)

-- Create a menu that will show a maximum of 8 items per page.
MasonUI.CreateMenu("player_list", "Online Players", "banner.png", { itemsPerPage = 8 })

-- Let's add 30 items to it. MasonUI will create 4 pages.
-- (Page 1: 8 items, Page 2: 8, Page 3: 8, Page 4: 6)
for i = 1, 30 do
    MasonUI.AddItem("player_list", {
        label = "Player " .. i,
        action = function() print("Selected player " .. i) end
    })
end

-- In your main menu, create a button that will trigger the process.
MasonUI.AddItem('main', {
    label = 'View Online Players',
    decorator = 'submenu',
    action = function()
        ESX.ShowNotification("Fetching player list from server...")

        -- 1. Trigger a server callback to get the player data.
        Callback.TriggerServerCallback("myResource:getPlayers", function(players)
            -- 3. This callback function runs once the server responds with the data.

            -- 4. Create (or re-create) the player list menu HERE.
            -- This clears any old data from a previous open.
            MasonUI.CreateMenu("playerlist", "Online Players", "banner.png")

            if not players or #players == 0 then
                MasonUI.AddItem("playerlist", { type = 'placeholder', label = "No other players are online." })
            else
                for _, playerData in ipairs(players) do
                    MasonUI.AddItem("playerlist", {
                        label = string.format("[%s] %s", playerData.source, playerData.name),
                        action = function()
                            ESX.ShowNotification("You selected " .. playerData.name)
                            -- You could add admin actions here, e.g., teleport, kick, etc.
                        end
                    })
                end
            end
            
            -- 5. Finally, open the newly populated menu.
            MasonUI.OpenMenu("playerlist")
        end)
    end
})

-- On the server-side (server.lua), you would have something like this:
-- Callback.RegisterServerCallback('myResource:getPlayers', function(source, cb)
--     local players = ESX.GetPlayers()
--     local playerData = {}
--     for i=1, #players do
--         local xPlayer = ESX.GetPlayerFromId(players[i])
--         table.insert(playerData, { name = xPlayer.getName(), source = xPlayer.source })
--     end
--     cb(playerData)
-- end)

-- --- List of all available functions ---

--// By Item Label (Convenient but slightly slower) //--

-- Checkbox
MasonUI.SetCheckboxState('menuId', 'itemLabel', true)
local isChecked = MasonUI.GetCheckboxState('menuId', 'itemLabel')

-- Slider
MasonUI.SetSliderValue('menuId', 'itemLabel', 75)
local sliderVal = MasonUI.GetSliderValue('menuId', 'itemLabel')

-- List
MasonUI.SetListValue('menuId', 'itemLabel', 'Option B')
local listVal = MasonUI.GetListValue('menuId', 'itemLabel')

-- Keybind
MasonUI.SetKeybindValue('menuId', 'itemLabel', 'K')
local key = MasonUI.GetKeybindValue('menuId', 'itemLabel')

-- Progressbar
MasonUI.SetProgressValue('menuId', 'itemLabel', 50, '50%')
local progressVal = MasonUI.GetProgressValue('menuId', 'itemLabel')

-- State Text
MasonUI.SetStateValue('menuId', 'itemLabel', 'Connected')
local stateVal = MasonUI.GetStateValue('menuId', 'itemLabel')

-- Placeholder
MasonUI.SetPlaceholderLabel('menuId', 'itemLabel', 'New Title')

-- Generic Item Properties
MasonUI.SetItemDisabled('menuId', 'itemLabel', true)
MasonUI.SetItemLocked('menuId', 'itemLabel', true)
MasonUI.SetItemIcon('menuId', 'itemLabel', 'fa-solid fa-star')
MasonUI.SetItemDescription('menuId', 'itemLabel', 'New description')
local desc = MasonUI.GetItemDescription('menuId', 'itemLabel')
local type = MasonUI.GetItemType('menuId', 'itemLabel') -- returns e.g., 'slider', 'checkbox'


--// By Item Index (Faster, 1-based index) //--
-- Example: Set the second item's description
MasonUI.SetItemDescriptionByIndex('menuId', 2, 'This is the second item.')

-- The following functions all have a 'ByIndex' equivalent:
-- SetCheckboxStateByIndex, GetCheckboxStateByIndex
-- SetSliderValueByIndex, GetSliderValueByIndex
-- SetListValueByIndex, GetListValueByIndex
-- SetKeybindValueByIndex, GetKeybindValueByIndex
-- SetProgressValueByIndex, GetProgressValueByIndex
-- SetStateValueByIndex, GetStateValueByIndex
-- SetItemDisabledByIndex, SetItemLockedByIndex, SetItemIconByIndex
-- SetItemDescriptionByIndex, GetItemDescriptionByIndex
-- GetItemTypeByIndex


--// Menu-wide Functions //--
local currentMenuId = MasonUI.GetCurrentMenu()
local currentSelectionIndex = MasonUI.GetCurrentIndex() -- returns number or nil

-- Remember! Each item you add with ex. MasonUI.AddItem counts into the index!

-- Navigate the menu up or down
MasonUI.MenuUp()
MasonUI.MenuDown()

-- Navigate left or right (e.g., for sliders, lists, or changing pages)
MasonUI.MenuLeft()
MasonUI.MenuRight()

-- Example: Go down 3 items and then right once
Citizen.CreateThread(function()
    if MasonUI.GetCurrentMenu() then
        MasonUI.MenuDown()
        Citizen.Wait(150)
        MasonUI.MenuDown()
        Citizen.Wait(150)
        MasonUI.MenuDown()
        Citizen.Wait(150)
        MasonUI.MenuRight()
    end
end)

-- Assuming your inventory menu was initialized like this:
MasonUI.CreateMenu('inventory', 'Inventory')
MasonUI.AddItem('inventory', { label = 'Pistol' })
MasonUI.AddItem('inventory', { label = 'First Aid Kit' })

-- Now, a player wants to sell the pistol. After a successful transaction,
-- remove the item from the menu:
local success = MasonUI.RemoveItem('inventory', 'Pistol')

if success then
    print('Pistol was removed from the menu.')
else
    print('Could not find Pistol in the menu.')
end

-- In a script that manages a custom HUD
Citizen.CreateThread(function()
    while true do
        Citizen.Wait(500)
        -- Only draw the HUD if MasonUI is not open
        if not exports.masonui:IsMenuOpen() then
            DrawCustomHudElements()
        end
    end
end)

-- Function to refresh a list of vehicles for sale
function RefreshVehicleList()
    -- Clear out the old list first
    MasonUI.ClearMenu('vehicle_shop')
    
    -- Fetch new data and repopulate
    Callback.TriggerServerCallback('getVehicles', function(vehicles)
        for _, vehicle in ipairs(vehicles) do
            MasonUI.AddItem('vehicle_shop', { label = vehicle.name, ... })
        end
    end)
end

-- Removes the very first item from the 'inventory' menu
local success = MasonUI.RemoveItemByIndex('inventory', 1)

if success then
    print("First inventory slot cleared.")
end

-- An important server announcement arrives
local announcement = {
    type = 'placeholder',
    label = 'SERVER RESTART IN 5 MINS',
    color = '#ff4757'
}
-- Insert this announcement at the very top of the main menu (position 1)
MasonUI.InsertItem('main_menu', announcement, 1)

-- When a player buys an item, re-open the shop and focus on the next item
local lastBoughtItemIndex = 4

MasonUI.OpenMenu('item_shop')
-- Set focus to the item right after the one they just bought
MasonUI.SetFocus('item_shop', lastBoughtItemIndex + 1)

-- Available Events:
-- 'menuOpen': Fires when any menu is opened.
--      - Callback receives: menuId (string)
-- 'menuClose': Fires when the last menu is closed and the UI becomes hidden.
--      - Callback receives: no arguments
-- 'selectionChange': Fires when the user highlights a different item.
--      - Callback receives: menuId (string), newItemIndex (number), newItemData (table)

-- Example: Centralized UI management
local function onMenuOpen(menuId)
    PlaySoundFrontend(-1, "SELECT", "HUD_FRONTEND_DEFAULT_SOUNDSET", true)
    print("Opened menu: " .. menuId)
end

MasonUI.on('menuOpen', onMenuOpen)
MasonUI.on('menuClose', function()
    PlaySoundFrontend(-1, "BACK", "HUD_FRONTEND_DEFAULT_SOUNDSET", true)
end)
MasonUI.on('selectionChange', function(menuId, index, item)
    print(string.format("Selection in '%s' changed to #%d ('%s')", menuId, index, item.label))
end)

-- To remove a listener later:
-- MasonUI.off('menuOpen', onMenuOpen)

-- In a deeply nested menu (e.g., main -> settings -> graphics -> advanced)
MasonUI.AddItem('advanced_graphics', {
    label = '<< Return to Main Menu',
    description = 'Skips intermediate menus and returns to the start.',
    action = function()
        -- Get the current navigation path for debugging
        local stack = MasonUI.GetMenuStack()
        print('Current path was: ' .. table.concat(stack, ' -> ')) -- e.g., "main -> settings -> graphics -> advanced_graphics"
        
        -- Jump directly back to the 'main' menu
        MasonUI.JumpToMenu('main')
    end
})

-- Example: Refreshing a dynamic list after fetching new data.
local function refreshPlayerList()
    -- 1. Clear all old items from the currently open menu.
    MasonUI.ClearMenu('player_list')

    -- 2. Add the new, updated items.
    local newPlayers = {'PlayerA', 'PlayerB', 'PlayerC'} -- Simulate new data
    for _, name in ipairs(newPlayers) do
        MasonUI.AddItem('player_list', { label = name })
    end

    -- 3. Call RefreshMenu to display the changes instantly.
    MasonUI.RefreshMenu()
    
    ESX.ShowNotification("Player list has been updated!")
end

-- In your menu registration, define a reusable template for a player list item.
MasonUI.RegisterTemplate('player_list_item', {
    type = 'stateText',
    label = '[{{source}}] {{name}}', -- Placeholders for dynamic data
    state = 'Job: {{job}}',
    icon = 'fa-solid fa-user',
    description = 'Click for admin actions on this player.',
    action = function(data, ...)
        -- The 'data' table passed to AddItem is automatically given to the action.
        -- Now you have access to all of the player's data inside the action.
        print('Selected player with source ID: ' .. data.source)
        OpenAdminActionsForPlayer(data)
    end
})

-- Now, use the template to build a dynamic player list
Callback.TriggerServerCallback('myResource:getPlayers', function(players)
    MasonUI.CreateMenu("player_list", "Online Players")

    for _, playerData in ipairs(players) do
        -- For each player, add an item using the template
        MasonUI.AddItem('player_list', {
            template = 'player_list_item', -- The name of the template to use
            data = playerData -- This table provides the values for {{source}}, {{name}}, etc.
        })
    end

    MasonUI.OpenMenu('player_list')
end)

-- Example playerData table from the server:
-- { source = 1, name = 'John Doe', job = 'Police' }

MasonUI.AddItem('actions', {
    label = 'Withdraw Money',
    action = function()
        MasonUI.OpenInputDialog({ 
            title = 'Withdraw Amount', 
            placeholder = 'e.g., 500', -- Optional placeholder text
            submitText = 'Confirm',      -- (Optional) Custom text for the submit button
            cancelText = 'Abort'         -- (Optional) Custom text for the cancel button
        }, function(text)
            -- This callback function is executed when the user submits or cancels.
            if text then 
                -- User clicked "Confirm". `text` contains their input.
                local amount = tonumber(text)
                if amount and amount > 0 then
                    ESX.ShowNotification("Attempting to withdraw $" .. amount)
                    -- Trigger server event to handle withdrawal
                else
                    ESX.ShowNotification("Invalid amount entered.")
                end
            else 
                -- User clicked "Abort" or pressed Escape. `text` is nil.
                ESX.ShowNotification("Withdrawal cancelled.")
            end
        end)
    end
})

-- This example shows how to open a dialog and control it via code after a delay.
MasonUI.AddItem('actions', {
    label = 'Run Automated Input Test',
    action = function()
        ESX.ShowNotification("Opening dialog for automated test...")

        MasonUI.OpenInputDialog({ title = 'Automated Input' }, function(text)
            -- This callback will be fired by SubmitInputDialog or CloseInputDialog below.
            ESX.ShowNotification("Dialog callback received: " .. (text or "nil"))
        end)

        -- Start a thread to control the dialog after it opens
        Citizen.CreateThread(function()
            Citizen.Wait(2000) -- Wait 2 seconds
            ESX.ShowNotification("Setting input value programmatically...")
            MasonUI.SetInputDialogValue("This is automated text!")

            Citizen.Wait(2000) -- Wait another 2 seconds
            ESX.ShowNotification("Submitting dialog programmatically...")
            MasonUI.SubmitInputDialog()
        end)
    end
})

MasonUI.AddItem('admin', {
    label = 'Kick Player',
    action = function()
        -- Assume `targetPlayer` is defined elsewhere
        local targetPlayer = { name = 'SomePlayer' } 

        MasonUI.ShowConfirmation({
            banner = "banner.png", -- Optional
            title = "Confirm Kick",
            text = "Are you sure you want to kick " .. targetPlayer.name .. "?" -- Optional text
        }, function(confirmed)
            -- This callback receives `true` if "Yes" was clicked, and `false` if "No" was clicked.
            if confirmed then
                ESX.ShowNotification("Kicking player...")
                -- Trigger server event to kick the player
            else
                ESX.ShowNotification("Kick action cancelled.")
            end
        end)
    end
})

-- 1. In CreateMenu, define the unique database prefix for this menu.
MasonUI.CreateMenu("persistent_settings", "My Saved Settings", "banner.png", {
    db_prefix = "my_player_settings" 
})

-- 2. Add `saveValue = true` to every item you want to persist.

-- Checkbox example
MasonUI.AddItem("persistent_settings", {
    type = "checkbox",
    label = "Enable GPS Voice",
    saveValue = true, -- This setting will be saved.
    defaultValue = true
})

-- Slider example
MasonUI.AddItem("persistent_settings", {
    type = "slider",
    label = "Field of View",
    saveValue = true, -- This setting will be saved.
    defaultValue = 90,
    min = 70,
    max = 120
})

-- List example
MasonUI.AddItem("persistent_settings", {
    type = "list",
    label = "HUD Style",
    saveValue = true, -- This setting will be saved.
    defaultValue = "Standard",
    values = {"Standard", "Compact", "Hidden"}
})

-- Keybind example
MasonUI.AddItem("persistent_settings", {
    type = "keybind",
    label = "Interaction Key",
    saveValue = true, -- This setting will be saved.
    defaultValue = "E",
    onaction = function()
        -- This action will use the saved key
        print("Interaction key pressed!")
    end
})

-- State Text example (Basically an button with a text next to it)
MasonUI.AddItem("info_menu", {
    type = "stateText",
    label = "Godmode:",
    state = "On",
    action = function()
        local state = MasonUI.GetStateValue("info_menu", "Godmode:")
        if state == "On" then
            MasonUI.SetStateValue("info_menu", "Godmode:", "Off")
        else
            MasonUI.SetStateValue("info_menu", "Godmode:", "On")
        end
    end
})

-- Create the theme menu with a database prefix.
MasonUI.CreateMenu("theme", "Customize Design", "banner.png", { db_prefix = "player_theme" })

-- Item to control the menu's position on the screen.
MasonUI.AddItem("theme", {
    type = "list",
    label = "Position",
    saveValue = true,
    defaultValue = "Left",
    values = {"Left", "Right"},
    onchange = function(value)
        -- The value from the list is "Left" or "Right".
        -- The SetTheme function expects "left" or "right" (lowercase).
        MasonUI.SetTheme({ position = string.lower(value) })
    end
})

-- Item to control the color scheme.
MasonUI.AddItem("theme", {
    type = "list",
    label = "Color Scheme",
    saveValue = true,
    defaultValue = "Purple",
    values = {"Purple", "Blue", "Green"},
    onchange = function(value)
        if value == "Blue" then
            MasonUI.SetTheme({ primary_color_start = "#007bff", primary_color_end = "#0056b3" })
        elseif value == "Green" then
            MasonUI.SetTheme({ primary_color_start = "#28a745", primary_color_end = "#1e7e34" })
        else -- Default to Purple
            MasonUI.SetTheme({ primary_color_start = "#8A2BE2", primary_color_end = "#4B0082" })
        end
    end
})

-- IMPORTANT: To apply the saved theme when the game loads, you need to
-- fetch and apply the settings when your script starts.
-- This code should be placed where your menus are registered.

local function applyInitialTheme()
    -- Wait a moment to ensure the UI is ready.
    Citizen.Wait(500)
    if not ESX.IsPlayerLoaded() then return end
    
    local playerIdentifier = ESX.GetPlayerData().identifier
    if not playerIdentifier then return end

    -- Use the generic data fetcher to get all saved data for this player.
    ESX.TriggerServerCallback('masonui:getAllPlayerData', function(settings)
        if not settings then return end

        -- Apply position (defaulting to "Left")
        local position = settings['player_theme_position'] or "Left"
        MasonUI.SetTheme({ position = (position == "Left" and "left" or "right") })
        
        Citizen.Wait(50) -- Small delay between NUI messages

        -- Apply color scheme (defaulting to "Purple")
        local color = settings['player_theme_color-scheme'] or "Purple"
        if color == "Blue" then
            MasonUI.SetTheme({ primary_color_start = "#007bff", primary_color_end = "#0056b3" })
        elseif color == "Green" then
            MasonUI.SetTheme({ primary_color_start = "#28a745", primary_color_end = "#1e7e34" })
        else
            MasonUI.SetTheme({ primary_color_start = "#8A2BE2", primary_color_end = "#4B0082" })
        end
    end, playerIdentifier)
end

-- Create a thread to run this function after the resource starts.
Citizen.CreateThread(applyInitialTheme)

-- WRONG - This might fail if this script loads too fast
Citizen.CreateThread(function()
    MasonUI.CreateMenu("main", "My Menu") -- MasonUI might be nil here
end)

-- CORRECT - This is the safe and recommended way
MasonUI.RegisterMenu(function()
    -- This code is guaranteed to run only after MasonUI is ready.
    MasonUI.CreateMenu("main", "My Menu")
end)

Also, double-check your fxmanifest.lua to ensure you have set up a dependency on MasonUI or that you are loading its client scripts correctly before your own.

Q: The `onaction` for my keybind item doesn't work when I press the key.

This is a common misunderstanding of how keybinds work. The onaction function is designed to be a global hotkey that works only when the menu is closed. It allows players to set a key in the menu and then use it during normal gameplay.

• If you want something to happen when the key is pressed while the game is running and the menu is closed, use onaction.
• If you want something to happen when the user clicks "Enter" on the keybind item inside the menu, you would normally use the action property. However, for a keybind item, its default action is to start "listening" for a new key. A custom action is not typically used on this item type.

Advanced Troubleshooting

Q: My menu opens, but it's empty or missing items.

Symptom: The UI appears with the correct title and banner, but the item list is empty.

• Cause 1: Incorrect Menu ID. You might be adding items to a different menu ID than the one you are opening. Item labels and menu IDs are case-sensitive.

  MasonUI.CreateMenu("MyMenu", "My Menu") -- Capital 'M'
  MasonUI.AddItem("mymenu", { label = "An item" }) -- Lowercase 'm'. This item will not appear.
  MasonUI.OpenMenu("MyMenu") -- Opens the empty menu.

• Cause 2: Dynamic Menu Logic Failure. If you are creating a menu from a server callback (like a player list), the callback might be returning nil or an empty table. Add print() statements inside your callback to debug the data you receive from the server before you create the items.

  ESX.TriggerServerCallback("myResource:getData", function(data)
      print("Data received from server:", json.encode(data)) -- Debug the received data!
      if not data or #data == 0 then
          print("Data is nil or empty, showing a placeholder.")
          MasonUI.CreateMenu("my_dynamic_menu", "List")
          MasonUI.AddItem("my_dynamic_menu", { type = "placeholder", label = "Nothing to show." })
      else
          -- ... create items from data
      end
      MasonUI.OpenMenu("my_dynamic_menu")
  end)

Q: A `Get...` function like `GetCheckboxState` is returning `nil`.

Symptom: You try to programmatically get an item's state, but the function returns `nil` instead of the expected value (e.g., `true`/`false`).

• Cause: Exact Match Required. The menuId and itemLabel you provide to the getter function must be an exact, case-sensitive match for the strings used when creating the menu and item. A single character difference will cause it to fail.

  MasonUI.AddItem("settings", { type = "checkbox", label = "Enable HUD" })
  -- ...
  -- This will return nil because of the case difference in "Hud"
  local state = MasonUI.GetCheckboxState("settings", "Enable Hud") 
  -- This is correct
  local state = MasonUI.GetCheckboxState("settings", "Enable HUD")

Q: My menu controls (Up/Down/Enter) don't work or stop working.

Symptom: The menu is visible on screen, but pressing keys does nothing. You can't navigate or select.

• Cause: A Conflicting Script. This is a classic FiveM issue. Another resource may be running a loop (a while true do thread) that constantly disables the same controls MasonUI needs. Scripts for things like custom HUDs, cinematic modes, or other UI systems are common culprits.
  Solution: You need to identify the conflicting script. Try disabling your other resources one by one until the menu controls start working again. Once you find the conflicting script, you'll need to edit it to not disable controls when your menu is open. You can use an export from your menu script to tell other scripts when MasonUI is active.

Q: A submenu button shows the arrow but doesn't open anything.

Symptom: You added decorator = 'submenu' to an item, but clicking it has no effect.

• Cause: Missing action Function. The decorator property is purely a visual hint for the user. It does not add any functionality. You must still provide an action function that explicitly calls MasonUI.OpenMenu() with the ID of your submenu.

  -- This is just a visual hint, it does nothing by itself.
  MasonUI.AddItem("main", { label = "Settings", decorator = "submenu" })
  
  -- CORRECT: You must also provide the action to open the next menu.
  MasonUI.AddItem("main", { 
      label = "Settings", 
      decorator = "submenu",
      action = function()
          MasonUI.OpenMenu("settings_menu") -- This part is required!
      end
  })