# qb-radialmenu

`qb-radialmenu` presents a wheel of contextual actions. Each entry describes an action; another resource still has to implement its event. This guide builds a harmless help action with a complete client resource, so you can test the handler independently before adding it to the wheel.

**Baseline:** [3fa42401](https://github.com/qbcore-fivem/qb-radialmenu/tree/3fa42401c53254bd5e37f94ccd5afdb5e22a48ad). See its [config](https://github.com/qbcore-fivem/qb-radialmenu/blob/3fa42401c53254bd5e37f94ccd5afdb5e22a48ad/config.lua), [README](https://github.com/qbcore-fivem/qb-radialmenu/blob/3fa42401c53254bd5e37f94ccd5afdb5e22a48ad/README.md) and [manifest](https://github.com/qbcore-fivem/qb-radialmenu/blob/3fa42401c53254bd5e37f94ccd5afdb5e22a48ad/fxmanifest.lua). The manual checks below have not been executed in FiveM by this article.

## Radial menu, qb-menu or qb-target?

| Need | Resource |
| --- | --- |
| A wheel of commonly used player actions | qb-radialmenu |
| A list of actions or a conventional submenu | [qb-menu](/docs/resources/qb-menu) |
| Interaction with an entity or zone | [qb-target](/docs/resources/qb-target) |
| Fields the player must fill in | [qb-input](/docs/resources/qb-input) |

Do not install multiple replacements for the same interaction just to solve a missing handler. Identify the responsible resource first. Keep the wheel focused on actions players actually use.

## Configure the keybind and opening behavior

The pinned config defaults to `Config.Keybind = 'F1'`, `Config.Toggle = false` and `Config.UseWhilstWalking = false`. With toggle disabled, use the configured hold-to-open behavior rather than expecting a single tap to keep the wheel open.

The key is registered through FiveM keymapping. Changing the server-side default does not necessarily overwrite a player's saved binding. Check **Settings → Key Bindings → FiveM** and the [keybinding guide](/docs/guides/keybindings) before repeatedly changing `Config.Keybind`.

Icon references can differ between documentation, README and frontend revisions. The pinned README mentions Font Awesome 5, while the documentation source describes support through 6.1.1. Inspect the assets actually loaded by your installed frontend instead of assuming every icon from the newest catalog will work.

## Add one client-side action

Create `resources/[local]/qbnet-help/` with the following files. This resource displays a notification and makes no server request.

### fxmanifest.lua

```lua
fx_version 'cerulean'
game 'gta5'
client_script 'client.lua'
dependency 'qb-core'
```

### client.lua

```lua
local QBCore = exports['qb-core']:GetCoreObject()

local function showHelp()
    QBCore.Functions.Notify('Use the server help page for commands.', 'primary', 5000)
end

AddEventHandler('myhelp:client:show', showHelp)
RegisterCommand('qbnet-help', showHelp, false)
```

The event is local because the configured wheel action is a client action. There is no need to expose a network event just to show this local message. Notification usage is described in [QBCore functions](/docs/core/functions).

In the server console, run `refresh` and `ensure qbnet-help`. In in-game chat, run `/qbnet-help`. **First expected result:** one help notification. If that fails, diagnose this resource and qb-core before changing the radial menu.

Then add the following entry **inside the existing `Config.MenuItems` array** in qb-radialmenu's `config.lua`:

```lua
{
    id = 'local_help',
    title = 'Help',
    icon = 'question',
    type = 'client',
    event = 'myhelp:client:show',
    shouldClose = true
},
```

This is a table entry, not a standalone Lua file. Do not replace `Config.MenuItems` with it or duplicate an existing ID. The manifest/client files belong in `qbnet-help`; the entry belongs in qb-radialmenu. Apply the config change on staging and test the wheel with its configured binding.

**Second expected result:** selecting Help closes the wheel and displays the same single notification. The independent command separates a missing handler from a menu-configuration problem.

## Add a submenu without breaking dispatch

A parent entry uses an `items` array containing child entries. Keep the parent and child IDs unique, and put the `type`, `event` and `shouldClose` fields on the actionable child:

```lua
{
    id = 'local_information',
    title = 'Information',
    icon = 'info',
    items = {
        {
            id = 'local_information_help',
            title = 'Help',
            icon = 'question',
            type = 'client',
            event = 'myhelp:client:show',
            shouldClose = true
        }
    }
},
```

Use either the single entry or this submenu during your initial test, not both copies. The structure follows the [documented menu format](https://github.com/qbcore-framework/qb-docs/blob/930c12ec4f60dfbba60253571f1a58980129516d/qbcore-resources/qb-radialmenu.md).

For state-changing gameplay actions, the menu only requests an operation. Implement permissions and current-state checks on the server; a hidden wheel option is not authorization. See [safe server events](/docs/security/safe-server-events).

## Troubleshooting

| Symptom | Isolating check |
| --- | --- |
| F1 does nothing | Inspect saved binding, hold/toggle mode, movement restrictions and first Lua error |
| Help appears but does nothing | Run `/qbnet-help`; compare the event string and `type = 'client'` |
| The command works but the wheel does not | Inspect the entry's placement, unique ID and loaded config |
| An icon is blank | Inspect the icon assets/classes in the installed frontend |
| A role-specific option is absent | Check live job, duty and context conditions, not just the job label |
| Menu stays open or controls remain captured | Verify close handling and the selected action's behavior |

## Trunk-door changes and runtime boundary

The current `server/trunk.lua` adds player-ped, nearby-vehicle, matching-plate and two-unit
proximity checks before broadcasting `qb-radialmenu:trunk:client:Door`. This is a change from
the older pinned handler, which broadcast the supplied plate and door arguments directly.
It still needs argument validation and an actual server-artifact test. The same file imports
only `Functions` and `Commands` from `GetCoreObject` but later calls `QBCore.Shared.Trim`.
With the reviewed filtered core object, `Shared` is absent. Include the shared namespace in
a reviewed local fix and test the complete handler; the source pin is not an endorsement of
a working trunk integration.

The new server handler calls the global `GetClosestVehicle`. Verify that this function exists
in your selected server artifact or integration before enabling the trunk flow; client native
availability alone does not establish server availability. Do not describe the added checks as
a completed security fix without testing the handler, invalid plates, missing entities and
repeated requests on staging.

## Update checklist

On staging, test the independent command, single entry, optional submenu, close/reopen, reconnect and the resolutions your players use. Confirm one selection produces one notification. Test actual job/vehicle/trunk/stretcher integrations separately; this help demo does not validate them.

To roll back, remove the added config entry, close the wheel, stop `qbnet-help` and remove its startup entry. There are no persistent records to restore. Keep config, NUI assets and client/server integration changes separately identifiable. Return to [resource references](/docs/resources) for related menus.
