Difference between revisions of "Activate"

From the Oblivion ConstructionSet Wiki
Jump to navigation Jump to search
imported>Haama
(Extra Failed Activation note)
imported>Haama
(Major overhaul)
Line 1: Line 1:
'''Syntax:'''
'''Syntax:'''
  Activate ''ActivatorID (optional)'','' NormalActivationFlag (optional)''  
  ''ObjectToActivateRef''.'''Activate''' [ActivatorID] [RunOnActivateBlock]
'''Example:'''
'''Example:'''
  Activate player  
  Activate player  
  Activate  
  ContainerRef.Activate  
  Activate player, 1  
  ActivatorRef.Activate player, 1  
 
This function tells the object to perform its default activation.
 
If ActivatorID is omitted, the Activate command will use the calling reference's "current activator". This is very useful inside of OnActivate blocks where you want the activation to proceed normally except under certain circumstances.
 
'''That means that this:'''
Activate
 
'''Is equivalent to this:'''
ref actingref
set actingref to GetActionRef
Activate actingref
 
If ActivatorID is included, the calling reference will perform its default activation as if activated by ActivatorID.
 


This function makes the object perform its default activation. The default activations are:
{|border="1" cellpadding="5" cellspacing="0" align="center"
{|border="1" cellpadding="5" cellspacing="0" align="center"
|-
|-
Line 44: Line 28:
|}
|}


If the ''RunOnActivateFlag'' is set to 1, then the [[OnActivate]] block of the object will be run ''instead'' of the default activation.


If NormalActivationFlag is omitted, the calling reference performs its default activation, bypassing any OnActivate script that might be on it. This is often how you want to use Activate, since most times you are calling Activate on the object itself from inside an OnActivate block after performing some check or other action.


If the NormalActivationFlag is 1, the calling reference will not bypass any OnActivate script on it.  This flag basically is an override of default activation as represented in the above chart. Use this with care -- if you call Activate on the object itself from inside an OnActivate block you will trigger an infinite loop.
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.


When used with care, this can be an extremely powerful tool to cause calls to Activate to be used as pseudo function calls between scripted objects and even spells.  The reference passed in can be used as arguments to tell the object being activated what to do.  This use of Activate is not as intended and requires very careful planning and execution.


'''Example 1:'''  
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.


If you call this script on a door, the door will behave as if the player had activated it (i.e. if a load door, the player will be teleported to the door's target location).
'''That means that this:'''
Activate


Activate player
'''Is equivalent to this:'''
 
  ref actingref
 
  set actingref to GetActionRef
'''Example 2:'''
  Activate actingref
 
Whatever triggered the OnActivate block will also Activate, just as if this script wasn't here.
 
begin OnActivate
if MyCrazyCondition == 1
  Activate
else
  ; do something else
endif
end
 
 
'''Example 3:'''  
 
This script will trigger an infinite loop -- once the scripted object is activated the OnActivate block will continue to be run forever.
   
  float infinity
begin OnActivate
  ; you should NEVER do this!!
  set infinity to infinity + .1
  message "Infinity = %.1f", infinity
  activate player 1
  end
 
(I doubt this, see Nesting info below--[[User:Haama|Haama]] 00:32, 13 July 2007 (EDT))


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).


'''Example 4:'''


This is the proper way to use the NormalActivationFlag
==Buggy Bug Bug of a Weird, Weird Bug==
There are a number of peculiarities and bugs with the [[Activate]] function:
begin OnActivate
#(This one is nice!) The activate function occurs immediately, meaning the next line of the calling reference's script won't be processed until the [[OnActivate]] block (and maybe other blocks in the called script --[[User:Haama|Haama]] 18:42, 13 July 2007 (EDT)) finishes.
  ; trigger some other reference when I am activated by the player
#You have to use an ''ActivatorID'' when using the ''RunOnActivateBlock'' flag.
  if IsActionRef player == 1
#You can't directly use an ''ActivatorID'' of an NPC. Instead, you have to set a temporary reference variable to the desired ''ActivatorID'', and use the variable in the ''ActivatorID'''s place. This is useful when using the ''RunOnActivateBlock'' flag. (I'm not sure what will happen for default activation. --[[User:Haama|Haama]] 18:42, 13 July 2007 (EDT))
      MyGate.Activate player 1
#If you open a container with '''''SomeContainer.Activate player''''', and the container doesn't have a script attached to it, then the player will be unable to directly open that container ever again. (I assume this is extended to all types of activation, but I haven't checked. --[[User:Haama|Haama]] 18:42, 13 July 2007 (EDT))
  endif
#[[:Category:Troubleshooting#Activate_Self|Activate Self]]
end
#[[:Category:Troubleshooting#Activating_a_Container|Activating a Container]] (Again, I've only tested this for containers, but I assume it extends to all types of activations. --[[User:Haama|Haama]] 18:42, 13 July 2007 (EDT))




==Nesting==
==Nesting==
You can nest activations within other activations. For example, a quest script activates an activator
You can nest activations within other activations. For instance, a quest script activates an activator
  SomeActivator.Activate player, 1
  SomeActivator.Activate player, 1
which in turn activates another activator
which in turn activates another activator
Line 107: Line 69:
   SomeOtherActivator.Activate player, 1
   SomeOtherActivator.Activate player, 1
end</pre>
end</pre>
Note, however, that you can only nest 5 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.
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.





Revision as of 17:42, 13 July 2007

Syntax:

ObjectToActivateRef.Activate [ActivatorID] [RunOnActivateBlock] 

Example:

Activate player 
ContainerRef.Activate 
ActivatorRef.Activate player, 1 

This function makes the object perform its default activation. The default activations are:

Object Type Activation
NPC Dialogue
Container Opens
Door Opens
Weapon, armor, etc Picks Up
Book/Scroll Reads

If the RunOnActivateFlag is set to 1, then the OnActivate block of the object will be run instead of the default activation.


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:

  1. You can use Activate inside of an object's OnActivate block to make it also perform it's default activation
  2. You can use Activate player, 1 inside of an object's onActivate block to make it run it's OnActivate block again (see Nesting below)
  3. 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 and bugs with the Activate function:

  1. (This one is nice!) The activate function occurs immediately, meaning the next line of the calling reference's script won't be processed until the OnActivate block (and maybe other blocks in the called script --Haama 18:42, 13 July 2007 (EDT)) finishes.
  2. You have to use an ActivatorID when using the RunOnActivateBlock flag.
  3. You can't directly use an ActivatorID of an NPC. Instead, you have to set a temporary reference variable to the desired ActivatorID, and use the variable in the ActivatorID's place. This is useful when using the RunOnActivateBlock flag. (I'm not sure what will happen for default activation. --Haama 18:42, 13 July 2007 (EDT))
  4. If you open a container with SomeContainer.Activate player, and the container doesn't have a script attached to it, then the player will be unable to directly open that container ever again. (I assume this is extended to all types of activation, but I haven't checked. --Haama 18:42, 13 July 2007 (EDT))
  5. Activate Self
  6. Activating a Container (Again, I've only tested this for containers, but I assume it extends to all types of activations. --Haama 18:42, 13 July 2007 (EDT))


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

scn SomeActivatorScript

begin onActivate
  SomeOtherActivator.Activate player, 1
end

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.