Get the creature or object who possesses a specified item.
Returns the object which has oItem in its inventory.
Returns OBJECT_INVALID if item was not found in any object's inventory.
Note that it could be in the possession of a store object, a placeable (with inventory) object, or a creatures inventory (which is what is usual).
Basically, if it return OBJECT_INVALID, it is either on the ground, in "limbo" during a PC to PC transaction (Barter), or oItem doesn't exist.
Things are a bit complicated if you have multiple copies of an item, all with the same tag. If you want to get the nearest creature which possesses the item, you can't just use GetNearestObjectByTag() to identify the item, because this function does not work on objects in a creature's inventory.
You have to use GetObjectByTag(), using the "nNth" argument to cycle through all copies in the game. Then use GetItemPossessor() to determine the owner of each item, and GetDistanceToObject() to determine which creature is nearest.
Note, of course, that if an object possesses oItem, then GetItemPossessedBy(oPossessor, GetTag(oItem)) will return that item, or, as noted above, one with the same tag.
// or somethings inventory, we will tell the first PC who has it.
// Get the first PC in the module (suitable for singleplayer games)
object oPC = GetFirstPC();
// Get the crown
object oCrown = GetObjectByTag("KING_CROWN");
// Get the possessor
object oPossessor = GetItemPossessor(oCrown);
// Tell the PC about the possessor
// Tell the PC about who has it
SendMessageToPC(oPC, "The kings crown is held by " + GetName(oPossessor));
// It is on the ground/somewhere else, tell them.
SendMessageToPC(oPC, "The kings crowm is probably on the ground right now");
author: Jason Harris, editor: Jasperre, additional contributor(s): Charles Feduke, Jasperre