# 1 · Setup & Access

Install Nord Inventory, choose a framework, configure administrator access and set the core runtime options.

# Requirements & Installation

## Requirements

| Requirement | Status |
|---|---|
| FiveM / OneSync | Required |
| MySQL or MariaDB | Required |
| `oxmysql` | Required |
| ESX / QBCore / Qbox / Nord Core | Optional |
| `ox_lib` | Not required |
| Target resource | Optional |

Nord Inventory can use its own Text UI, so a target resource is not mandatory.

## Resource installation

1. Copy `nord_inventory` to your resources folder.
2. Make sure `oxmysql` is available and started first.
3. Keep the resource folder named exactly `nord_inventory`.
4. Add the ACE permission for admins.
5. Ensure the resource in `server.cfg`.

```cfg
add_ace group.admin nord_inventory.admin allow

ensure oxmysql
ensure nord_inventory
```

## Database setup

On startup, Nord Inventory creates/migrates its tables. You can also run the provided `sql/nord_inventory.sql` manually.

The main tables are:

- `nord_inventory_storage`
- `nord_inventory_custom_items`
- `nord_inventory_item_versions`
- `nord_inventory_custom_categories`
- `nord_inventory_preferences`
- `nord_inventory_transactions`
- `nord_inventory_vehicle_categories`
- `nord_inventory_vehicle_models`

## Startup order

A safe example:

```cfg
ensure oxmysql
ensure qbx_core        # or qb-core / es_extended / nord-core when used
ensure nord_inventory
```

Framework resources should normally be started before Nord Inventory so `Config.Framework = 'auto'` can detect them during initialization.

## First boot verification

Check the server console for the framework bridge line:

```text
[nord_inventory] Framework bridge: qb
```

The final value can be `qb`, `esx`, `qbox`, `nord` or `standalone`.


# Framework Detection

Set the framework mode in `config.lua`:

```lua
Config.Framework = 'auto' -- auto | esx | qb | qbox | nord | standalone
```

## Auto-detection order

When set to `auto`, Nord checks resources in this order:

1. `qbx_core` → Qbox
2. `qb-core` → QBCore
3. `es_extended` → ESX
4. `nord-core` → Nord Core
5. Nothing matched → standalone

## Player identifiers

Nord uses a stable identifier appropriate to the active bridge:

| Framework | Identifier basis |
|---|---|
| QBCore | `citizenid` |
| ESX | player `identifier` |
| Qbox | `citizenid` |
| Nord Core | `citizenid`/identifier when available |
| Standalone fallback | FiveM `license:` identifier, then first identifier |

## Jobs and restricted storage

Job access checks use the framework job name and numeric grade. Example:

```lua
jobs = {
    police = 0,
    sheriff = 2
}
```

A player must have a listed job and a grade greater than or equal to the configured minimum.

## Hunger and thirst

- QBCore: updates player metadata hunger/thirst.
- ESX: uses `esx_status:add` for hunger/thirst.
- Other modes: emits `nord_inventory:server:consume` so a custom framework can react.
- Health/armor effects are applied by Nord on the client after server validation.

## Forcing standalone mode

If you use a custom framework and want Nord to avoid detecting a supported framework:

```lua
Config.Framework = 'standalone'
```

You can then integrate your own status/identity systems around Nord's public exports and events.


# Admin Access · ACE + License Fallback

Nord Inventory v1.6.11 supports two administrator authorization methods without exposing license identifiers to the client.

## Access order

The server resolves admin access in this order:

1. **Console** — server console commands are trusted.
2. **ACE** — checks the configured ACE object.
3. **License fallback** — checks the player's FiveM `license:` identifier against the private allowlist.

## ACE configuration

The default ACE object is:

```lua
Config.AdminAce = 'nord_inventory.admin'
```

Recommended `server.cfg`:

```cfg
add_ace group.admin nord_inventory.admin allow
```

You can assign a license to a group through ACE if you prefer central permission management:

```cfg
add_principal identifier.license:YOUR_LICENSE group.admin
```

## Direct license fallback

Edit only:

```text
nord_inventory/server/config.lua
```

Example:

```lua
Config.AdminAccess = {
    UseAce = true,
    Ace = Config.AdminAce or 'nord_inventory.admin',
    LicenseFallback = true,
    Licenses = {
        'license:0123456789abcdef0123456789abcdef01234567',
        '89abcdef0123456789abcdef0123456789abcdef', -- hash-only is accepted
    }
}
```

## Security notes

- `server/config.lua` is listed only under `server_scripts`.
- Admin license identifiers are never loaded client-side.
- Keep the license list out of shared config files and NUI JavaScript.
- ACE remains the preferred method when you already manage staff groups centrally.
- The fallback is useful when ACE is unavailable, misconfigured or intentionally not used.

## Admin Studio

The default command is:

```text
/norditems
```

Admin commands use the same access resolution, so ACE and license fallback apply consistently.


# Admin Commands

All commands in `Config.AdminCommands` require Nord Inventory admin access. They can be renamed or have aliases removed in `config.lua`.

| Default command | Purpose |
|---|---|
| `/giveitem` / `/nordgiveitem` | Give an item to a player |
| `/givecash` / `/nordgivecash` | Give cash currency item |
| `/givedirtymoney` / `/nordgivedirtymoney` | Give dirty-money currency item |
| `/removeitem` / `/nordremoveitem` | Remove an item by name |
| `/removeslot` / `/nordremoveslot` | Remove from a specific slot |
| `/clearinventory` / `/clearinv` | Clear all or one item type |
| `/openinventory` / `/openinv` | Open another player's inventory as admin |
| `/setmetadata` / `/setmeta` | Replace metadata on a slot |
| `/setdurability` / `/repairitem` | Set/repair durability |
| `/itemcount` | Count an item in a player's inventory |
| `/iteminfo` | Show item and metadata for a slot |
| `/saveinventory` / `/saveinv` | Force-save a player inventory |
| `/listitems` | Search the active item registry |

