OnAcquireItem

From NWN Lexicon
Revision as of 01:07, 20 August 2021 by Jasperre (talk | contribs)
Jump to: navigation, search

The script attached to this event fires when an item is acquired. 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 someone's inventory.

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)


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.


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. OnEnter (of the area they're put into then any triggers/traps they are on top of)


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