# Configuration (/docs/orbit-studios-resources/orbit-lib/configuration)



# Configuration [#configuration]

Edit `resources/[orbit]/orbit-lib/config.lua`.

`orbit-lib` is the bridge layer. Other Orbit resources call it when they need player data, inventory actions, item counts, notifications, progress bars, and framework-specific helpers. If a value here points at the wrong framework or resource name, the dependent resource usually fails later with missing exports, missing items, or empty player data.

<TypeTable
  type="{
  'Config.Debug': {
    type: 'boolean',
    default: 'false',
    description: 'Enables debug prints for bridge behavior.',
  },
  'Config.Framework': {
    type: '&#x22;esx&#x22; | &#x22;qb&#x22; | &#x22;qbx&#x22; | &#x22;standalone&#x22;',
    description: 'Framework adapter used by Orbit resources.',
    required: true,
  },
  'Config.Standalone': {
    type: 'table',
    description: 'Standalone identifier, cache, default money/job data, and optional adapters.',
  },
  'Config.TargetResource': {
    type: '&#x22;ox_target&#x22; | &#x22;qb-target&#x22;',
    description: 'Target resource used for interaction zones.',
    required: true,
  },
  'Config.Inventory': {
    type: '&#x22;ox_inventory&#x22; | &#x22;qb-inventory&#x22; | &#x22;ps-inventory&#x22; | &#x22;lj-inventory&#x22; | &#x22;qb-like&#x22; | &#x22;ox-like&#x22;',
    description: 'Inventory adapter used by Orbit resources.',
    required: true,
  },
  'Config.CustomInventory': {
    type: 'string | nil',
    description: 'Resource name when using qb-like or ox-like custom inventory exports.',
  },
  'Config.CustomExport': {
    type: 'string | nil',
    description: 'Inventory export name when it differs from Config.CustomInventory.',
  },
  'Config.Notify': {
    type: '&#x22;framework&#x22; | &#x22;ox_lib&#x22; | &#x22;orbit-dynamichud&#x22; | string',
    description: 'Notification provider used by Orbit resources.',
  },
  'Config.Progress': {
    type: '&#x22;framework&#x22; | &#x22;ox_lib&#x22; | &#x22;orbit-dynamichud&#x22;',
    description: 'Progress provider used by Orbit resources.',
  },
  'Config.Gangs': {
    type: 'table',
    description: 'Optional gang resolver configuration for QB/QBX style access rules.',
  },
}"
/>

## Framework Presets [#framework-presets]

Pick one framework preset first, then adjust the target, inventory, notification, and progress providers to match the resources actually started on your server.

<Tabs groupId="framework" items="['ESX', 'QB', 'QBX', 'Standalone']">
  <Tab value="ESX">
    ```lua title="resources/[orbit]/orbit-lib/config.lua"
    Config.Framework = 'esx'
    Config.TargetResource = 'ox_target'
    Config.Inventory = 'ox_inventory'
    Config.Notify = 'ox_lib'
    Config.Progress = 'ox_lib'
    ```
  </Tab>

  <Tab value="QB">
    ```lua title="resources/[orbit]/orbit-lib/config.lua"
    Config.Framework = 'qb'
    Config.TargetResource = 'qb-target'
    Config.Inventory = 'qb-inventory'
    Config.Notify = 'framework'
    Config.Progress = 'framework'
    ```
  </Tab>

  <Tab value="QBX">
    ```lua title="resources/[orbit]/orbit-lib/config.lua"
    Config.Framework = 'qbx'
    Config.TargetResource = 'ox_target'
    Config.Inventory = 'ox_inventory'
    Config.Notify = 'ox_lib'
    Config.Progress = 'ox_lib'
    ```
  </Tab>

  <Tab value="Standalone">
    ```lua title="resources/[orbit]/orbit-lib/config.lua"
    Config.Framework = 'standalone'
    Config.TargetResource = 'ox_target'
    Config.Inventory = 'ox_inventory'
    Config.Notify = 'ox_lib'
    Config.Progress = 'ox_lib'

    Config.Standalone = {
        identifierType = 'license',
        playerDataCache = 1000,
        defaultMoney = {
            cash = 0,
            bank = 0,
            dirty = 0
        },
        defaultJob = {
            name = 'unemployed',
            label = 'Unemployed',
            grade = {
                name = 'Unemployed',
                level = 0
            }
        },
        fetchName = nil,
        fetchCharInfo = nil,
        fetchMoney = nil,
        fetchJob = nil,
        createUsableItem = nil
    }
    ```
  </Tab>
