Difference between revisions of "OnAcquireItem"

From NWN Lexicon
Jump to: navigation, search
(Remarks)
Line 1: Line 1:
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. 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.
+
__NOTOC__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====
 
====Trigger====
  
 
Whenever an item is added to someone's inventory.
 
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)====
 
====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.
 
* [[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
+
* [[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)
 
* [[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.
 
* [[GetModuleItemAcquiredStackSize]] - The amount of items added to an existing stack.
 +
  
 
====Remarks====
 
====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).
+
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 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.
 
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:
 +
 +
# [[OnAcquireItem]] for each item in the inventory (including those equipped)
 +
# [[OnPlayerEquipItem]] for any item is equipped
 +
#* (Repeat 1 for each item in inventory)
 +
# [[OnClientEnter]]
 +
# [[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 [https://github.com/Beamdog/nwn-issues/issues/367 here].
 +
  
 
====Example====
 
====Example====

Revision as of 01:07, 20 August 2021

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