item

Reads and changes an item: name, amount, owner, consume, delete, message.

Source: src/Moongate.Server.Ultima/Modules/ItemModule.cs

Functions

add_loot

item.add_loot(container, table, rolls?) -> integer

Rolls a loot table of templates/loots once, or rolls times, into a container, or into the backpack of a mobile, and gives how many items it added; 0 for rolls that give nothing, an unknown table or something that is no container; fewer than the roll gave when the container is full (125 items) or no item serial is at hand.

Parameter	Type	Default
container	integer
table	string
rolls (optional)	integer	1

Returns integer.

amount

item.amount(serial) -> integer?

The item's amount; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns integer?.

can_hold

item.can_hold(container, serial) -> boolean

Whether the container, and every container it is in, still holds its limit of stones with the item in it: the template's max_weight, 400 without one and none for 0, a bank box having none. False for an unknown container or item. The count of items a pack may hold is not asked.

Parameter	Type	Default
container	integer
serial	integer

Returns boolean.

combat_stats

item.combat_stats(serial) -> table?

What the item is in a fight, from its template, as a table: weapon_type (sword, axe, pole_arm, mace, staff, fencing, bow, crossbow, thrown) or nil, two_handed (false when the template does not say), damage_min, damage_max, speed, armor_rating and max_hits, nil for what the template does not say; nil for an item without a template or a serial that is no item.

Parameter	Type	Default
serial	integer

Returns table?.

consume

item.consume(serial, amount?) -> boolean

Takes amount units (default 1) off the item, deleting it at 0, and shows the change to the owner or the players around a ground stack; false for a worn item, an amount below 1, fewer units left or an item a player holds on the cursor.

potion.lua, the script of a potion that is drunk on a double click:

potion = {}

function potion.on_use(serial, user)
    item.message(serial, user, "You drink the potion.")
    item.consume(serial)

    return true
end

Parameter	Type	Default
serial	integer
amount (optional)	integer	1

Returns boolean.

container

item.container(serial) -> integer?

The serial of the container the item lies in; nil for an item on the ground, a worn one or an unknown one.

Parameter	Type	Default
serial	integer

Returns integer?.

contents

item.contents(serial) -> table

The serials of the items lying directly in the container, as a list; empty for an empty or unknown container.

The items lying directly in a container:

for _, inside in ipairs(item.contents(bag)) do ... end

Parameter	Type	Default
serial	integer

Returns table.

create

item.create(template, map, x, y, z, amount?) -> integer?

Makes an item from a template on the ground at x, y, z of the map, seen by the players around, and gives its serial; nil for an unknown template, a spot outside the map, a z outside -128 to 127, an amount the template cannot have, or when no serial is ready, as item.give.

Parameter	Type	Default
template	string
map	MapType | string
x	integer
y	integer
z	integer
amount (optional)	integer	nil

Returns integer?.

delete

item.delete(serial) -> boolean

Deletes the item; false for a worn item, a held item or a container that still holds items.

Parameter	Type	Default
serial	integer

Returns boolean.

durability

item.durability(serial) -> table?

The hits and the maximum hits of a weapon or a piece of armor, as { hits, max }: its durability and max_durability props, or the template's max_hits for a piece that never wore. Nil for an item that cannot wear (no max_hits) or an unknown one.

Whether a piece is worn down:

local hits = item.durability(serial)

if hits and hits.hits < hits.max then
    mobile.message(user, "It needs mending.")
end

Parameter	Type	Default
serial	integer

Returns table?.

dyeable

item.dyeable(serial) -> boolean

Whether the item's template is dyeable, as clothing is: a dye tub can give it its hue; false for an unknown item.

Parameter	Type	Default
serial	integer

Returns boolean.

equip

item.equip(serial, mobile) -> boolean

Puts the item on the mobile, on its template's layer, seen by everyone around; its script runs on_equip, its can_equip is not asked. False for a worn or held item, a stack, an item without a layer or one the mobile cannot wear, a taken layer, a mobile not in the world, or an item another mobile carries.

Taken from a chest on the ground, those who look into the chest see it go.

Parameter	Type	Default
serial	integer
mobile	integer

Returns boolean.

find

item.find(holder, template) -> table

The serials of the items of a template inside a container, at any depth, or worn and carried by a mobile (not what lies in its bank), as a list; empty when there is none, or for an unknown container or mobile.

The gold a player carries, pile by pile:

for _, coins in ipairs(item.find(user, "gold")) do ... end

Parameter	Type	Default
holder	integer
template	string

Returns table.

get_prop

item.get_prop(serial, key) -> any?

