Function: GetItemByID(player, item_id, count = 1, include_bank = 0)
Returns an original character item matching a definition ID and stack quantity.
Parameters: player must be a Player. item_id is the definition ID.
count is the requested quantity (an omitted/zero value becomes 1). The engine
prefers an exact stack count, then the smallest matching stack with a greater
count. include_bank is a numeric 0/1 flag read by GetInt8Value; use 1 to include
bank locations. The legacy getter's bag and appearance selection is preserved.
Returns: One item userdata value when found; otherwise no value (nil in
a Lua expression), with an error log. This function does not consume items.
local item = GetItemByID(Player, 123, 1, 1)
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.