</Tabs>

## Supported Providers [#supported-providers]

These are the supported values from `config.lua`. Use the exact lowercase key in the config, not the display name.

<Tabs items="['Frameworks', 'Targets', 'Inventories', 'Notifications', 'Progress Bars']">
  <Tab value="Frameworks">
    | Config value | Use when                                                                          |
    | ------------ | --------------------------------------------------------------------------------- |
    | `esx`        | Your server runs ESX Legacy or another ESX-compatible setup.                      |
    | `qb`         | Your server runs QBCore and exposes QB-style player data.                         |
    | `qbx`        | Your server runs QBX/Qbox and uses QB-style data with modern Qbox resources.      |
    | `standalone` | You do not use ESX, QB, or QBX and will provide standalone adapters where needed. |

    Framework selection controls how `orbit-lib` reads player identifiers, names, character info, money, jobs, gangs, and usable-item behavior.
  </Tab>

  <Tab value="Targets">
    | Config value | Resource                                                             | GitHub                                                                      |
    | ------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
    | `ox_target`  | Overextended target system for entity, zone, and world interactions. | [overextended/ox\_target](https://github.com/overextended/ox_target)        |
    | `qb-target`  | QBCore target interaction system.                                    | [qbcore-framework/qb-target](https://github.com/qbcore-framework/qb-target) |

    Target resources are used when Orbit resources create interaction points, such as crafting stations.
  </Tab>

  <Tab value="Inventories">
    | Config value   | Resource or mode                                              | GitHub                                                                            |
    | -------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
    | `ox_inventory` | Overextended inventory. Recommended for OX/QBX style servers. | [overextended/ox\_inventory](https://github.com/overextended/ox_inventory)        |
    | `qb-inventory` | Official QBCore inventory.                                    | [qbcore-framework/qb-inventory](https://github.com/qbcore-framework/qb-inventory) |
    | `ps-inventory` | Project Sloth inventory.                                      | [Project-Sloth/ps-inventory](https://github.com/Project-Sloth/ps-inventory)       |
    | `lj-inventory` | LJ inventory.                                                 | [loljoshie/lj-inventory](https://github.com/loljoshie/lj-inventory)               |
    | `qb-like`      | Custom inventory with QB-style exports.                       | Custom resource                                                                   |
    | `ox-like`      | Custom inventory with OX-style exports.                       | Custom resource                                                                   |

    Inventory support is used for item counts, adding/removing items, metadata, image paths, and usable-item behavior. For `qb-like` or `ox-like`, set `Config.CustomInventory` to the actual resource name and `Config.CustomExport` only when the export name differs from the resource name.
  </Tab>

  <Tab value="Notifications">
    | Config value       | Provider                                | Use when                                                                                      |
    | ------------------ | --------------------------------------- | --------------------------------------------------------------------------------------------- |
    | `framework`        | ESX/QB/QBX native notification wrapper. | You want Orbit resources to use your framework's normal notification behavior.                |
    | `ox_lib`           | `lib.notify`.                           | You have `ox_lib` installed and want consistent ox\_lib notifications.                        |
    | `orbit-dynamichud` | DynamicHUD notification event.          | You have `orbit-dynamichud` installed and want notifications shown through the HUD interface. |

    Do not use `orbit-dynamichud` as the notification provider unless `orbit-dynamichud` is installed and started after `orbit-lib`.
  </Tab>

  <Tab value="Progress Bars">
    | Config value       | Provider                                  | Use when                                                                              |
    | ------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------- |
    | `framework`        | ESX/QB/QBX progress wrapper.              | Your framework already provides a progress bar you want Orbit resources to use.       |
    | `ox_lib`           | `lib.progressBar` / `lib.progressCircle`. | You want progress handled by `ox_lib`.                                                |
    | `orbit-dynamichud` | DynamicHUD interface integration.         | You want Orbit resources to integrate progress UI through DynamicHUD where supported. |
  </Tab>
</Tabs>

## Provider Rules [#provider-rules]

Use real resource names and supported provider keys:

<TypeTable
  type="{
  'Config.TargetResource': {
    type: '&#x22;ox_target&#x22; | &#x22;qb-target&#x22;',
    description: 'Use the target resource that is already installed and ensured before orbit-lib.',
  },
  'Config.Inventory': {
    type: '&#x22;ox_inventory&#x22; | &#x22;qb-inventory&#x22; | &#x22;ps-inventory&#x22; | &#x22;lj-inventory&#x22; | &#x22;qb-like&#x22; | &#x22;ox-like&#x22;',
    description: 'Use a built-in adapter when possible. Use qb-like or ox-like only for custom inventories with compatible exports.',
  },
  'Config.Notify': {
    type: '&#x22;framework&#x22; | &#x22;ox_lib&#x22; | &#x22;orbit-dynamichud&#x22; | string',
    description: 'Use framework for native framework notifications, ox_lib for lib.notify, orbit-dynamichud for HUD notifications, or a custom provider when configured.',
  },
  'Config.Progress': {
    type: '&#x22;framework&#x22; | &#x22;ox_lib&#x22; | &#x22;orbit-dynamichud&#x22;',
    description: 'Use framework, ox_lib, or orbit-dynamichud depending on the UI provider you want running on the server.',
  },
}"
/>

Do not set a provider to a resource that is not running. For example, `Config.Notify = 'orbit-dynamichud'` only makes sense when `orbit-dynamichud` is installed and started after `orbit-lib`.

## Standalone Adapters [#standalone-adapters]

Standalone mode uses defaults until you provide adapters.

<TypeTable
  type="{
  'Config.Standalone.identifierType': {
    type: '&#x22;license&#x22; | &#x22;steam&#x22; | &#x22;discord&#x22; | &#x22;fivem&#x22; | string',
    default: '&#x22;license&#x22;',
    description: 'Identifier used as citizenid in standalone mode.',
  },
  'Config.Standalone.playerDataCache': {
    type: 'number',
    default: '1000',
    description: 'How long client-side standalone player data stays cached in milliseconds.',
  },
  'Config.Standalone.fetchName': {
    type: 'nil | function(source, playerState)',
    description: 'Optional function that returns the display name.',
  },
  'Config.Standalone.fetchCharInfo': {
    type: 'nil | function(source, playerState, defaults)',
    description: 'Optional function that returns character info.',
  },
  'Config.Standalone.fetchMoney': {
    type: 'nil | function(source, playerState, defaults)',
    description: 'Optional function that returns cash, bank, and dirty money.',
  },
  'Config.Standalone.fetchJob': {
    type: 'nil | function(source, playerState, defaults)',
    description: 'Optional function that returns job data.',
  },
  'Config.Standalone.createUsableItem': {
    type: 'nil | function(item, callback)',
    description: 'Optional function used to register usable items without a framework.',
  },
}"
/>

The default standalone data is useful for testing, but production standalone servers usually need at least money and job adapters so HUDs, access checks, and logs show real values.

```lua title="resources/[orbit]/orbit-lib/config.lua"
Config.Standalone.fetchMoney = function(source, playerState, defaults)
    return {
        cash = defaults.cash,
        bank = defaults.bank,
        dirty = defaults.dirty
    }
end
```

```lua title="resources/[orbit]/orbit-lib/config.lua"
Config.Standalone.fetchJob = function(source, playerState, defaults)
    return {
        name = defaults.name,
        label = defaults.label,
        grade = defaults.grade
    }
end
```

If you use standalone mode with a custom inventory, implement `createUsableItem` only when another Orbit resource needs usable-item registration and your inventory does not already provide a native framework callback.

## Custom Inventory [#custom-inventory]

Use this only when the inventory follows a QB-like or OX-like export shape but runs under a custom resource name.

```lua title="resources/[orbit]/orbit-lib/config.lua"
Config.Inventory = 'qb-like'
Config.CustomInventory = 'my_inventory'
Config.CustomExport = 'my_inventory'
```

Set `Config.CustomExport` only when the export name is different from the resource name.