> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fzd-scripts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure FzD Action Wheel, including frameworks, inventory, controls, layout and persistent actions.

All server-owner settings for FzD Action Wheel live in:

```text theme={null}
fzd_actionwheel/shared/config.lua
```

Restart `fzd_actionwheel` after changing this file.

## Quick reference

| Setting                        | Default              | Purpose                                                    |
| ------------------------------ | -------------------- | ---------------------------------------------------------- |
| `Config.Framework`             | `'auto'`             | Auto-detect or select `qbx`, `qb`, `esx`, or `standalone`. |
| `Config.Inventory`             | `'auto'`             | Select `auto`, `ox`, `framework`, or `none`.               |
| `Config.DefaultKey`            | `'F3'`               | Default keyboard binding for new players.                  |
| `Config.KeyboardOpenMode`      | `'hold'`             | Choose `hold` or `toggle`.                                 |
| `Config.ControllerOpenControl` | `37`                 | Native controller open control; `37` is LB/L1.             |
| `Config.CommandName`           | `'actionwheel'`      | Base registered command/keymapping name.                   |
| `Config.Title`                 | `'MENU'`             | Default centre title.                                      |
| `Config.Position`              | `{ x = 70, y = 50 }` | Wheel centre as screen percentages.                        |
| `Config.Actions`               | `{}`                 | Persistent actions shown on the normal wheel.              |

## Framework

FzD Action Wheel is **standalone by default** and does not require a framework. Framework integration is only used when an action needs framework-owned player data such as jobs, grades, metadata, or framework inventory.

Set `Config.Framework` to one of the following values:

| Value          | Behaviour                                          |
| -------------- | -------------------------------------------------- |
| `'auto'`       | Automatically detects Qbox, then QBCore, then ESX. |
| `'qbx'`        | Forces Qbox integration.                           |
| `'qb'`         | Forces QBCore integration.                         |
| `'esx'`        | Forces ESX integration.                            |
| `'standalone'` | Disables framework player/job integration.         |

For most servers, the default is the easiest option:

```lua theme={null}
Config.Framework = 'auto'
```

<Info>
  Automatic detection checks **Qbox before QBCore**. This prevents Qbox's QBCore compatibility layer from being mistaken for a native QBCore installation.
</Info>

### Framework examples

<Tabs>
  <Tab title="Automatic">
    Recommended for most servers.

    ```lua theme={null}
    Config.Framework = 'auto'
    ```

    Detection order:

    1. Qbox
    2. QBCore
    3. ESX
    4. Standalone fallback

    Make sure the framework starts before `fzd_actionwheel`.
  </Tab>

  <Tab title="Qbox">
    ```lua theme={null}
    Config.Framework = 'qbx'
    ```

    Start Qbox before FzD Action Wheel. Job, grade and player metadata conditions use the Qbox adapter.

    ```cfg theme={null}
    ensure qbx_core
    ensure fzd_actionwheel
    ```

    Most Qbox servers can leave inventory detection on `auto`.
  </Tab>

  <Tab title="QBCore">
    ```lua theme={null}
    Config.Framework = 'qb'
    ```

    Start QBCore before FzD Action Wheel. Job, grade, metadata and supported framework inventory checks use QBCore player data.

    ```cfg theme={null}
    ensure qb-core
    ensure fzd_actionwheel
    ```
  </Tab>

  <Tab title="ESX">
    ```lua theme={null}
    Config.Framework = 'esx'
    ```

    Start ESX before FzD Action Wheel. Job and grade conditions use the ESX adapter.

    If you want item conditions to use ESX's player inventory:

    ```lua theme={null}
    Config.Inventory = 'framework'
    ```
  </Tab>

  <Tab title="Standalone">
    ```lua theme={null}
    Config.Framework = 'standalone'
    ```

    Unrestricted actions, vehicle-state conditions, contextual menus, exports, events and custom callbacks continue to work normally.

    Job and grade restricted actions remain hidden because standalone mode has no framework job data.

    A standalone server can still use `ox_inventory` for item conditions:

    ```lua theme={null}
    Config.Inventory = 'ox'
    ```
  </Tab>
</Tabs>

### What framework integration affects

Framework integration is only needed for conditions that depend on framework-owned player data, including:

* `job`
* `jobGrade`
* player `metadata`
* framework-backed `items` checks

Other Action Wheel features do not require a framework.

For example:

```lua theme={null}
{
    id = 'police_menu',
    label = 'Police',
    icon = 'shield-halved',
    job = 'police'
}
```

