Features#

Every feature below can be switched off live on the admin Addon Management page (key in brackets). A disabled feature falls back to stock ox_inventory behaviour.

The inventory window#

Open it with F2 (inventory:keys). The top bar has five tabs:

• Pockets — the first 5 slots are the hotbar (keys 1–5).
• Rarity — slot borders, backgrounds and labels use the item's rarity colour.
• Tooltip — metadata, serial, durability, plates, and the contents of mini stashes and hangers. Click an item in the tooltip to take it out.
• Context menu — use, give, drop, attachments, copy serial number, rename, change description, throw, trade, open stash, insert / remove plate.
• Multi-select (multiselect) — SHIFT + click several slots, then drag them together.
• Rename & describe (rename) — players can rename an item (max 32 characters) and change its description (max 160). Both are stored in the item metadata.

Fast actions#

The row under the right inventory has drop tiles and buttons:

Give and Trade are hidden when nobody is in range, Hands up while you sit in a vehicle. The list comes from fastActions in data/koja/core.lua.

Ped preview#

While the inventory is open your ped is shown in the clothes panel:

• Clone ped (pedMode = 'clone') — a camera frames your ped where the clothes panel is (left, center or right).
• Pause menu ped (pedMode = 'pause') — the pause-menu ped on a dark background.
• With the player setting Camera on character off, the gameplay camera stays and a copy of your ped is drawn inside the UI.

Drag the ped to rotate it. The admin switches the mode on Addon Management. Next to the ped, the panel shows health, armour, hunger and thirst (esx_status on ESX, player metadata on Qbox).

Item popups and sounds#

While the inventory is closed, items you get or lose pop up on screen in the player's style: Compact (card with image and amount) or Minimalistic (small pill). With the inventory open they are always the small version. The UI plays sounds for clicks, hover, open, close, moves, pickups, drops, equipping, success and errors. Players can turn them off in Settings.

Clothing as items#

clothing — worn clothes are real items, stored in a hidden per-character inventory.

• Drag a clothing item onto its slot in Your clothes to wear it, or drag it off to take it off.
• Gloves (arms) follow the torso.
• Clothes the ped already wears become items when the slot is empty (adoptAppearance).
• When a skin menu or outfit changes the appearance (illenium-appearance / fivem-appearance save), the worn items follow it (externalAppearance). Bag and vest stay items.
• After every change the appearance is saved through illenium-appearance / fivem-appearance (saveAppearance).
• With an appearance resource that exports getClothingImage (for example Koja Appearance), every piece shows its real thumbnail.
• An item made for the other gender cannot be worn.

Hangers#

A hanger (clothing_hanger) stores one whole outfit (bag and vest excluded).

• Use a hanger: the outfit in it and the one you wear swap places.
• Put on hanger fast action: your outfit goes into the first hanger with room and no outfit.
• Hover a hanger to see the outfit in the tooltip. The clothes panel also has a hanger quick slot.

Backpacks#

backpack — the item worn in the bag slot unlocks backpack.slots extra slots and adds backpack.weight carry weight.

• Locked slots show "Need a backpack".
• You cannot take the bag off, or swap it for a smaller one, while its extra slots still hold items or the weight would go over the limit.

Mini stashes#

ministash — items with isStash are small containers.

• Open stash in the context menu opens it as the right inventory.
• Hover it to see the contents; click an item in the tooltip to pull it into your inventory.
• Only one player can have a mini stash open at a time. A mini stash cannot be put into another one.

Armour plates#

plates — plates are inserted into the vest worn in the vest slot (armor_vest, or any item with clothing.id = 9).

• Use a plate, or pick Insert plate, to insert it (1.5 s). A vest holds up to maxPerVest (3) plates.
• Your armour is the sum of the plates, up to 100.
• Damage eats the plates from the last one inserted. A partly used plate keeps its remaining armour when taken out.
• Remove plate in the vest's context menu gives the last plate back.

Weight and overload#

weightEffects — from 85% of your max weight you walk slower, sweat and lose stamina while running. From 97% you cannot sprint or jump. All thresholds are in Configuration.

Throwing#

throw — throw an item from the context menu (Throw item), or the weapon in your hand.

• Aim with the arc and the landing marker, left mouse throws, right mouse cancels.
• Heavier stacks fly shorter. The item lands as a normal ground drop with all its metadata.
• Weapon in hand: hold the koja_throw_weapon key (middle mouse by default) to aim and charge, release to throw. Releasing too early, right mouse, ESC, switching weapons, ragdoll, death, entering a vehicle or opening the inventory cancels.
• Grenades and other thrown weapons cannot be thrown this way (denyProjectiles).
• The server checks the slot, the item and the landing distance (maxDistance).

Give#

give — give an item to a player in the world.

1. Drop the item on the Give tile#

   The UI switches to target mode and shows a ring over every player in range (give.distance, 3 m).

