OnAcquireItem

The script attached to this event fires when an item is acquired on a PC or NPC creature. The item can be tested against a list of items, and if the item is found an event could occur such as the corpses around the PC arising to fight them in undeath or a journal entry is made.

Trigger

Whenever an item is added to a creatures inventory. They can be a PC or NPC - it would be recommended to use GetIsPC at the top of the script and exit early if you don't care that NPCs are getting items.

It also fires whenever the OnClientEnter script would fire for a PC. It fires before the OnClientEnter Event starts, for all the items in the PC's inventory (including those equipped!). This is new, quite recent behavior change for this event.

Function(s)

• GetModuleItemAcquired - The item acquired (or altered in the case of stack changes). Invalid in the case of pure gold, see below for notes.
• GetModuleItemAcquiredBy - The PC acquiring the item. Note: see Known Bugs
• GetModuleItemAcquiredFrom - The person who has lost the item (may be invalid if created using a script, or picked up off the ground)
• GetModuleItemAcquiredStackSize - The amount of items added to an existing stack.

Remarks

Since GetModuleItemAcquiredStackSize() returns the change in stack sizes if something is added to an existing stack, it will fire for when a PC picks up a potion and it is adding to an existing stack of potions. If GetModuleItemAcquiredFrom() is invalid, it could have been from a Barter screen or the ground. Pickpocketed items do trigger the module events, and such stolen items are automatically marked as stolen - retrievable by GetStolenFlag(object oItem).

This event fires for gold but in this case the item is invalid (OBJECT_INVALID) and the only valid information is item stack size.

This event will not fire when moving items to/from containers such as Magical Bags.

The event will not fire when obtaining items put on the creature by EffectPolymorph - since all polymorph effects are script driven you can get these items through checking slots just as the polymorph is applied.

Player Login Order

Important mainly for multiplayer servers, the order of events of a player entering is:

1. OnAcquireItem for each item in the inventory (including those equipped)
2. OnPlayerEquipItem for any item is equipped
   • (Repeat 1 for each item in inventory)
3. OnClientEnter
4. Removal of expired effects, eg will run EffectRunScript sOnRemovedScript script
5. OnEnter - Order: Triggers, Area of Effects then the Area they are in.

Known Bugs

On the first login after module start the object references returned by GetModuleItemAcquiredBy and GetPCItemLastEquippedBy are correct. On subsequent logins on the same module session, the object references returned by the aforementioned functions will be OBJECT_INVALID.

To work around this use GetItemPossessor on the item relevant to the event. This has been reported in detail here.

Example

// Writes an entry in the logfile whenever a PC acquires an
// item, if the script is put OnAcquireItem. The entry will
// contain info about the PC acquiring the item, the item,
// and the object the item was acquired from
void main()
{
    object oItem = GetModuleItemAcquired();
    object oPC = GetModuleItemAcquiredBy();
    // Note: you can use GetItemPossessor(oItem); to get oPC
    object oLostBy = GetModuleItemAcquiredFrom();

    string sLog = GetName(oPC) + " acquired " + GetName(oItem) + " from " + GetName(oLostBy);
    PrintString(sLog);
}

See Also

functions:

GetModuleItemAcquiredStackSize, GetModuleItemAcquired, GetModuleItemAcquiredBy, GetModuleItemAcquiredFrom

---