Script:Events: Difference between revisions
No edit summary |
No edit summary |
||
Line 1: | Line 1: | ||
Events are entry points of entity scripts. They are sent by the game engine or by other scripts using the {{Command|sendevent}} command. While the engine defines some event names, entity scripts can use arbitrary names for custom events. | Events are entry points of entity scripts. They are sent by the game engine or by other scripts using the {{Command|sendevent}} command. While the engine defines some event names, entity scripts can use arbitrary names for custom events. | ||
= Syntax = | |||
on eventname { | on eventname { | ||
Line 8: | Line 8: | ||
} | } | ||
= Sender = | |||
Events always have a sender associated | Events always have a sender [[entity]] associated with them. The [[entity ID]] of the sender is available in the read-only <code>^sender</code> [[Script:Variables|script variable]]. | ||
= Target = | |||
Scripts can be sent to a single target or multiple targets matching some criteria using the {{Command|sendevent}} command but are always executed independently for each target. | Scripts can be sent to a single target [[entity]] or multiple targets matching some criteria using the {{Command|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 sent by the game engine are usually executed synchronously although there are some exceptions. Events sent by scripts are always executed asynchronously. | ||
Line 24: | Line 24: | ||
For events sent by the game engine, ending the event with {{Command|accept}} or {{Command|refuse}} sometimes also determines some further engine behavior. For events send by entity scripts the result is not returned to the sender. | For events sent by the game engine, ending the event with {{Command|accept}} or {{Command|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|script variables]] as {{text}} using <code>^$param1</code>, <code>^$param2</code> and <code>^$param3</code>, as {{real}} using <code>^¶m1</code>, <code>^¶m2</code> and <code>^¶m3</code> or as {{int}} using <code>^#param1</code>, <code>^#param2</code> and <code>^#param3</code>. | Events can have up to three parameters which can be accessed using the special read-only [[Script:Variables|script variables]] as {{text}} using <code>^$param1</code>, <code>^$param2</code> and <code>^$param3</code>, as {{real}} using <code>^¶m1</code>, <code>^¶m2</code> and <code>^¶m3</code> or as {{int}} using <code>^#param1</code>, <code>^#param2</code> and <code>^#param3</code>. | ||
= List = | |||
The following is a (incomplete) list of events sent by the game engine. Scripts can send arbitrarily named events. | |||
<table class="wikitable sortable"> | |||
<tr> | |||
<th scope="col">Event</th><th scope="col">Trigger</th> | |||
</tr> | |||
{{#arraydefine:events|{{#ask: [[Category:Script events]] | ?=# | mainlabel=- | limit=1000 | format=array}}}} | |||
{{#arrayprint:events||@event| | |||
<tr> | |||
<td><code>[[@event|on {{#replace:{{#replace:@event|Script:on |}}| |_}}]]</code></td><td>Sent when {{#show: @event |?description }}.</td> | |||
</tr> | |||
}} | |||
</table> | |||
[[Category:Scripting]] | [[Category:Scripting]] |
Revision as of 00:27, 15 April 2020
Events 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|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 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. |