OnPlayerUseItem

The player’s game used an item - a potion, food, a book, a letter, a map; return false to cancel its effect, or (for a checked item) the use itself.

A potion drunk, food eaten, an ointment applied - and a book read, a letter or a map opened, a recipe learned: every use the player’s inventory makes comes here (a repair kit’s repair is no use: OnPlayerItemWear hears it). For a consumable the server looked the class up in the game’s tables (Consumables) and is about to add health to its own vitals (a potion’s heal-over-time runs at [combat] potion_speed times the game’s pace) and give the buff buff (GivePlayerBuff). Return false to cancel both

• the item is gone from the player’s inventory either way, their game consumed it. Anything else (a book, a letter, a map) comes with health 0 and no buff, after the game used it - its false changes nothing.

Deciding before the use. For an item class or category named with SetItemUseCheck this comes before the game uses the item: the player’s game holds the use and waits, and false refuses it - the book stays shut, the bread uneaten, the item where it was. Anything else lets the game use it (and the server’s effect follows without a second call). Tell the player why yourself (ShowNotification, SendClientMessage).

A use of an item the server’s records say the player never held - or any use in the first seconds of a visit, before the server follows the player’s bag - is refused first under [audit] mode = "enforce" (observe only logs that it would be). Food eaten from a cooking pot or a table is no item of the bag: the server takes it as food from the world, at most 50 health a minute and never a buff. A drink raises the alcohol level on the side (OnPlayerDrunk).

Syntax

function OnPlayerUseItem(pid, class, health, buff, id)
  -- ...
end

Parameter	Type
pid	number	the player
class	string	the item’s class GUID (GetItemName turns it into a name)
health	number	the health the server is about to add (a negative number hurts); 0 for anything that is no consumable
buff	string	the buff GUID the server is about to give; "" = none
id	string	the item’s id when it is one of the mode’s tagged items (GivePlayerTaggedItem), "" otherwise

Returns

false cancels the health and the buff - and, for a checked item, the use itself; anything else lets them through

Example

-- nothing heals in the arena; bandages (an Ointment) still stop the bleeding
function OnPlayerUseItem(pid, class, health, buff)
  local info = GetItemInfo(class)
  if inArena[pid] and info and info.category ~= "Ointment" and health > 0 then
    SendClientMessage(pid, COLOR_RED, "That does nothing in the arena.")
    return false
  end
end

-- the sealed orders can only be read by the captain
SetItemUseCheck("sealed_orders", true)
function OnPlayerUseItem(pid, class, health, buff)
  if GetItemName(class) == "sealed_orders" and not isCaptain[pid] then
    ShowNotification(pid, "The seal is not yours to break.")
    return false
  end
end

See also

SetItemUseCheck · GivePlayerBuff · OnPlayerDrunk · GetItemInfo · OnPlayerAuditViolation · the Buffs and the drink group of the index