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. Synchronous events have their script code executed immediately when the event is generated and the engine waits for the event to be fully executed before continuing. Asynchronous events however are queued only up to 20 are executed each frame. All queued asynchronous events are executed when saving.

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.

Blocked events

Mega-hidden entities can only receive the reload event and dead NPCs can only receive the die, dead, executeline, reload, inventory2_open and inventory2_close events. Additionally, certain events can be disabled for an entity using the setevent script command.

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

From: [1]

Event	Trigger
on init
on inventoryin
on inventoryuse
on equipin
on equipout
on chat
on action
on reachedtarget
on die
on losttarget
on treatout
on detectplayer
on undetectplayer
on combine
on custom
on initend
on clicked
on leavezone
on controlledzone_leave
on enterzone
on controlledzone_enter
on load
on reload
on hear
on summoned
on strike
on waypoint
on pathend
on critical
on collide_npc
on backstab
on aggression
on key_pressed
on pathfinder_failure
on pathfinder_success
on book_open
on book_close
on identify
on break
on cursormode
on explorationmode

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

[1]: https://github.com/arx/ArxLibertatis/blob/master/src/script/ScriptEvent.cpp