On* events and ACTN record

[Hrnchamd]

Some research from investigating Container UI locks up in Vivec at Jeanne's (Bug #1629).


Activation flags

References may have extra flags attached, serialized as an ACTN subrecord (4 bytes). This is permanent state, kept from frame to frame.

Code: Select all

ActivationFlag_UseEnabled  = 1
ActivationFlag_OnActivate  = 2
ActivationFlag_OnDeath  = 10h
ActivationFlag_OnKnockout  = 20h
ActivationFlag_OnMurder  = 40h
ActivationFlag_DoorOpening  = 100h
ActivationFlag_DoorClosing  = 200h
ActivationFlag_DoorJammedOpening  = 400h
ActivationFlag_DoorJammedClosing  = 800h

ActivationFlag_UseEnabled is the stateful part of the OnActivate mechanic. It defaults to true, but an OnActivate script command will set it to false. While false, it suppresses user activation of an object, instead setting the OnActivate flag to true. The Activate script command will then remove ActivationFlag_OnActivate and set ActivationFlag_UseEnabled to true again.

Note that the ActivationFlag_UseEnabled is saved to the reference, which will result in permanently suppressed activation if the reference script is removed. This occurred when removing the animated containers mod, and the fix in MCP is to reset UseEnabled to true on loading a game.

OnDeath, OnKnockout and OnMurder are set as soon as the respective event occurs. All damage sources including Mod* commands call out to check the actor state.

The door flags indicate animation state as they transition between open and closed, and are mutually exclusive. Doors are flagged as jammed if there is an actor colliding with it. The Lock script command immediately closes a door and resets animation state.

[scrawl]

Thanks, very useful. I'll post the info to relevant places.

[Hrnchamd]

Activate and OnActivate

These script commands are linked. The Activate command will trigger an activation which was suppressed by the OnActivate command. The exact mechanics follow:

OnActivate

- Sets return value to value of reference's ActivationFlag_OnActivate.
- Clears reference's ActivationFlag_UseEnabled and ActivationFlag_OnActivate.

When the UseEnabled flag is cleared, activation from player input is suppressed; instead the activating actor is buffered in an extra ACTN node attached to the reference.


Activate

- Sets reference's ActivationFlag_UseEnabled and ActivationFlag_OnActivate.
- If there is a buffered actor, then activate the object as if the actor used it, otherwise do nothing. This is a consequence of null parameter checks rather than part of the script engine. No actor -> no activation.
- Clears reference's ActivationFlag_OnActivate.


User interaction

Iff a reference's ActivationFlag_UseEnabled is cleared, then using it will cause the activating actor's reference to be buffered. This buffer does not expire at the end of a frame, but is not written to a savegame. Only the most recent activation is buffered.

[Hrnchamd]

This info should be enough to resolve issues with Activate. You may run a test case through the console:

• Select a container, and execute OnActivate.
• Execute Activate. It should be a no-op as no user activation is buffered.
• Close the console and use the container. The container should not open (suppressed action), but the info text will blink.
• Execute Activate. The container should open. Note that Activate seems to work from any distance.