en-inventory

en-inventory is a spatial grid inventory in the style of Resident Evil or DayZ. Every container is a grid of cells, and every item takes up a w x h footprint that you can rotate. Players carry an 8x6 grid with a 30 kg base limit and a 5-slot hotbar, and can wear a bag (a backpack or duffel) that adds its own grid underneath.

TAB opens your inventory next to whatever is nearby: a glovebox when you are in a vehicle, a trunk when you stand behind an unlocked vehicle, a stash, a ground bag, or an empty "ground" grid to drop items onto. Weapons are items that carry their own magazine ammo and durability. When you die, part of your gear spills into a persistent death bag marked on your map.

#At a glance

#How it works

#The grid

• An item instance is { id, name, count, x, y, rotated, metadata }. x and y are the top-left cell, starting at 1. A stack is one instance with count above 1, using the same footprint.
• Rotating swaps an item's width and height.
• When space is needed, rows are scanned top to bottom, left to right, trying the item upright first and then rotated.
• Adding items first tops up existing stacks with identical metadata, then places new stacks. AddItem and CanCarryItem use the same plan, so they always agree.
• Weight is weight x count, plus metadata.contentWeight for bags that hold items.
• The server is authoritative on every move. The client uses the same maths only to preview drags.

A player's max weight is Config.player.maxWeight plus Player(src).state.carryBonus (from en-skills) plus Player(src).state.bagCapacity (from en-clothing). Changes to those state bags update the limit live.

#Containers

Every server action re-checks that the player can reach the container: distance (with 1.5 m slack for drops and stashes), group rules, canOpen, and being inside the vehicle for gloveboxes.

#Backpacks

The item in en-clothing's bag slot, if its definition has a container, gets its own grid shown under the player's grid. The storage id is kept in the worn item's metadata.container, and the weight of its contents is written to metadata.contentWeight, so the bag stays heavy when you take it off. A bag's contents are only reachable while it is worn, and bags never go inside bags.

#Weapons

Weapons are equipped from the inventory or hotbar. Their rounds live in metadata.ammo, synced every 5 seconds and after firing. R reloads from matching ammo items (player grid first, then bag). Each shot wears the weapon down, and a weapon at 0 durability is holstered. GTA's weapon wheel and weapon number keys are disabled by default.

#Death bags

When en-core reports a death (encore:server:playerDied, with a 10 second debounce):

1. A share of carried cash (cashPercent) always drops.
2. Each stack rolls to drop: the item's deathDrop, else its category chance, else itemChance.
3. Each worn clothing piece rolls clothingChance. A worn bag rolls bagChance and takes its contents with it.

The bag persists across restarts until it is emptied or reaches lifetimeHours. The owner gets a map blip for their newest bag.

#Configuration

#config/shared.lua

Default trunk sizes: default = { 6, 4, 50.0 }, compacts { 5, 3, 35 }, SUVs { 8, 5, 90 }, vans { 10, 6, 220 }, commercial { 12, 8, 400 }. Motorcycles, cycles and trains are false (no trunk).

#config/server.lua

A stash entry takes id, label, coords, distance, width, height, maxWeight, plus optional personal, shared and groups. groups accepts:

-- config/server.lua
ServerConfig.death.cashPercent = 1.0   -- lose all carried cash
ServerConfig.death.lifetimeHours = 6

ServerConfig.stashes = {
    {
        id = 'burton_locker', label = 'Checkpoint Locker',
        coords = vec3(-255.1, -299.4, 21.6), distance = 1.5,
        width = 10, height = 8, maxWeight = 200.0,
        personal = true,
    },
    {
        id = 'clinic_supplies', label = 'Clinic Supplies',
        coords = vec3(1839.2, 3672.9, 34.3), distance = 2.0,
        width = 8, height = 6, maxWeight = 120.0,
        groups = { medic = 0 },
    },
}

#Item definitions

data/items.lua returns a table keyed by item name. Weapon items use the weapon name, such as WEAPON_PISTOL. Cash is an item too: cash, 1x1, weight 0, stacks to 1,000,000.

-- data/items.lua
scrap_radio = {
    label = 'Broken Radio',
    description = 'Might be worth something for parts.',
    category = 'material', size = { 2, 1 }, weight = 0.8, stack = 4,
    usable = true, consume = 1,
},

See Add an item for a full walkthrough.

#Exports

#Server: the inventory contract

These names are a contract that other resources rely on through encore.inventory.* in the en-core library. See Inventory interface.

#Server: additional

#Client

#Commands

Restricted to ServerConfig.adminPrincipal (default group.admin).

#Events

#Client (local)

Listen with AddEventHandler.

#Server (local)

en-inventory reacts to encore:server:onPlayerLoaded, encore:server:onPlayerUnload, encore:server:playerDied, en-clothing:server:loaded and txAdmin:events:serverShuttingDown on the server, and encore:client:playerLoaded, playerUnloaded and playerDied on the client.

#Look options

With en-target running, en-inventory adds:

• A global vehicle option en-inventory:trunk ("Open trunk") on the boot bone.
• "Search bag" (or "Search" plus the bag label) on ground bag and death bag props.
• A sphere zone "Open" plus the stash label for each config stash.

#State bags

#Database

There is one row per container. A corrupt row refuses to load rather than being overwritten, so a bad write never wipes a player's items.

#Examples

A usable bandage:

-- server
encore.inventory.registerUsable('bandage', function(source, item, slot)
    local ped = GetPlayerPed(source)
    SetEntityHealth(ped, math.min(200, GetEntityHealth(ped) + 20))
    return true -- consume one
end)

A base storage box that another resource registers and opens:

-- server
exports['en-inventory']:RegisterStash('en-bases:box:42', {
    label = 'Supply Crate', width = 8, height = 6, maxWeight = 120.0,
    coords = vec3(1200.0, -300.0, 69.0), distance = 2.0,
    canOpen = function(src) return true end,
})

-- client
exports['en-inventory']:OpenInventory({ kind = 'stash', id = 'en-bases:box:42' })

Pay a reward that never gets lost when the player is full:

-- server
local placed, dropped = exports['en-inventory']:AddItemOrDrop(source, 'cash', 250)
if dropped and dropped > 0 then
    encore.notify(source, { title = 'Inventory', description = 'Some of it fell at your feet.', type = 'inform' })
end

#Related

• Inventory interface
• Add an item
• Money and cash
• en-clothing
• en-respawn