2. Release on a player#

   The ring under the cursor is the target; a circle is drawn on the ground under them.

3. The item is handed over#

   A short give animation plays. The server checks the distance and the slot again.

Trade#

trade — a two-sided trade, swapped by the server in one step.

1. Drop an item on the Trade tile and pick a player, or press the Trade fast action (closest player).
2. The other player gets a request: a card in the UI, or a 3D prompt with Y / N while their inventory is closed. It expires after timeout (30 s).
3. Both players pick items and amounts (up to maxOffers slots), then confirm. Changing an offer removes the other player's confirmation.
4. When both confirmed, the server checks both inventories and swaps everything at once.

A trade is cancelled when a player walks away (distance), closes the inventory, or nothing happens for sessionTimeout seconds.

Rarity and discovery#

discovery — items in other inventories stay hidden ("Discovering...") until a search time has passed.

• The time comes from the item's rarity: common 0 s, uncommon 2 s, rare 4 s, epic 6 s, legendary 8 s, mythic 10 s.
• Rarities with revealTimer show a countdown on the slot.
• Applies to player, drop, stash, trunk and glovebox inventories (discovery.types). Your own stashes are skipped.
• The server blocks taking items that are not revealed yet, and remembers what you searched for memory (600 s).

Rarities are edited on the admin Edit Rarity page.

Weapon attachments#

attachments — Attachments in the context menu of a weapon opens a 3D view.

• A marker for each component type: muzzle, flashlight, scope, magazine, grip, barrel, skin and tint.
• Click a marker to see compatible items from your inventory and attach one in place, or remove an installed one.
• Weapon tints are items (tint_1…tint_7): applying one uses the item, removing it gives it back.
• Drag on empty space to rotate the weapon, mouse wheel to zoom, Reset view to go back.
• Staff with access to Items can adjust the position of each marker per weapon (saved in koja_inv_attachment_offsets).

Shops#

Shops keep the ox_inventory format and the RegisterShop export, with a new panel:

• Grid or list view, search, and a basket with amounts, totals and a Clear button.
• Payment with Cash (the money item) or Card (the framework bank account). Confirm is disabled with the reason when you cannot afford it.
• The server prices the whole basket and checks stock, access, licence and distance before anything changes hands.
• Dragging a product onto your inventory still buys it the upstream way.
• A built-in 3D "press E" card at every shop point, so no target script is needed (shops3d).

New optional fields in data/shops.lua:

General = {
    name = 'Shop',
    paymentMethods = { 'cash', 'card' }, -- cash = money item, card = bank account
    interaction = { enabled = true, distance = 2.0, drawDistance = 8.0, key = 38 }, -- or true / false
    icon = 'fas fa-shopping-basket',     -- ox_target icon
    blip = { id = 59, colour = 69, scale = 0.8 },
    inventory = { { name = 'burger', price = 10 } },
    locations = { vec3(25.7, -1347.3, 29.49) },
},

Shops can also be created and edited live on the admin Shops pages.

Crafting#

Crafting benches keep the data/crafting.lua format. Opening a bench shows the crafting panel instead of the grid:

• A recipe list with search, and a recipe card with ingredients (have / need), output and an amount.
• Craft starts a queue (up to 100 crafts). Progress runs inside the UI with a crafting animation.
• Cancel / Cancel queue stops it. Closing the inventory, dying, ragdolling or entering a vehicle cancels too; nothing is used up for the unfinished craft.
• Ingredients below 1 are tools: they stay and lose that fraction of their durability per craft.

{
    name = 'workshop',
    label = 'Workshop',
    items = {
        { name = 'lockpick', ingredients = { scrapmetal = 3, WEAPON_HAMMER = 0.02 }, duration = 4000, count = 2 },
    },
    points = { vec3(2340.62, 3126.81, 48.21) },   -- marker + [E] without ox_target
    zones = { { coords = vec3(2340.62, 3126.81, 48.21), size = vec3(2.0, 1.0, 1.2), distance = 1.8, rotation = 350.0 } },
    blip = { id = 566, colour = 47, scale = 0.8 },
},

duration is in ms (default 3000). count is the output per craft, or { min, max } for a random amount. groups restricts the bench to jobs. Benches can also be created and edited live on the admin Crafting benches page.

World containers#

• Loot: dumpsters and the trunks / gloveboxes of vehicles nobody owns are filled the first time they are opened (inventory:randomloot). Each search rolls up to 3 rows of the loot table; a row drops with its chance and a random amount between min and max.
• Search animation: players rummage in the dumpster or at the trunk while its inventory is open.
• ox_target: without inventory:target, "Search dumpster", "Open trunk", stashes and evidence lockers are added to ox_target as extra options. The keybind and markers keep working.

The loot tables and both switches are edited on the admin World containers page.

History#

history — every inventory action (open, close, move, give, drop, pickup, buy, craft, use, trade, throw, rename, clothing, stash, admin actions) is logged to the database for the admin History page and item tracking.