EVENT scripts: Difference between revisions
Added the GAMEEVENT_LEVEL_INIT event.
DrinkyBird (talk | contribs) (New arg for spawned event) Tag: Source edit |
(Added the GAMEEVENT_LEVEL_INIT event.) |
||
| (8 intermediate revisions by 3 users not shown) | |||
| Line 28: | Line 28: | ||
;GAMEEVENT_ACTOR_SPAWNED 10 | ;GAMEEVENT_ACTOR_SPAWNED 10 | ||
: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. | :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. | ||
:{{Devfeature|3.2|alpha}}: <tt>arg1</tt> is a boolean which is true the actor was spawned by the level. | :{{Devfeature|3.2|alpha}}: <tt>arg1</tt> is a boolean which is true if the actor was spawned by the level. | ||
;GAMEEVENT_ACTOR_DAMAGED 11 | ;GAMEEVENT_ACTOR_DAMAGED 11 | ||
: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. | :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. | ||
;GAMEEVENT_ACTOR_ARMORDAMAGED 12 | ;GAMEEVENT_ACTOR_ARMORDAMAGED 12 | ||
:Behaves exactly like GAMEEVENT_ACTOR_DAMAGED but is triggered slightly earlier, just before an actor's armor can absorb any damage. | :Behaves exactly like GAMEEVENT_ACTOR_DAMAGED but is triggered slightly earlier, just before an actor's armor can absorb any damage. | ||
;{{Devfeature|3.2|alpha}} GAMEEVENT_DOMINATION_CONTROL 13 | |||
: When a player takes control of a point sector in [[Game Modes#Domination|Domination]]. The activator is the player who took control of the point sector, <tt>arg1</tt> is the team index that previously owned the sector (this is always 255 if no team occupied it before), and <tt>arg2</tt> is a dynamic ACS string containing the name of the sector that was captured. | |||
;{{Devfeature|3.2|alpha}} GAMEEVENT_DOMINATION_POINT 14 | |||
:When a team gets a point for controlling point sector in [[Game Modes#Domination|Domination]]. The activator is always the world, <tt>arg1</tt> is the team index that occupies the sector, and <tt>arg2</tt> is a dynamic ACS string containing the name of the sector. | |||
;{{Devfeature|3.2|alpha}} GAMEEVENT_PLAYERLEAVESSERVER 15 | |||
:When a player disconnects from the server (the opposite of GAMEEVENT_PLAYERCONNECT). This is not to be confused with {{Zdoomwiki|Script types#DISCONNECT|DISCONNECT scripts}} which fire when a player leaves the game, including becoming a spectator. The activator is the world, <tt>arg1</tt> is the number of the player who disconnected, and <tt>arg2</tt> indicates the reason the player disconnected - see [[#Leave reasons|Leave reasons]] below. | |||
;{{Devfeature|3.2|alpha}} GAMEEVENT_LEVEL_INIT 16 | |||
:This event is executed early in map initialization, before things are spawned, OPEN scripts executed, etc. This script is usable as a way to manipulate map features early where the regular OPEN script doesn't work. This is not to be confused with said {{Zdoomwiki|Script types#OPEN|OPEN scripts}} which fire when a level initialized, happening much later down the line. The activator is the world. | |||
== Event handling == | == Event handling== | ||
You are allowed to modify the results of some events by changing the result value of the EVENT script itself via | You are allowed to modify the results of some events by changing the result value of the EVENT script itself via {{zdoomwiki|SetResultValue}}. The event types that current support this are: | ||
* '''GAMEEVENT_CHAT''': setting the result value to zero prevents the chat message from being printed onto the screen. If the result value is non-zero, the chat message will be printed like normal. | *'''GAMEEVENT_CHAT''': setting the result value to zero prevents the chat message from being printed onto the screen. If the result value is non-zero, the chat message will be printed like normal. | ||
* '''GAMEEVENT_ACTOR_DAMAGED''' and '''GAMEEVENT_ACTOR_ARMORDAMAGED''': changing the result value affects how much damage the actor actually takes. | *'''GAMEEVENT_ACTOR_DAMAGED''' and '''GAMEEVENT_ACTOR_ARMORDAMAGED''': changing the result value affects how much damage the actor actually takes. | ||
*{{Devfeature|3.2|alpha}} '''GAMEEVENT_MEDALS''': setting the result value to zero prevents the player from receiving the medal that was earned. | |||
*{{Devfeature|3.2|alpha}} '''GAMEEVENT_DOMINATION_POINT''': the result value determines how many points a team gets from the point sector. Anything above and including zero is acceptable. | |||
A few things to note are: | A few things to note are: | ||
* If there are multiple EVENT scripts, the result of the event will be transferred from one script to the next. If more than one script tries to change the result of the event, then whichever script is fired last decides the outcome of the event. | *If there are multiple EVENT scripts, the result of the event will be transferred from one script to the next. If more than one script tries to change the result of the event, then whichever script is fired last decides the outcome of the event. | ||
* Event handling does not work at all in <tt>CLIENTSIDE</tt> scripts. | * Event handling does not work at all in <tt>CLIENTSIDE</tt> scripts. | ||
It's recommended that you change the result value in only one script per event type, unless you know the order in which the scripts are fired (e.g. creating an addon of a mod that overrides the result of the event). | It's recommended that you change the result value in only one script per event type, unless you know the order in which the scripts are fired (e.g. creating an addon of a mod that overrides the result of the event). | ||
== Additional information == | {{Devfeature|3.2|alpha}}: It's possible to get the current result value with [[GetEventResult]]. | ||
==Additional information== | |||
Due to risks of performance drops, '''GAMEEVENT_ACTOR_SPAWNED''', '''GAMEEVENT_ACTOR_DAMAGED''', and '''GAMEEVENT_ACTOR_ARMORDAMAGED''' are disabled by default. There are two methods for enabling these event types: | Due to risks of performance drops, '''GAMEEVENT_ACTOR_SPAWNED''', '''GAMEEVENT_ACTOR_DAMAGED''', and '''GAMEEVENT_ACTOR_ARMORDAMAGED''' 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 [ | *'''Method A''': Add the properties <tt>ForceSpawnEventScripts</tt> or <tt>ForceDamageEventScripts</tt> in the [[zdoom: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> (actors with <tt>ISMISSILE</tt> will still execute the event) 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. | *'''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. | 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. | ||
| Line 58: | Line 70: | ||
*AAPTR_DAMAGE_INFLICTOR: Accesses the actor directly responsible for causing damage (e.g. a barrel or projectile). | *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. | *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 [ | You may use these in ACS functions that deal with actor pointers, such as [[zdoom:IsPointerEqual|IsPointerEqual]], [[zdoom:SetActivator|SetActivator]], [[zdoom:SetPointer|SetPointer]], or [[zdoom:Warp|Warp]]. | ||
| Line 64: | Line 76: | ||
[[Category:Level Development]] | [[Category:Level Development]] | ||
== Examples == | === Leave reasons === | ||
The second argument passed to '''GAMEEVENT_PLAYERLEAVESSERVER''' indicates the reason a player disconnected from the server: | |||
;LEAVEREASON_LEFT 0 | |||
:The player disconnected from the server of their own accord. | |||
;LEAVEREASON_KICKED 1 | |||
:The player was kicked from the server by an admin. | |||
;LEAVEREASON_ERROR 2 | |||
:The client was disconnected due to an error. | |||
;LEAVEREASON_TIMEOUT 3 | |||
:The player timed out. | |||
;LEAVEREASON_RECONNECT 4 | |||
:The player is re-connecting; e.g. the <tt>map</tt> command was used. | |||
==Examples == | |||
Let's say we want to use '''GAMEEVENT_ACTOR_SPAWNED''' and '''GAMEEVENT_ACTOR_DAMAGED''' for our mod. For the sake of simplicity, we want the events to be triggered by all actors, so we'll create a <tt>MAPINFO</tt> lump in our WAD file and add the following: | Let's say we want to use '''GAMEEVENT_ACTOR_SPAWNED''' and '''GAMEEVENT_ACTOR_DAMAGED''' for our mod. For the sake of simplicity, we want the events to be triggered by all actors, so we'll create a <tt>MAPINFO</tt> lump in our WAD file and add the following: | ||