Activation

From ZDoom Wiki
Jump to navigation Jump to search

Activation and deactivation are actions that can happen to any actor. These allow to provide a higher degree of interactivity with things on the map.

There are many different aspects that to activation/deactivation. Depending on how and where it's done, activation/deactivation can be used to execute a special attached to the actor, set/unset the DORMANT flag on it, or simply set its state to the Activate or Deactivate state sequences.

ACS

If Thing_Activate or Thing_Deactivate are called in ACS, each actor with the specified TID will be activated/deactivated. In ACS terms this implies the following:

  • The actor's Activate()/Deactivate() ZScript virtual functions will be called. They will always be called this way, regardless of how the activation property is set up. By default, these functions don't do anything and can be overridden to add custom behavior.
  • If the actor is a monster who is alive (health is above 0) or an ice corpse, the DORMANT flag will be set/unset on it.
  • If the actor's Activation field was set to THINGSPEC_Switch, then upon activation THINGSPECI_Deactivate will be added, and upon deactivation, THINGSPECI_Activate will be added to the field. This is done so that the opposite action can be performed.

Nothing else is implied by these functions by default. For example, if Thing_Activate/Thing_Deactivate is called on a non-monster actor that doesn't have any special behavior added to its Activate()/Deactivate() virtuals, nothing will happen at all.

ZScript

Activate() and Deactivate() are Actor virtual functions that can be both called directly to "activate"/"deactivate" an actor, or be overridden on an actor to determine what it does when activated. By default, these functions don't do anything. Some actors, like SwitchableDecoration, override these functions to do something, and they can be freely used in custom actors. However, if there's a need to create an interactive decoration, it's recommend to use the Used virtual instead, which is much easier to set up.

These functions can be called by the following means:

An actor actor can also call its Activate()/Deactivate() functions with the help of the USESPECIAL flag (player can activate it by pressing Use next to it) or the BUMPSPECIAL flag (player can activate it by bumping into it), as long as the following conditions are also met:

  • The actor's Activation property must contain one of the following: THINGSPEC_Activate (can activate once), or THINGSPEC_Deactivate (can deactivate once), or THINGSPEC_Switch (will activate/deactivate interchangeably any number of times);
  • The actor must also have the SOLID flag set, because pressing Use and bumping into the actor is based on collision, which is disabled without this flag.

Actor specials

The execution of the actor's special is tangenially related to the concept of activation/deactivation, but is not directly implied by it. Calling Thing_Activate/Thing_Deactivate in ACS or Activate()/Deactivate() in ZScript does not execute the actor's special.

There are only three possible cases when the actor's special is executed:

  • When the actor is killed. This is the default behavior.
  • When the actor has USESPECIAL and SOLID, and the player presses Use next to it.
  • When the actor has BUMPSPECIAL and SOLID, and the player bumps into it.

If the actor's special is executed, then we can observe some overlap between that and the the concept of activation/deactivation: the flags defined in the actor's Activation property come into play.

Activation property

The Activation property governs the conditions for activation/deactivation. The values of that property govern two mostly unrelated aspects:

  • First of all, they govern how the actor's special is executed. (As described earlier, there are only 3 possible cases when that happens.)
  • Three of those flags (specifically, THINGSPEC_Activate, THINGSPEC_Deactivate and THINGSPEC_Switch) allow the actor to call its Activate()/Deactivate() in addition to executing its special.

The values of this field don't interact with the ACS functions at all. The ACS functions can still set or unset the DORMANT flag on the actor (if it's a living monster) and forcefully call Activate()/Deactivate() but do nothing else by default.

The following flags are available (multiple flags can be combined with | between them):

  • THINGSPEC_Default — default behavior. This allows the actor to execute its special by being killed, used (with the USESPECIAL flag) or bumped (with the BUMPSPECIAL flag). The trigger (bumper/user/killer) is considered the activator, and only players can trigger this actor.
  • THINGSPEC_ThingActs — the actor itself is considered the activator.
  • THINGSPEC_TriggerActs — the trigger is considered the activator. This is the default behavior except for specials activated upon the thing's death in maps with the ActivateOwnDeathSpecials level flag. This flag overrides the MAPINFO flag.
  • THINGSPEC_ThingTargets — the actor changes its target field to the activator when triggered.
  • THINGSPEC_TriggerTargets — the activator changes its target field to this actor when it triggers it.
  • THINGSPEC_MonsterTrigger — monsters are allowed to trigger this actor.
  • THINGSPEC_MissileTrigger — missiles are allowed to trigger this actor.
  • THINGSPEC_ClearSpecial — the actor's special is cleared after execution.
  • THINGSPEC_NoDeathSpecial — the actor's special will not execute on death. (This means that it can only be executed by the player provided the actor has USESPECIAL or BUMPSPECIAL.)
  • THINGSPEC_Activate — same as THINGSPEC_Default but in addition to that, if the actor is triggered by the player via USESPECIAL or BUMPSPECIAL, the actor will call its Activate ZScript virtual (only once).
  • THINGSPEC_Deactivate — same as THINGSPEC_Default but in addition to that, if the actor is triggered by the player via USESPECIAL or BUMPSPECIAL, the actor will call its Deactivate ZScript virtual (only once).
  • THINGSPEC_Switch — same as THINGSPEC_Default but in addition to that, if the actor is triggered by the player via USESPECIAL or BUMPSPECIAL, the actor will alternate between calling its Activate and Deactivate virtuals when triggered. By default, it will call Activate the first time it's triggered, but if this is used in conjunction with THINGSPEC_Deactivate, it will call Deactivate first instead.
Note, for the USESPECIAL/BUMPSPECIAL flags to be effective, the actor also needs the SOLID flag.

See also