Koja Scripts

Runtime items

Create item definitions from other resources at runtime with RegisterItem, for fines, tickets, documents and other script items.

Runtime items

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

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

FieldDescription
label, descriptionText (64 and 256 characters max).
size{ w, h }, 1 to 10 each.
weight, stackGrams and stack size. stack = false means 1.
category, rarityAs in Items.
imageFile name in the image path, or imageUrl with a nui:// or https://cfx-nui- address.
prop, degrade, consume, uses, use, hold, usable, closeAs in Items.
persistfalse 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

ExportDescription
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:

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)