Editing Activate

__NOTOC__
'''Syntax:'''
 ''ObjectToActivateRef:rec''.'''Activate''' [ActivatorID:rec] [RunOnActivateBlock:bin] 
(note on syntax: ''Italics'' = object that's acted on, '''Bold''' = function name, <nowiki>[Brackets]</nowiki> = optional field, "rec" = record, "bin" = binary. See discussion for more info)

'''Example:'''
 Activate player 
 ContainerRef.Activate 
 ActivatorRef.Activate player, 1 

If the RunOnActivateBlock is set to zero (default) this function makes the object only perform its default activation, bypassing any OnActivate Block in its script.

The default activations for the player are:
{|border="1" cellpadding="5" cellspacing="0" align="center"
|-
! style="background:#efefef;" | Object Type 
! style="background:#efefef;" | Activation    
|-
|NPC            
|Dialogue    
|-
|Container         
|Opens    
|-
|Door
|Opens    
|-
|Weapon, armor, etc   
|Picks Up    
|-
|Book/Scroll         
|Reads    
|}

For [[Enable]]d NPCs, activating an item will force them to pick it up (even if they're [[SetUnconscious|unconscious]]). However, containers won't pick up the item.

If the ''RunOnActivateFlag'' is set to 1, then the [[OnActivate]] block of the object (if any) will be run ''instead'' of the default activation. (In other words, act just as if ''ActivatorID'' activated it directly -- NPC used it, Player moused over and clicked on it, etc.)


If the ''ObjectToActivateRef'' flag isn't set then the object will activate itself (as with most functions). There are a couple of tricks you can pull with this:
#You can use '''''Activate''''' inside of an object's [[OnActivate]] block to make it ''also'' perform it's default activation
#You can use '''''Activate player, 1''''' inside of an object's onActivate block to make it run it's [[OnActivate]] block again (see [[Activate#Nesting|Nesting]] below)
#You can use '''''Activate player, 1''''' to make an item activate itself ''while inside an inventory''. By having the item continuously check a persistent variable, you can make external scripts "activate" the item by controlling the persistent variable.


The ''ActivatorID'' flag determines the ActionRef for that activation, as if the ActionRef had activated the object. This is useful if you use [[IsActionRef]] or [[GetActionRef]] inside of the [[OnActivate]] block of the object. If the ''ActivatorID'' flag is omitted, the calling reference's ActionRef will be used instead.

'''That means that this:'''
 Activate

'''Is equivalent to this:'''
 ref actingref
 set actingref to GetActionRef
 Activate actingref

If the calling reference doesn't have an ActionRef (for example, if the calling reference is a quest) then the object won't be activated and the line will be ignored (the calling reference's script will continue).


==Buggy Bug Bug of a Weird, Weird Bug==
There are a number of peculiarities (both good and bad) and bugs with the '''Activate''' function:
#When you use the ''RunOnActivate'' flag, the script of the activated object/item will run immediately, meaning the next line of the activator's script won't be processed until the entire activated script (including blocks other than [[onActivate]]) finishes. If the activated script doesn't have an [[onActivate]] block, it won't run.
#You have to use an ''ActivatorID'' when using the ''RunOnActivateBlock'' flag.
#Calling '''''Activate''''' with the RunOnActivateBlock set to 0 on an object which doesn't have an '''''onActivate''''' block in its script, or has no script at all, will prevent that object from being activated normally ever again. For example, if Activate is called on an unscripted container, the player will no longer be able to open that container by activating it with the spacebar; similarly, calling Activate on unscripted NPCs prevents the player from being able to talk to them. Therefore, use RunOnActivateBlock = 0 only if you know for sure the object has an OnActivate block and, for some reason, you don't want that code to run.  
#You can use 'Activate player, 1', while an item is in an inventory, to have it run it's own [[onActivate]] block. However, you have to place the onActivate block on the top of the script. See [[Crashes#Activate_Self|Activate Self]] for more info.
#[[Crashes#Activating_a_Container_.28including_NPC.29|Activating a Container (including NPCs)]]
#If you add a MessageBox to the OnActivate block of a container and then issue the Activate command somewhere after the call to the MessageBox, the in-game result will be an opened inventory dialog box of the container with a MessageBox behind it without the ability to select any items in the inventory screen or be able to exit the inventory screen or be able to see the message in order to click the OK button...basically, you will be stuck.

==Nesting==
You can nest activations within other activations. For instance, a quest script activates an activator
 SomeActivator.Activate player, 1
which in turn activates another activator
<pre>scn SomeActivatorScript

begin onActivate
  SomeOtherActivator.Activate player, 1
end</pre>
You can only nest 5-6 activations at a time. At a time is a little hard to define here, since [[OnActivate]] blocks run instantly and before the next line of code is processed. This really means that if 4 other scripts are still being processed and an activation is made during the 5th script, that last activation will be ignored (the script skips the line). This applies to any activation, even if they're different objects or different scripts.
*Using a result script to activate the next script, the limit is still 5-6.

==See Also==
* [[OnActivate]]
* [[PlayGroup]]
* [[Activate2]]

[[Category: Functions]]
[[Category: Functions (CS)]]
[[Category: Functions (CS 1.0)]]
[[Category: Inventory Functions]]
[[Category: Inventory Functions (CS 1.0)]]