ScriptObject
This is the base class for all scripts that correspond to a kActor.
Script objects get a handle to their associated kActor in their constructor, which is typically stored in a member variable named self.
Initialization
void OnSpawn()
gets called when the actor is spawned, immediately after the script's constructor
void OnBeginLevel()
called during level initialization, after OnSpawn() has been called for all actors
void OnRestore()
gets called if the persistent bit is marked, immediately after OnBeginLevel()
When the player enters a level, all actors placed in the map file will be spawned in their default state, even if they've been killed, picked up, or triggered. An actor's persistent bit – whose value persists between saves/loads and level transitions – can be used as a rudimentary signal to restore the actor to some previous state.
Some native classes use this bit internally. For example, pickups use this bit to flag them as having been picked up, in which case they are removed before OnRestore() has a chance to be called. Other classes can replicate this kind of behavior via script by marking the persistent bit and removing the actor in OnRestore() (e.g., TurokAnimal, in scripts/animal.txt).
The persistent bit doesn't necessarily need to be used for removing an actor. For example, TurokTrap in scripts/traps.txt uses it to track whether a trap has already been triggered. This is how, for example, boulders appear on the ground when returning to a level after they've fallen.
void OnPostBeginLevel()
called during level initialization, after OnBeginLevel() and OnRestore() have been called for all actors
Other Events
void OnTick()
gets called every tick
void OnEndLevel()
called when changing levels, before the current level is unloaded
no script destructors are called until after all OnEndLevel() events have completed
void OnActivate()
called when the actor is triggered (by script, actor, or sector)
AF_ACTIVATED gets set before this gets called
void OnDeactivate()
void OnDamage( kActor@ instigator, kDictMem@ damageDef, const int damage )
void OnDeath( kActor@ instigator, kDictMem@ damageDef )
gets called when taking damage, before the actor's health gets decremented
instigator will be:
- the actor passed by
kActor::InflictGenericDamage() - the source actor for
kActor::MeleeObject() - self (damage) or some non-null value (death; neither self nor player) for particles
damageDef stores damage type properties (null if sourced from kActor::InflictGenericDamage())
if the actor dies, OnDeath() is called before OnDamage()