A value the item keeps across restarts: a string, a number or a bool; nil when it has none.

Parameter	Type	Default
serial	integer
key	string

Returns any?.

give

item.give(mobile, template, amount?, hue?) -> integer?

Makes an item from a template in the mobile's backpack and gives its serial; what stacks joins the stack of its kind already lying in the backpack (same template, hue and name, no prop of its own, 60000 at most) and the serial is that stack's. The owner sees it at once and its next save keeps it. Nil for an unknown mobile or template, a mobile without a backpack, an amount the template cannot have (more than 1 of what does not stack), a hue outside 0 to 65535, or when no serial is ready: the server keeps 64 in reserve and refills them in the background, so making more in one go gives nil for the rest; try again later. hue, when given, colours the item before it looks for a stack, so it joins only a stack of that colour.

Parameter	Type	Default
mobile	integer
template	string
amount (optional)	integer	nil
hue (optional)	integer	nil

Returns integer?.

has_room

item.has_room(mobile, template, amount?) -> boolean

Whether item.give(mobile, template, amount) would find room: the mobile has a backpack, the template can be made in that amount, and the item either joins a stack of its kind or the backpack takes one more item. Nothing is made. False for an unknown mobile or template, a mobile without a backpack, or an amount the template cannot have. It does not look at the weight, as item.give does not, and it cannot know that the pool of serials is empty.

Ask before taking something to give something back, as the quests do before a turn-in:

if not item.has_room(user, "healpotion", 2) then
    mobile.message(user, "Your pack is full.")
    return
end

Parameter	Type	Default
mobile	integer
template	string
amount (optional)	integer	nil

Returns boolean.

has_room_for_all

item.has_room_for_all(mobile, items) -> boolean

Whether item.give would find room for all the items of the list together, a list of { template, amount } tables (amount 1 when left out): what joins a stack of its kind in the backpack, or another new item of the list, needs no slot, the others take one each. False for an unknown mobile or template, a mobile without a backpack, an entry that is no table or has no template; true for an empty list.

The same for several items together; what joins a stack needs no slot:

local reward = { { template = "gold_coin", amount = 100 }, { template = "healpotion", amount = 2 } }

if item.has_room_for_all(user, reward) then ... end

Parameter	Type	Default
mobile	integer
items	table

Returns boolean.

hue

item.hue(serial) -> integer?

The item's hue, 0 for the colours of its art; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns integer?.

in_range

item.in_range(serial, mobile, range) -> boolean

Whether the mobile is on the map of a ground item and within range tiles of it, the larger of the two differences; false for an item not on the ground, a mobile not in the world or a negative range.

if item.in_range(serial, user, 2) then ... end

Parameter	Type	Default
serial	integer
mobile	integer
range	integer

Returns boolean.

is_container

item.is_container(serial) -> boolean

Whether the item's template is a container, as the spells of the lock and of the trap ask; false for an item whose template is not one or an unknown item.

Parameter	Type	Default
serial	integer

Returns boolean.

is_held

item.is_held(serial) -> boolean

Whether a player has lifted the item and holds it on the cursor: it still counts where it was taken from until it is dropped, and item.consume and item.set_item_id refuse it. False for an unknown item.

Parameter	Type	Default
serial	integer

Returns boolean.

is_movable

item.is_movable(serial) -> boolean

Whether the item can be picked up: its own flag, else its template's, else the tiledata's weight (255 cannot be lifted); false for an unknown item.

Parameter	Type	Default
serial	integer

Returns boolean.

is_stackable

item.is_stackable(template) -> boolean

Whether the items of a template stack: the template's stackable, else the tiledata of its graphic. False for an unknown template.

Parameter	Type	Default
template	string

Returns boolean.

item_id

item.item_id(serial) -> integer?

The item's graphic; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns integer?.

layer

item.layer(serial) -> string?

The layer a worn item is on, as a lowercase name such as backpack, bank or one_handed; nil for an item that is not worn, lies in a container or on the ground, and for an unknown one.

Parameter	Type	Default
serial	integer

Returns string?.

location

item.location(serial) -> table?

Where a ground item lies, as a table { x, y, z, map }; nil for an item not on the ground.

Parameter	Type	Default
serial	integer

Returns table?.

look

item.look(target, player) -> boolean

Shows the player what a single click on the item or the mobile shows: the first line of its tooltip, its name (with title, amount and the name its template gives), as a label over it seen by that player only. False for an unknown serial, a player not in the world, or something the player cannot see.

Parameter	Type	Default
target	integer
player	integer

Returns boolean.

loot_type

