Lua functions

GetEquippedItemByID

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

Historical signature: GetEquippedItemByID(…) via current binding

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

Function: GetEquippedItemByID(player, item_id)

Returns the first equipped item matching an item definition ID.

Parameters: player must be a Player. item_id is the item definition ID, not its unique character-item ID. The normal equipment collection is searched.

Returns: One item userdata value when found; otherwise no value (nil in a Lua expression), with an error log for invalid input or a missing item.

local item = GetEquippedItemByID(Player, 123)
if item ~= nil then print(GetItemID(item)) end

Original item lifetime: The collection selects and acquires the original item loan while holding its lock. Marshalling admits that loan into the protected Lua invocation. The userdata itself remembers a weak original allocation control; saved Lua values cannot extend publication or follow address reuse. An admitted invocation keeps its original item through retirement/expiration until the callback ends. Later invocations reject retired originals. See Lua actor lifetime.

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.

StartDialogConversation(conversation, 4, GetEquippedItemByID(Spawn, 157116), Spawn, "Prey is close.")

Evidence: server/ZoneScripts/FrostfangSea.lua:117; binding EQ2Emu_lua_GetEquippedItemByID.

Current registration: WorldServer/Lua/LuaInterface.cpp.