Lua functions

RemoveItem

Registered in this checkout as EQ2Emu_lua_RemoveItem; implementation found at WorldServer/Lua/LuaFunctions.cpp:1825.

Historical signature: RemoveItem(spawn, item_id, quantity)

Parameter and behavior details in the historical explanation are under review against the current implementation.

Function: RemoveItem(spawn, item_id, quantity)

Description: Removes units from the first matching item in a player's inventory. A missing or zero quantity defaults to one. If the requested quantity reaches or exceeds that item's count, the entire item is removed; the function does not combine several matching stacks to satisfy a larger request.

Parameters:

  • spawn (Spawn) - The player whose inventory should change.
  • item_id (uint32) - A positive item definition ID, rather than an allocation's unique ID.
  • quantity (uint16, optional) - Number of units to remove. Defaults to one.

Returns: On normal return, a boolean: true when the exact selected original commits its inventory change, or false for invalid input, a missing original, changed session/publication, busy native or save admission, or a conflicting item-use reservation. The return value describes the inventory change; failure to construct an inventory packet does not turn a completed removal into false.

Behavior: The selected original allocation is retained before native admission; a later item with the same item ID or unique ID cannot replace it. Native count/removal and original save ownership commit before notifications. An item's removed(Item, Player) callback runs for the accepted original while that original player's audience remains current. Partial removal passes the remaining original stack; full removal retains the detached original through its admitted work. Removing a bag also removes its original contents only if the complete change can be admitted together. Reconnect or publication replacement stops later old-audience effects.

A script consuming its own reserved item uses that same reservation. Only an accepted native change marks its automatic charge as script handled. A rejected or temporarily busy change leaves the original charge obligation intact. A packet rejection does not undo an accepted inventory change; dirty packet work remains pending. Entered callbacks are never replayed by save recovery.

Trade completion commits both inventories and coin balances and closes its transaction before delivering removal, quest, and obtained callbacks. Reentrant callbacks can modify the completed inventories or start a new trade without interrupting the committed exchange.

Connection lifetime: Each player or group-member connection resolved by this function is retained through the native call. A disconnect or reconnect during a callback cannot destroy that retained connection or switch the ongoing call to a replacement. A later Lua call resolves the current connection. This does not extend the lifetime of unrelated spawn or item userdata.

Checked example

Active call in a local runtime Lua script. Argument count matches current fixed C++ readers. This is a contextual call pattern, not a tested standalone script.

RemoveItem(Spawn,9357,1)

Evidence: server/SpawnScripts/FarJourneyFreeport/HelmsmanNyles.lua:131; binding EQ2Emu_lua_RemoveItem.

Current registration: WorldServer/Lua/LuaInterface.cpp. Historical explanation: EQ2Emu Lua documentation.