item.loot_type(serial) -> string?

What happens to the item when its owner dies, as its own loot type or its template's: regular, newbied, blessed or cursed; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns string?.

message

item.message(serial, player, text) -> boolean

A label over the item seen only by that player (cut to 128 characters); false for blank text, an unknown item or a player not in the world.

Parameter	Type	Default
serial	integer
player	integer
text	string

Returns boolean.

message_cliloc

item.message_cliloc(serial, player, cliloc, args?) -> boolean

A label over the item seen only by that player, with a text of the client by its number, in the client's language; args fill its ~1_NAME~ places, split by tabs. False when the player or the item is not in the world.

Parameter	Type	Default
serial	integer
player	integer
cliloc	integer
args (optional)	string	nil

Returns boolean.

move_into

item.move_into(serial, container, transfer?) -> boolean

Moves the item into a container, or into a mobile's backpack; those who saw it lose it and the new owner sees it. No weight or item limit is checked. False for a worn or held item, a target that is not a container, a container put into itself or into what it holds, or an item one mobile carries moved to another mobile (a trade, not supported yet) unless transfer is true, as a theft does: the item is then saved by its new owner's leave or the world save, and until then a crash gives it back to the old one. A part cut off a pile with item.split is a new item with its own row: a crash between the owners' saves can lose it, or leave it in both packs.

Players who have a container on the ground open do not see it change until they open it again.

Parameter	Type	Default
serial	integer
container	integer
transfer (optional)	boolean	nil

Returns boolean.

move_to

item.move_to(serial, x, y, z) -> boolean

Moves a ground item to x, y, z on its map: the players around the old spot lose it, those around the new one see it, and a decaying item's decay starts again; false for an item not on the ground, a spot outside the map or a z outside -128 to 127.

Parameter	Type	Default
serial	integer
x	integer
y	integer
z	integer

Returns boolean.

name

item.name(serial) -> string?

The item's name, or its template id when it has none; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns string?.

owner

item.owner(serial) -> integer?

The serial of the mobile carrying or wearing the item; nil on the ground or unknown.

A cursed ring: once worn, it stays on. A worn item has an owner and lies in no container:

ring = {}

function ring.can_pick_up(serial, picker)
    -- worn: it has an owner and lies in no container
    if item.owner(serial) == picker and item.container(serial) == nil then
        mobile.message(picker, "The ring will not come off.")
        return false
    end
end

Parameter	Type	Default
serial	integer

Returns integer?.

play_sound

item.play_sound(serial, sound) -> boolean

Plays a sound id (0 to 65535) where the item lies, or where the mobile carrying it stands, for the players within 15 cells; false for an unknown item, a sound out of range or an item inside a container on the ground.

Parameter	Type	Default
serial	integer
sound	integer

Returns boolean.

script

item.script(serial) -> string?

The script_id of the item's template, such as 'door' or 'dye_tub'; nil for an item whose template has no script, or an unknown item.

Parameter	Type	Default
serial	integer

Returns string?.

search

item.search(text, limit?) -> table

Finds item templates whose id or name holds the text, without regard to case, and those of the graphic when the text is a number (3903 or 0xF3F), sorted by id, as a list of { id, name, graphic } with the template's id as the name when it has none. limit is the most to give, 40 by default and between 1 and 100; empty for a blank text.

Parameter	Type	Default
text	string
limit (optional)	integer	40

Returns table.

set_amount

item.set_amount(serial, amount) -> boolean

Sets the stack's amount (1 to 60000), shown to the players who see it; false for a worn or held item, an amount out of range, or an amount above 1 on an item that does not stack, as its template or its graphic says.

Parameter	Type	Default
serial	integer
amount	integer

Returns boolean.

set_durability

item.set_durability(serial, hits, max) -> boolean

Sets the hits and the maximum hits of a weapon or a piece of armor, keeping them on the item across restarts; the hits are kept from 0 to the maximum, and its tooltip shows them again. False for an item that cannot wear (no max_hits), one that is worn, one on a player's cursor, a maximum under 1 or an unknown item.

A reward that mends the piece a player carries:

local hits = item.durability(serial)

if hits then
    item.set_durability(serial, hits.max, hits.max)
end

Parameter	Type	Default
serial	integer
hits	integer
max	integer

Returns boolean.

set_hue

item.set_hue(serial, hue) -> boolean

Changes the item's hue (0 to 65535), shown to the players who see it; false for a worn or held item.

Parameter	Type	Default
serial	integer
hue	integer

Returns boolean.

set_item_id

item.set_item_id(serial, graphic) -> boolean

