Script:Events

Events in the Arx scripting language are entry points of entity scripts. They are sent by the game engine or by other scripts using the sendevent command. While the engine defines some event names, entity scripts can use arbitrary names for custom events.

Syntax

on eventname {
  ...
  accept or refuse
}

Sender

Events always have a sender entity associated with them. The entity ID of the sender is available in the read-only ^sender script variable.

Target

Scripts can be sent to a single target entity or multiple targets matching some criteria using the sendevent command but are always executed independently for each target.

Execution

Events sent by the game engine are usually executed synchronously although there are some exceptions. Events sent by scripts are always executed asynchronously.

Events are first executed in the entity instance script. Commands are executed after on eventname until a accept or refuse command is reached. refuse ends event execution while accept allows execution to continue after on eventname in the entity class script until a accept or refuse command is reached there. If a script does not have a on eventname block, the event is always accepted.

For events sent by the game engine, ending the event with accept or refuse sometimes also determines some further engine behavior. For events send by entity scripts the result is not returned to the sender.

Parameters

Events can have up to three parameters which can be accessed using the special read-only script variables as string using ^$param1, ^$param2 and ^$param3, as number using ^&param1, ^&param2 and ^&param3 or as int using ^#param1, ^#param2 and ^#param3.

List

The following is a (incomplete) list of events sent by the game engine. Scripts can send arbitrarily named events.

Event	Trigger
on cine_end	Sent when when a cinematic ends.
on collide_door	Sent when on collisions involving an entity in the door group.
on collide_field	Sent when on collisions with a field created with the Create field () spell.
on collision_error	Sent when if there are entities occupying the same space when re-enabling collisions using collision on.
on collision_error_detail	Sent when for every entity occupying the same space when re-enabling collisions using collision on.
on controls_off	Sent when when player input is disabled using the setplayercontrols off command.
on controls_on	Sent when when player input is enabled using the setplayercontrols on command.
on dead	Sent when periodically when dead.
on game_ready	Sent when after starting a new game, changing to a different area or loading a save file.
on hit	Sent when when the the entity is damaged.
on inventory2_close	Sent when when closing non-player inventories.
on inventory2_open	Sent when when opening non-player inventories.
on main	Sent when periodically when not dead.
on ouch	Sent when when the the entity is damaged and did not receive an ouch event in the last 500 milliseconds.
on spellcast	Sent when when a spell is cast.
on spellend	Sent when when a spell ends or is cancelled.
on steal	Sent when when opening or closing a non-player inventory by pickpocketing.

Besides these events, the game engine also uses the internal executeline and null events.