Activate

Syntax:

ObjectToActivateRef:rec.Activate [ActivatorID:rec] [RunOnActivateBlock:bin] 

(note on syntax: Italics = object that's acted on, Bold = function name, [Brackets] = optional field, "rec" = record, "bin" = binary. See discussion for more info)

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. Calling Activate 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.
5. 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 Activate Self for more info.
6. Activating a Container (including NPCs)

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.