EVENT scripts: Difference between revisions

2,586 bytes added ,  29 September 2021
Added the new event types in 3.1-alpha and a section that covers more information about GAMEEVENT_ACTOR_SPAWNED and GAMEEVENT_ACTOR_DAMAGED.
m (Replaced "3.1 only" with "Zandronum 3.1 only".)
(Added the new event types in 3.1-alpha and a section that covers more information about GAMEEVENT_ACTOR_SPAWNED and GAMEEVENT_ACTOR_DAMAGED.)
Line 22: Line 22:
;GAMEEVENT_ROUND_ABORTED 7
;GAMEEVENT_ROUND_ABORTED 7
:If the round is aborted (e.g. in duel where one of the combatants leaves the game).
:If the round is aborted (e.g. in duel where one of the combatants leaves the game).
;GAMEEVENT_CHAT 8 (<font color="darkblue">Zandronum 3.1</font> <font color="red">only</font>)
;GAMEEVENT_CHAT 8 {{Devfeature|3.1|alpha}}
:When a chat message is sent. The activator is always the world, <tt>arg1</tt> is the number of the player who sent the message (if the server sent the message, -1 is passed instead), and <tt>arg2</tt> is set to 0 if it was a global chat message or 1 if it was a team chat message.
:When a chat message is sent. The activator is always the world, <tt>arg1</tt> is the number of the player who sent the message (if the server sent the message, -1 is passed instead), and <tt>arg2</tt> is set to 0 if it was a global chat message or 1 if it was a team chat message.
;GAMEEVENT_PLAYERCONNECT 9 {{Devfeature|3.1|alpha}}
:A client or bot connects to the server. The activator is the world, <tt>arg1</tt> is the number of the player, and <tt>arg2</tt> is set to 1 if the client had previously joined the server or 0 if not.
;GAMEEVENT_ACTOR_SPAWNED 10 {{Devfeature|3.1|alpha}}
:When an non-player actor is spawned. Strictly speaking, this occurs just before the actor's first tic. The activator is the actor that spawned.
;GAMEEVENT_ACTOR_DAMAGED 11 {{Devfeature|3.1|alpha}}
:When an actor is just about to take damage, after all damage modifications are applied. The activator is the actor taking damage, <tt>arg1</tt> is the amount of damage received, and <tt>arg2</tt> is a dynamic ACS string containing the damage type.


== Additional information ==
Due to risks of performance drops because of how often they might be called, '''GAMEEVENT_ACTOR_SPAWNED''' and '''GAMEEVENT_ACTOR_DAMAGED''' are disabled by default. There are two methods for enabling these event types:
* '''Method A''': Add the properties <tt>ForceSpawnEventScripts</tt> or <tt>ForceDamageEventScripts</tt> in the [https://zdoom.org/wiki/GameInfo_definition GameInfo Definition]. This helps if you want all actors to execute these events. Note that using this method in the case of '''GAMEEVENT_ACTOR_SPAWNED''', actors with the <tt>NOBLOCKMAP</tt> or <tt>NOSECTOR</tt> flags still won't execute the event. This way, only the non-trivial actors are accounted for.
* '''Method B''': Add the <tt>USESPAWNEVENTSCRIPT</tt> or <tt>USEDAMAGEEVENTSCRIPT</tt> flags to the actor that you wish have execute the events. These are useful if you only want certain actors to trigger the events and not all of them, which can optimize your mod better.
If you wish to forbid an actor from triggering these events, you can add the <tt>NOSPAWNEVENTSCRIPT</tt> or <tt>NODAMAGEEVENTSCRIPT</tt> flags to them.
In addition, '''GAMEEVENT_ACTOR_DAMAGED''' enables special actor pointers that give you access to the actors involved in the <tt>P_DamageMobj</tt> call:
*AAPTR_DAMAGE_SOURCE: Accesses the "shooter" responsible for making the attack.
*AAPTR_DAMAGE_INFLICTOR: Accesses the actor directly responsible for causing damage (e.g. a barrel or projectile).
*AAPTR_DAMAGE_TARGET: Accesses the "victim" taking the damage. By default, this actor is already the activator of the script.
You may use these in ACS functions that deal with actor pointers, such as [https://zdoom.org/wiki/IsPointerEqual IsPointerEqual], [https://zdoom.org/wiki/SetActivator SetActivator], [https://zdoom.org/wiki/SetPointer SetPointer], or [https://zdoom.org/wiki/Warp Warp].
[[Category:Level Development]]
[[Category:Level Development]]
[[Category:ACS Functions]]
[[Category:ACS Functions]]