# Runtime items

Other resources can create item definitions without touching `shared/items.lua`. Good for fines, tickets, documents, keys and anything a script owns.

```lua title="server.lua"
exports['koja-inventory-v2']:RegisterItem('police_fine', {
    label = 'Fine',
    description = 'Pay it at the city hall.',
    size = { 1, 1 },
    weight = 5,
    stack = 1,
    category = 'docs',
    rarity = 'uncommon',
    imageUrl = 'nui://koja-mdt/web/images/fine.png',
    close = true,
}, function(source, item)
    TriggerClientEvent('koja-mdt:client:showFine', source, item.meta)
end)

exports['koja-inventory-v2']:AddItem(playerId, 'police_fine', 1, { label = 'Fine #2041', amount = 500, officer = 'J. Kowalski' })
```

## Fields

| Field | Description |
|---|---|
| `label`, `description` | Text (64 and 256 characters max). |
| `size` | `{ w, h }`, 1 to 10 each. |
| `weight`, `stack` | Grams and stack size. `stack = false` means 1. |
| `category`, `rarity` | As in [Items](/new/inventory-v2/items). |
| `image` | File name in the image path, or `imageUrl` with a `nui://` or `https://cfx-nui-` address. |
| `prop`, `degrade`, `consume`, `uses`, `use`, `hold`, `usable`, `close` | As in [Items](/new/inventory-v2/items). |
| `persist` | `false` for a temporary item that is not saved. |

Everything is sanitised and clamped to safe ranges.

## Behaviour

- The optional third argument (or `onUse` in the table) is the use handler, the same as `RegisterUsableItem`.
- Definitions are saved and come back after a restart, so items players hold never break. Calling `RegisterItem` again with the same name updates the item.
- Items from `shared/items.lua` and ox data cannot be overwritten (`false, 'exists'`).
- Clients and the UI get the new item right away. Items that were waiting for a definition (for example after a restart) are placed as soon as it is registered.
- The same items can be created and edited in `/invadmin` → Settings → Item definitions.

## Other exports

| Export | Description |
|---|---|
| `RegisterItems({ name = def, ... })` | Registers many at once and returns a table of results by name. |
| `CreateItem(name, def, handler?)` | Alias of `RegisterItem`. |
| `RemoveItemDefinition(name)` | Stops saving the item. It stays defined until the next restart. |
| `GetDynamicItems()` | All runtime items. |

The server event `koja-inventory-v2:itemsReady` fires when the inventory starts. Register your items there too, so they come back if the inventory restarts while your resource keeps running:

```lua
local function registerItems()
    exports['koja-inventory-v2']:RegisterItem('police_fine', { label = 'Fine', size = { 1, 1 }, weight = 5 })
end

AddEventHandler('koja-inventory-v2:itemsReady', registerItems)
CreateThread(registerItems)
```