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
orrefuse
}
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 Template:Text using ^$param1
, ^$param2
and ^$param3
, as Template:Real using ^¶m1
, ^¶m2
and ^¶m3
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.