Koja Scripts

Server exports

Every server export of koja-inventory-v2 with arguments, return values and examples, including durability, drops, locations and hooks.

Server exports

Call them on exports['koja-inventory-v2']. The resource name has dashes, so use the bracket form.

local ok, reason = exports['koja-inventory-v2']:AddItem(source, 'water', 2)

target below is a player server id or a container id (stash:<name>, trunk:<plate>, glovebox:<plate>). See Database for all container ids.

Inventory

ExportReturnsDescription
AddItem(target, name, count, metadata?)true or false, reasonAdds items, stacking first and then finding free space across pockets and the worn backpack. Reasons: invalid_item, no_inventory, too_heavy, no_space.
RemoveItem(target, name, count, metadata?, itemId?)booleanRemoves items. Fails without removing anything if there are not enough.
GetItemCount(target, name, metadata?)numberTotal units.
HasItem(target, name, count?)booleanAt least count (default 1). Always available.
CanCarryItem(target, name, count, metadata?)true or false, reasonChecks weight and grid space without changing anything.
GetInventoryItems(target)table[]{ name, label, count, metadata, slot, container, weight } for every item. slot is the item id.
Search(target, 'count'|'slots', names, metadata?)number, table[] or a table by nameCounts or lists items by name.
SetMetadata(target, itemId, metadata)booleanReplaces the metadata of one item.
ClearInventory(target, keep?)trueRemoves everything except item names in keep.
OpenInventory(source, type, data)booleanOpens an inventory for a player: 'player', id, 'stash', name, 'shop', name.

Single items

ExportReturnsDescription
GetItem(target, itemId)table or nil{ id, name, label, count, metadata, container, weight, durability }.
SetDurability(target, itemId, value)booleanSets durability (0 to 100).
AddDurability(source, itemId, amount)new value or falseAdds (positive) or removes (negative) durability. Removing goes through the normal wear rules, so the item can break.
GetWeight(target)current, maxCarried weight in grams and the limit.
A lockpick that only wears when it fails
exports['koja-inventory-v2']:RegisterUsableItem('lockpick', function(source, item)
    local success = math.random() < 0.6
    if not success then
        exports['koja-inventory-v2']:AddDurability(source, item.id, -25)
    end
    return false
end)

Returning false from the use handler skips the automatic per-use wear from Config.Durability.tools, so only your own call changes the durability.

Drops

ExportReturnsDescription
CreateDrop(coords, items)drop id or nilCreates a drop on the ground. items is a list of { name = , count = , metadata = } or { name, count, metadata }. Merges with a nearby drop like a normal drop.
exports['koja-inventory-v2']:CreateDrop(vec3(25.7, -1347.3, 29.49), {
    { name = 'water', count = 3 },
    { 'WEAPON_PISTOL', 1, { ammo = 12 } },
})

Locations

Stashes, shops and crafting benches created at runtime. They are saved, show up in the admin panel's Locations tab, get a point and a sign for every player, and survive restarts.

ExportReturnsDescription
CreateLocation(data)id or false, reasonCreates a location.
UpdateLocation(id, data)true or false, reasonChanges fields of a runtime location.
RemoveLocation(id)booleanDeletes it. Stash contents stay in the database.
GetLocations()table[]All runtime locations.
local id = exports['koja-inventory-v2']:CreateLocation({
    kind = 'stash',
    id = 'ballas_stash',
    label = 'Ballas stash',
    coords = vec3(85.2, -1959.4, 20.75),
    radius = 1.5,
    jobs = { ballas = 0 },
    width = 10,
    height = 8,
    maxWeight = 150000,
    shared = true,
})
FieldKindsDescription
kindall'stash', 'shop' or 'crafting'.
idallOptional. Lowercase letters, digits and _, 2 to 32 characters. Generated when empty. Must not clash with a config name.
label, coords, radius, jobs, blipallName, position, interaction radius (0.5 to 10), { job = minGrade }, map blip.
width, height, maxWeight, sharedstashGrid, weight limit, shared or per player.
width, itemsshopGrid width and { { name, price, stock? } }.
recipescraftingRecipe ids from Config.Recipes.

Reasons: invalid, invalid_name, name_taken, no_items, no_recipes.

Stashes and shops (native mode)

ExportDescription
RegisterStash({ name, label, coords?, radius?, width, height, maxWeight?, jobs?, shared?, owner? })Registers a stash. owner (string) makes it private to that identifier.
RegisterShop({ name, label, locations?, jobs?, width?, items })Registers or replaces a shop.

With ox mode on, use the ox signatures instead: RegisterStash(name, label, slots, maxWeight, owner, groups, coords) and RegisterShop(type, { name, inventory, locations, groups }).

Usable items and clothing

ExportDescription
RegisterUsableItem(name, function(source, item) end)Runs when the item is used. item is { name, id, count, meta, container }. Return false to cancel consuming it.
AddClothing(target, category, drawable, texture, gender?)Gives a clothing item, e.g. AddClothing(source, 'jackets', 22, 1). Categories are the keys in Config.Clothing.categories.
GetItemDefinitions(name?)One item definition or all of them.

Hooks

ExportDescription
RegisterHook(event, callback, options?)Same as ox registerHook. Returns a hook id. See Events and hooks.
RemoveHooks(id?)Removes one hook, or every hook of the calling resource.
ExportDescription
RegisterSearchCheck(function(target) end)Lets your script decide if a player can be frisked. Return true to allow, false to block, nil to let the default checks (hands up, cuffed, dead) decide.
IsBeingSearched(target)true while someone is frisking that player.

More

  • Runtime items: RegisterItem, RegisterItems, CreateItem, RemoveItemDefinition, GetDynamicItems.
  • Custom slots: RegisterSlot, RemoveSlot, GetSlotItem, SetSlotItem, GetSlots.