See [Conditions](/scripts/action-wheel/guides/conditions) for all supported restrictions and examples.

## Inventory

`Config.Inventory` controls where item-count conditions get their information.

| Value         | Behaviour                                                                        |
| ------------- | -------------------------------------------------------------------------------- |
| `'auto'`      | Prefer `ox_inventory` when running, otherwise use supported framework inventory. |
| `'ox'`        | Force `ox_inventory`.                                                            |
| `'framework'` | Use the active framework's inventory data.                                       |
| `'none'`      | Disable inventory-backed item checks.                                            |

For most servers:

```lua theme={null}
Config.Inventory = 'auto'
```

<Note>
  Item conditions only **check** whether the player has the required items. FzD Action Wheel does not consume items and should not replace server-side authorization or validation in the resource performing the action.
</Note>

### Common framework and inventory combinations

```lua theme={null}
-- Qbox with automatic inventory detection
Config.Framework = 'qbx'
Config.Inventory = 'auto'
```

```lua theme={null}
-- Native QBCore inventory
Config.Framework = 'qb'
Config.Inventory = 'framework'
```

```lua theme={null}
-- ESX framework inventory
Config.Framework = 'esx'
Config.Inventory = 'framework'
```

```lua theme={null}
-- Fully standalone
Config.Framework = 'standalone'
Config.Inventory = 'none'
```

```lua theme={null}
-- Standalone with ox_inventory
Config.Framework = 'standalone'
Config.Inventory = 'ox'
```

## Controls and keybinds

### Keyboard and mouse

By default, hold **F3** to open the normal wheel. Move the mouse to reveal the cursor, hover an action and left-click to select it.

* Right-click or Escape goes back one level and closes at the root.
* `Config.KeyboardOpenMode = 'toggle'` changes F3 to press-to-open / press-to-close.
* Players can remap the binding in **FiveM Settings → Key Bindings → FiveM**.

To change the default keyboard binding for new players:

```lua theme={null}
Config.DefaultKey = 'F3'
```

To change the keyboard open behaviour:

```lua theme={null}
Config.KeyboardOpenMode = 'hold'
```

or:

```lua theme={null}
Config.KeyboardOpenMode = 'toggle'
```

### Controller

Controller support is built into the Action Wheel rather than treated as a separate optional mode.

| Input         | Behaviour                                             |
| ------------- | ----------------------------------------------------- |
| Hold LB/L1    | Open the normal player wheel.                         |
| Right stick   | Point at an action.                                   |
| RB/R1         | Enter a submenu or confirm.                           |
| Release LB/L1 | Select a highlighted leaf action on the normal wheel. |
| B/Circle      | Go back or close.                                     |
| A/Cross       | Also confirms in contextual menus.                    |

Returning the right stick to centre clears the selection. Releasing LB/L1 while centred, or while a submenu is highlighted, closes without activating a leaf action.

The default controller open control is:

```lua theme={null}
Config.ControllerOpenControl = 37
```

`37` corresponds to **LB/L1**.

<Info>
  The default LB/L1 binding replaces the game's controller weapon-wheel control while FzD Action Wheel is in use. Walking and driving remain available while the menu is open.
</Info>

## Wheel position

```lua theme={null}
Config.Position = {
    x = 70,
    y = 50
}
```

* `x` is clamped between **12 and 88**.
* `y` is clamped between **18 and 82**.

Use these values to move the wheel away from HUD elements or other server UI.

## Title

The default centre title is controlled by:

```lua theme={null}
Config.Title = 'MENU'
```

## Command name

The base command/keymapping name is:

```lua theme={null}
Config.CommandName = 'actionwheel'
```

Change this if it conflicts with another resource on your server.

## Persistent actions

`Config.Actions` contains actions that should always be available on the normal wheel.

```lua theme={null}
Config.Actions = {
    {
        id = 'server:emotes',
        label = 'Emotes',
        icon = 'hand',
        clientEvent = 'my_emotes:open'
    }
}
```

For the complete action format and all supported fields, see [Action schema](/scripts/action-wheel/reference/action-schema).

## Startup order

If you use a framework or inventory resource, start it before FzD Action Wheel.

```cfg theme={null}
ensure your_framework
ensure your_inventory
ensure fzd_actionwheel
ensure your_integrating_resource
```

Resources that require FzD Action Wheel should also declare it in their `fxmanifest.lua`:

```lua theme={null}
dependency 'fzd_actionwheel'
```