Home For Builders Scripting Tutorials Using Placeable Object Events

Using Placeable Object Events

Intended Audience:
By David Gaider

[Printer Friendly / Syntax Highlight]

Like with areas, the thing to remember when writing scripts for placeable objects is that when you using 'action'-type commands (commands that return void) the default performer is the placeable object, itself. If you want the script to tell something other than the placeable object to perform a command, you need to use the AssignCommand action.
Also keep in mind that while placeable objects are capable of performing some actions (such as ActionPlayAnimation with reference to ANIMATION_PLACEABLE_*... although not all placeables open/close or activate/deactivate), telling them to do things that are inherently impossible often causes problems (ActionLockObject, ActionUnlockObject, ActionEquipItem, ActionPickUpItem... these are examples of things you should never tell a placeable object to do).

Placeable Object Event Listing

Event: OnClose, trigger: the placeable has been close (not that only placeables that can be opened or closed will fire this... like a chest or armoire), what triggered it? use GetLastClosedBy() to return the object that closed the placeable.

Example: here is an OnClose script that checks to see if its inventory is empty after it's closed... and, if so, creates 100 gold inside.

NWScript:
void main() { // get the first item in inventory object oInside = GetFirstItemInInventory(); // and if there isn't one if (!GetIsObjectValid(oInside)) { // create the gold piece item with a stack of 100 CreateItemOnObject("NW_IT_GOLD001", OBJECT_SELF, 100); } }

Event: OnDamaged, trigger: the placeable object has taken damage, what triggered it? Use GetLastDamager() to return the object that damaged the placeable. Also used here: GetTotalDamageDealt(), GetDamageDealtByType (int nDamageType), GetCurrentHitPoints(), GetMaxHitPoints().

Event: OnDeath, trigger: the object has been destroyed (playing its 'destruction' animation is automatic), what triggered it? GetLastKiller() will return the object that destroyed the placeable.

Event: OnHeartbeat, trigger: there is no trigger for the heartbeat... any script in this location fires automatically once every six seconds. Be careful not to put scripts in this area that will run constantly, as the overhead can be high.

Event: OnDisturbed, trigger: an item has either been added to or removed from the placeable's inventory, what triggered it? Use GetInventoryDisturbType(). This results in one of these constants: INVENTORY_DISTURB_TYPE_ADDED, INVENTORY_DISTURB_TYPE_REMOVED, or INVENTORY_DISTURB_TYPE_STOLEN. Also used here: GetLastDisturbed() returns the object that removed/added the item, GetInventoryDisturbItem() returns the item that was added/removed.

example: here's an OnDisturbed script that sends a UserDefinedEvent #500 signal to a wizard (with the tag "WIZARD1") if anyone removes a particular potion (with the tag "PRECIOUS_POTION") from the placeable.

NWScript:
void main() { object oWizard = GetObjectByTag("WIZARD1"); object oPC = GetLastDisturbed(); object oPotion = GetObjectByTag("PRECIOUS_POTION"); // if the removing object is valid and the potion is removed if (GetIsObjectValid(oPC) && (GetInventoryDisturbType() == INVENTORY_DISTURB_TYPE_REMOVED) && (GetInventoryDisturbItem() == oPotion)) { // send the signal to the wizard SignalEvent(oWizard, EventUserDefined(500)); } }

Event: OnLock, trigger: the placeable has been locked (or relocked), what triggered it? Use GetLastLocked() to return the object that locked the placeable. Also Used Here: GetLockLockDC() returns the DC for locking the placeable. **NOTE** I've had a few reports that this event may not be working.

Event: OnPhysicalAttacked, trigger: the placeable has been physically attacked (but not necessarily damaged), what triggered it? Use GetLastAttacker().

Event: OnOpen, trigger: the placeable object has been opened (for those placeable objects that can be opened and have their 'Has Inventory' box checked), what triggered it? Use GetLastOpenedBy().

Event: OnSpellCastAt, trigger: a spell has been cast at the placeable, what triggered it? Use GetLastSpellCaster(). Also used here: GetLastSpell() will return the constant of the spell used (SPELL_*), GetLastSpellHarmful() will return TRUE or FALSE depending on whether or not the last spell cast was marked hostile.

Event: OnUnlock, trigger: the placeable has been unlocked, what triggered it? Use GetLastUnlocked() to return the object that unlocked the placeable. **NOTE** I've had a few reports that this event may not be working.

Event: OnUsed, trigger: if a placeable object has its 'Useable' box checked, then clicking on the object sets off this event, what triggered it? Use GetLastUsedBy().

example: a script for a placeable object that heals whoever used it.

NWScript:
void main() { object oUser = GetLastUsedBy(); effect eHeal = EffectHeal(GetMaxHitPoints(oUser)); effect eVis = EffectVisualEffect(VFX_IMP_PULSE_HOLY); // if the using object is valid if (GetIsObjectValid(oUser)) { // apply the visual effect ApplyEffectToObject(DURATION_TYPE_INSTANT, eVis, oUser); // and, 1 second later, heal the user DelayCommand(1.0, ApplyEffectToObject(DURATION_TYPE_INSTANT, eHeal, oUser)); } }

Event: OnUserDefined, trigger: this event will only occur if someone specifically uses SignalEvent to send a UserDefinedEvent to the placeable object.