Changes the item's graphic (0 to 65535), as a door opening, shown to the players around a ground item or the owner of a carried one; an item inside a container on the ground changes without being shown again. False for an unknown, worn or held item or a graphic out of range.

Parameter	Type	Default
serial	integer
graphic	integer

Returns boolean.

set_light

item.set_light(serial, type?) -> boolean

Sets the item's light shape by LightType name, such as circle150, circle300 or west_big, nil clears it; the players who see the item are shown it again, and the client draws the light only for a lit graphic. False for an unknown shape or a worn or held item.

Parameter	Type	Default
serial	integer
type (optional)	string	nil

Returns boolean.

set_name

item.set_name(serial, name?) -> boolean

Sets the item's own name (cut to 128 characters), nil gives it back its template's, shown to the players who see it; false for a worn or held item.

Parameter	Type	Default
serial	integer
name (optional)	string	nil

Returns boolean.

set_prop

item.set_prop(serial, key, value?) -> boolean

Keeps a string, a number or a bool on the item across restarts, saved by the world save or its owner's save; nil removes it. False for a table, a function, a blank key or a timer.<name> key, which the item's timers use.

Parameter	Type	Default
serial	integer
key	string
value (optional)	any	nil

Returns boolean.

set_rarity

item.set_rarity(serial, rarity) -> boolean

Sets the item's rarity: 'common', 'uncommon', 'rare', 'epic' or 'legendary'; its tooltip shows a rarity above common, in its colour, and an item of another rarity does not join its stack. False for an unknown item or rarity.

A reward chest that makes one of its prizes rare:

local prize = item.give(user, "0x13ff")

if prize then
    item.set_rarity(prize, "rare")
end

Parameter	Type	Default
serial	integer
rarity	string

Returns boolean.

show_contents

item.show_contents(container, player) -> boolean

Opens the container on the player's client, with the items directly inside it, as a double click would, with no check of whether the player may: the script has decided. False for a serial that is not an item container, or a player not in the world.

Parameter	Type	Default
container	integer
player	integer

Returns boolean.

split

item.split(serial, amount) -> integer?

Cuts amount units off a stack: the item keeps amount of them and a new item holds the rest where the stack lay, with its props and hue; gives the serial of the rest. Nil for an item that is no stack, held or worn, an amount under 1 or not under the stack's, an unknown item, or when no serial is left.

Parameter	Type	Default
serial	integer
amount	integer

Returns integer?.

start_timer

item.start_timer(serial, name, seconds) -> boolean

Starts, or starts again from now, a timer of the item that runs on_timer(serial, name) of its script after that many seconds, also after a restart; one whose script has no on_timer, or fails, is dropped with a warning in the log. False for an unknown item, a blank name or one over 32 characters, or seconds not above 0 or over a year.

The timers are kept in the props timer.<name>, which item.set_prop refuses; splitting a stack leaves them with the part that is lifted.

Parameter	Type	Default
serial	integer
name	string
seconds	number

Returns boolean.

stop_timer

item.stop_timer(serial, name) -> boolean

Stops a timer of the item; false for an unknown item or when it has no timer of that name.

Parameter	Type	Default
serial	integer
name	string

Returns boolean.

template

item.template(serial) -> string?

The id of the item's template; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns string?.

timer

item.timer(serial, name) -> number?

The seconds a timer of the item still has to run, 0 when it is due; nil for an unknown item or when it has no timer of that name.

Parameter	Type	Default
serial	integer
name	string

Returns number?.

unequip

item.unequip(serial) -> boolean

Takes the worn item off its wearer and puts it into the wearer's backpack, as a disarm does: everyone around sees it go and the wearer sees it in the pack. No weight or item limit is checked. False for an item nobody wears, one held on the cursor, one that cannot be moved, the backpack, the bank box, the mount, the hair and the face, a wearer not in the world or with no backpack.

Parameter	Type	Default
serial	integer

Returns boolean.

weight

item.weight(serial) -> integer?

The stones the item weighs, with everything inside it: each pile is its unit weight times its amount, rounded up, as its tooltip says; nil for an unknown item.

Parameter	Type	Default
serial	integer

Returns integer?.

worn_by

item.worn_by(serial) -> integer?

The serial of the mobile that wears the item or holds it in its hands (a backpack is worn too); nil for an item inside a backpack or another container, on the ground, lifted onto a player's cursor or unknown.

An axe chops only in the hands of who uses it, not from the backpack:

if item.worn_by(serial) ~= user then
    mobile.message(user, "Take the axe in your hands first.")
end

Parameter	Type	Default
serial	integer

Returns integer?.