Category:Event manipulation: Difference between revisions

From EDukeWiki
Jump to navigation Jump to search
No edit summary
m Clarify the information present + formatting
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Events are special occurences in the game engine, including specific key presses, display calls, etc. Events are also the only of the three CON entry points (the other two being [[actor]] and [[eventloadactor]] code) that may recurse, for example through [[EVENT_EGS]], [[EVENT_SPAWN]] or [[EVENT_KILLIT]].
Events are special occurrences in the game engine. They allow modifications to inject custom code outside of actor definitions, which is executed before or after the corresponding game event.


Please see the [[EDuke32 event list]] for a complete list of all currently valid events in EDuke32.
Some events also allows the outcome of the occurrence to be changed. For instance, for [[EVENT_CHANGEMENU]], one can alter the destination of a specific menu transition.
 
Example events include the passing of tic time in the game's 30 Hz state machine, player keypresses, display rendering calls, etc.
 
== Usage ==
 
<span {{code}}>'''onevent''' ''<EVENT_NAME>'' ... '''endevent'''</span>
 
<span {{code}}>'''appendevent''' ''<EVENT_NAME>''  ... '''endevent''' </span>
 
 
Used outside of all [[actor]]s and [[state]]s, '''onevent''' and '''appendevent''' define a special block of CON code to be executed when a specific [[event]] happens in the game code. '''endevent''' is used to end the block.
 
