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.