## Example metadata command

```text
/setmetadata 12 4 {"quality":"premium","serial":"NORD-001"}
```

## Disable command set

```lua
Config.AdminCommands.Enabled = false
```

The Admin Studio can remain available even if you choose to disable these convenience commands.


# Core Configuration

The complete configuration is in `config.lua`. The values below are the defaults shipped with v1.6.11.

## General

```lua
Config.Framework = 'auto'
Config.Locale = 'en'
Config.Debug = false

Config.OpenCommand = 'inventory'
Config.OpenKey = 'TAB'
Config.AdminCommand = 'norditems'
Config.AdminAce = 'nord_inventory.admin'
```

## Inventory capacity defaults

```lua
Config.DefaultPlayerSlots = 40
Config.DefaultPlayerWeight = 80000 -- grams
Config.DefaultStashSlots = 60
Config.DefaultStashWeight = 150000
Config.TrunkSlots = 50
Config.TrunkWeight = 120000
Config.GloveboxSlots = 10
Config.GloveboxWeight = 15000
```

Weights are stored in grams in the default configuration.

## Sessions and persistence

```lua
Config.InventorySessionSeconds = 300
Config.SaveIntervalSeconds = 30
Config.MaxTransferAmount = 100000
Config.MaxContainerDepth = 3

Config.EnableWeight = true
Config.EnableVolume = false
Config.EnableDurability = true
Config.EnableItemHistory = true
Config.TransactionLogRetentionDays = 14
```

## UI defaults

```lua
Config.UI = {
    theme = 'dark',
    columns = 7,
    slotSize = 'medium',
    showWeight = true,
    animations = true,
    hotbarSlots = 5,
    hotbarKeybinds = true
}
```

## Standalone hotbar

```lua
Config.Hotbar = {
    Enabled = true,
    Command = 'hotbar',
    OpenKey = 'Z',
    Mode = 'timed', -- timed | toggle
    Duration = 3200,
    ShowOnSlotUse = false
}
```

## Ground inventory

```lua
Config.GroundOpenDistance = 3.0
Config.GroundDrawDistance = 15.0
Config.GroundPropDistance = 35.0
Config.GroundDefaultModel = 'prop_cs_cardbox_01'
Config.GroundLifetimeSeconds = 1800
Config.GroundSlots = 30
Config.GroundWeight = 250000
Config.ThrowMaxDistance = 8.0
Config.ThrowMaxHeightDifference = 4.0
```

See the dedicated Vehicle Storage and Interaction pages for nested vehicle/target settings.
## Weapon magazine configuration added in v1.6.9+

```lua
Config.WeaponAmmo = {
    Enabled = true,
    DefaultMagazineSize = 30,
    MaxMagazineSize = 999,
    DetectMagazineFromGame = true,
    AutoReloadDelay = 260,
    ReloadCooldown = 650,
    ManualReloadControl = 45,
}
```

`DefaultMagazineSize` is only a bootstrap fallback until the weapon instance has authoritative `metadata.magazineSize`.


# Interaction Providers

Nord can use its own Text UI or a target resource for ground items, configured stashes and vehicle trunks.

## Built-in Text UI

Default configuration:

```lua
Config.Interaction = {
    Mode = 'textui',
    TextUI = 'default',
    Target = 'auto',
    Key = 'E',
    Control = 38,
    OxLibPosition = 'right-center'
}
```

`TextUI = 'default'` uses Nord's built-in UI and has no `ox_lib` requirement.

## ox_lib TextUI

Switch the Text UI provider without changing interaction mode:

```lua
Config.Interaction.Mode = 'textui'
Config.Interaction.TextUI = 'ox_lib'
```

## Target mode

```lua
Config.Interaction.Mode = 'target'
Config.Interaction.Target = 'auto'
```

Supported target choices in the bridge are:

- `auto`
- `ox_target`
- `qb-target`
- `nord_target`

If a selected/auto-detected target provider is unavailable, Nord can continue using its own interaction fallback where implemented.

## Custom Text UI bridge

```lua
Config.Interaction.TextUI = 'custom'

Config.Interaction.Custom = {
    Show = function(data)
        -- show your UI
    end,
    Hide = function()
        -- hide your UI
    end
}
```

The callbacks run client-side.


# Locales

Nord Inventory v1.6.11 ships with:

- `locales/en.json`
- `locales/pt.json` (Portuguese, PT-PT)

Select the active locale:

```lua
Config.Locale = 'en'
-- Config.Locale = 'pt'
```

Fallback behavior:

```lua
Config.LocaleFallback = 'en'
Config.LocalePath = 'locales'
```

## What the locale system covers

The dictionaries cover the player inventory, Admin Studio, Personal Studio, item management, vehicle storage, imports/exports, context menus, world interactions, use progress text, server notifications and command/admin feedback.

## Item-specific text is preserved

Item labels, descriptions and runtime-created custom text are treated as item data, not as generic interface translation keys. Nord does not automatically rewrite an item label just because the UI locale changes.

## Missing keys

English is used as a fallback when the selected locale does not contain a key.