The only difference between '''onevent''' and '''appendevent''' is in how multiple definitions for the same event type are chained together, see [[#event_chaining|Event Chaining]].
 
[[gamevar]] MYMEDPACK 100 1
'''onevent''' [[EVENT_TURNAROUND]]
    [[palfrom]] 32 0 0 32
    [[addphealth]] 5
    [[subvar]] MYMEDPACK 5
    [[setvar]] [[RETURN]] -1
'''endevent'''
 
The hardcoded portion of many events can be modified by altering the special [[gamevar]] [[RETURN]] in a way specific to each event.
 
Events are also the only of the three CON entry points (the other two being [[actor]] and [[eventloadactor]] code) that may recurse, for example through [[EVENT_EGS]], [[EVENT_SPAWN]] or [[EVENT_KILLIT]].
 
Please see the [[EDuke32 event list]] for a complete list of all events available.
 
==Event Chaining==
 
When writing a large modification, it makes sense to split up your code into separate files, using the [[include]] directive.
 
This is useful for keeping your CONs organized, as well as to facilitate [[CON mutator]]s. However, doing so may require you to use the same type of event across multiple files.
 
This is where the difference between '''onevent''' and '''appendevent''' becomes important. When using multiple instances of '''onevent''', each block of code will be prepended to the previously defined block. This means that the code blocks for this type of event will be executed in reverse program order, starting with the last event. For '''appendevent''', the inverse applies, and the code is instead appended to the previously defined block.
 
It is hence recommended to only use '''appendevent''' when defining multiple instances for the same type of event, as this will ensure that the code is executed in the order it was defined inside the scripts, and will reduce the amount of headaches and confusion when bugs occur.
 
====Example====
 
definequote 666 placeholder
appendevent EVENT_ENTERLEVEL
    redefinequote 666 0
    echo 666
endevent
appendevent EVENT_ENTERLEVEL
    redefinequote 666 1
    echo 666
endevent
onevent EVENT_ENTERLEVEL
    redefinequote 666 -1
    echo 666
endevent
appendevent EVENT_ENTERLEVEL
    redefinequote 666 2
    echo 666
endevent
onevent EVENT_ENTERLEVEL
    redefinequote 666 -2
    echo 666
endevent
 
Console output when starting a level:
 
-2
-1
0
1
2
 
Note that the two commands are identical when defining the first instance of an event found when the game parses the CONs.
 
== Terminating Execution ==
 
=== [[break]] ===
 
The [[break]] keyword can be used to terminate the current event block. Any blocks appended after this will still be executed!
 
definequote 666 This will print.
definequote 616 This will never print.
appendevent EVENT_ENTERLEVEL
    echo 666
    break
    echo 616
endevent
appendevent EVENT_ENTERLEVEL
    echo 666
    break
    echo 616
endevent
appendevent EVENT_ENTERLEVEL
    echo 666
    break
    echo 616
endevent
 
This will print.
This will print.
This will print.
 
=== [[return]] ===
 
The [[return]] keyword will abort the entire block chain from executing. Use with caution!
 
definequote 666 This will print.
definequote 616 This will never print.
appendevent EVENT_ENTERLEVEL
    echo 666
endevent
appendevent EVENT_ENTERLEVEL
    echo 666
    return
    echo 616
endevent
appendevent EVENT_ENTERLEVEL
    echo 616
endevent
 
This will print.
This will print.
 
It also aborts the event chain when [[return]] is called from inside a [[state]]. This is not the case for the [[break]] statement.
 
Take special care '''not to''' use the [[return]] statement as you would in another programming language!
 
definequote 666 This will print.
definequote 616 This will never print.
state example_state
    return
ends
appendevent EVENT_ENTERLEVEL
    echo 666
endevent
appendevent EVENT_ENTERLEVEL
    echo 666
    state example_state
    echo 616
endevent
appendevent EVENT_ENTERLEVEL
    echo 616
endevent
 
This will print.
This will print.


[[Category:All commands]]
[[Category:All commands]]

Latest revision as of 02:47, 12 January 2021

Events are special occurrences in the game engine. They allow modifications to inject custom code outside of actor definitions, which is executed before or after the corresponding game event.

Some events also allows the outcome of the occurrence to be changed. For instance, for EVENT_CHANGEMENU, one can alter the destination of a specific menu transition.

Example events include the passing of tic time in the game's 30 Hz state machine, player keypresses, display rendering calls, etc.

Usage

onevent <EVENT_NAME> ... endevent

appendevent <EVENT_NAME> ... endevent


Used outside of all actors and states, onevent and appendevent define a special block of CON code to be executed when a specific event happens in the game code. endevent is used to end the block.

The only difference between onevent and appendevent is in how multiple definitions for the same event type are chained together, see Event Chaining.

gamevar MYMEDPACK 100 1

onevent EVENT_TURNAROUND
    palfrom 32 0 0 32
    addphealth 5
    subvar MYMEDPACK 5
    setvar RETURN -1
endevent

The hardcoded portion of many events can be modified by altering the special gamevar RETURN in a way specific to each event.

Events are also the only of the three CON entry points (the other two being actor and eventloadactor code) that may recurse, for example through EVENT_EGS, EVENT_SPAWN or EVENT_KILLIT.

Please see the EDuke32 event list for a complete list of all events available.

Event Chaining

When writing a large modification, it makes sense to split up your code into separate files, using the include directive.

This is useful for keeping your CONs organized, as well as to facilitate CON mutators. However, doing so may require you to use the same type of event across multiple files.

This is where the difference between onevent and appendevent becomes important. When using multiple instances of onevent, each block of code will be prepended to the previously defined block. This means that the code blocks for this type of event will be executed in reverse program order, starting with the last event. For appendevent, the inverse applies, and the code is instead appended to the previously defined block.

It is hence recommended to only use appendevent when defining multiple instances for the same type of event, as this will ensure that the code is executed in the order it was defined inside the scripts, and will reduce the amount of headaches and confusion when bugs occur.

Example

definequote 666 placeholder

appendevent EVENT_ENTERLEVEL
    redefinequote 666 0
    echo 666
endevent

appendevent EVENT_ENTERLEVEL
    redefinequote 666 1
    echo 666
endevent

onevent EVENT_ENTERLEVEL
    redefinequote 666 -1
    echo 666
endevent

appendevent EVENT_ENTERLEVEL
    redefinequote 666 2
    echo 666
endevent

onevent EVENT_ENTERLEVEL
    redefinequote 666 -2
    echo 666
endevent

Console output when starting a level:

-2
-1
0
1
2

Note that the two commands are identical when defining the first instance of an event found when the game parses the CONs.

Terminating Execution

break

The break keyword can be used to terminate the current event block. Any blocks appended after this will still be executed!

definequote 666 This will print.
definequote 616 This will never print.

appendevent EVENT_ENTERLEVEL
    echo 666
    break
    echo 616
endevent

appendevent EVENT_ENTERLEVEL
    echo 666
    break
    echo 616
endevent

appendevent EVENT_ENTERLEVEL
    echo 666
    break
    echo 616
endevent
This will print.
This will print.
This will print.

return

The return keyword will abort the entire block chain from executing. Use with caution!

definequote 666 This will print.
definequote 616 This will never print.

appendevent EVENT_ENTERLEVEL
    echo 666
endevent

appendevent EVENT_ENTERLEVEL
    echo 666
    return
    echo 616
endevent

appendevent EVENT_ENTERLEVEL
    echo 616
endevent
This will print.
This will print.

It also aborts the event chain when return is called from inside a state. This is not the case for the break statement.

Take special care not to use the return statement as you would in another programming language!

definequote 666 This will print.
definequote 616 This will never print.

state example_state
    return
ends

appendevent EVENT_ENTERLEVEL
    echo 666
endevent

appendevent EVENT_ENTERLEVEL
    echo 666
    state example_state
    echo 616
endevent

appendevent EVENT_ENTERLEVEL
    echo 616
endevent
This will print.
This will print.

Subcategories

This category has only the following subcategory.

E

Pages in category "Event manipulation"

The following 10 pages are in this category, out of 10 total.