UgCore.Items

Server Client Proxied to ug-core. Items are defined by owners in config/items.lua and by resources at runtime. Inventories that hold them come from the inventory module.

Config

config/items.lua

return {
    water = { label = 'Water', weight = 500, maxStack = 10 },
    bread = { label = 'Bread', weight = 250, maxStack = 10 },
    phone = { label = 'Phone', weight = 200, stack = false, keepOnRespawn = true, description = 'Calls and messages.' },
}

Field	Required	Meaning
`label`	Yes	Display name, up to 64 characters.
`weight`	Yes	Grams per unit, 0 to 1,000,000.
`stack`	No	`false` puts every unit in its own slot. Defaults to `true`.
`maxStack`	No	Units per slot, 1 to 1,000,000.
`description`	No	Up to 256 characters.
`keepOnRespawn`	No	Survives `clearOnRespawn` in `config/inventory.lua`.

Item names are lowercase letters, digits and underscores. The file replaces the default items entirely.

Register

UgCore.Items.Register(name, definition)

Adds an item from a resource. Same fields as the config, plus metadata:

UgSchemaRule | function

Checked on every write of the item’s metadata. A schema rule, or a function fun(metadata): ok, message?.

local S = UgCore.Schema

UgCore.Items.Register('id_card', {
    label = 'ID card',
    weight = 10,
    stack = false,
    metadata = S.Object({
        name = S.String({ max = 64 }),
        dob = S.String({ max = 10, pattern = '^%d%d%d%d%-%d%d%-%d%d$' }),
    }),
})

Invalid definitions raise, with the same messages as config errors.
When config/items.lua defines the same name, the config wins: its fields stay, and only your metadata rule is added. A warning is logged.
A name registered by another resource raises.
Items registered by a resource are removed when it stops.

Metadata rules

Every item’s metadata MUST be bounded data, rule or not: booleans, finite numbers, strings up to 512 characters, at most 128 entries, 6 levels deep. Vectors are not allowed, since metadata is saved as JSON.

nil metadata is always allowed. An empty table counts as nil.
Stacks only merge when their metadata is equal.
A rejected write returns invalid_args. The reason goes to the server log in debug mode.

RegisterUse

UgCore.Items.RegisterUse(name, handler, options?)

Makes an existing item usable. Players use items through Inventory.Use, which runs every check before your handler.

fun(source, item): boolean?

required

Gets the player and a copy of the slot: { slot, name, count, metadata }. Return false to refuse: nothing is consumed.

integer

default:"0"

Units removed from the slot after a successful use. 0 to 1,000.

integer

default:"0"

Milliseconds between uses of this item, per player.

boolean

default:"true"

Refuses downed and dead players.

UgCore.Items.RegisterUse('bread', function(source, item)
    local player = UgCore.Players.Get(source)

    if not player then
        return false
    end

    player:SetMetadata('hunger', math.min(100, (player:GetMetadata('hunger') or 0) + 25))
    return true
end, { consume = 1, cooldown = 2000 })

One resource per item. Handlers are removed when their resource stops.

Get / GetAll / Exists / IsUsable

UgCore.Items.Get(name) -> UgItemDefinition?
UgCore.Items.GetAll() -> table<string, UgItemDefinition>
UgCore.Items.Exists(name) -> boolean
UgCore.Items.IsUsable(name) -> boolean

table

Hide fields

string

integer

Grams per unit.

boolean

integer

1 when the item does not stack.

string?

boolean

Client

UgCore.Items.Get(name) -> UgItemDefinition?
UgCore.Items.GetAll() -> table<string, UgItemDefinition>
UgCore.Items.Exists(name) -> boolean

Definitions replicate through GlobalState['ug-core:Items'], without metadata rules. Use them for labels and weights in a UI.

Events

Event	Arguments
`ug-core:Items:Used`	`(source, name, slot, metadata)`

Hooks

Hook	Payload
`Items:BeforeUse`	`{ source, name, slot, metadata }`

It allows or cancels. A cancelled use returns no_permission and consumes nothing.

Overview

Core

Networking and security

Modules

Reference

Config

Register

Metadata rules

RegisterUse

Get / GetAll / Exists / IsUsable

Client

Events

Hooks

​Config

​Register

​Metadata rules

​RegisterUse

​Get / GetAll / Exists / IsUsable

​Client

​Events

​Hooks

Config

Register

Metadata rules

RegisterUse

Get / GetAll / Exists / IsUsable

Client

Events

Hooks