Types

Synchronous

Requires the current task to complete before the next one starts. The flow of execution is paused until the event finishes, which can cause delays if the event takes a long time.

The event's arguments can be modified before passing them to the original function.

The first return value is a boolean and controls whether other handlers will process the event after the current handler. Returning true (default) allows further handlers to execute, while false ends the event processing immediately.

Further return values are optional and passed to the original function.

If no arguments (except the first) are explicitly returned or no return statement is used, the original arguments remain unchanged.

The execution order of synchronous events is determined by their queuing sequence. Since they halt game execution, they are executed at the earliest available opportunity when no script is actively running, such as between asynchronous events or flag changes. If multiple scripts register the same synchronous event, the order of execution follows the sequence in which the script objects were created.

Although synchronous events execute within the main game thread, they pause all other tasks performed by it. While the game has 16.67 ms per frame at 60 FPS to process everything, including physics and rendering, synchronous events consume part of this time, potentially causing slowdowns if overused. They should generally be avoided unless necessary, such as when updating something while the game is paused, modifying arguments, or ensuring synchronization with the main thread.

Asynchronous

Allows the game process to continue running while the event is processed in the background. It doesn’t block the flow of execution and lets other tasks proceed without waiting for the event to complete.

The execution order begins with asynchronous events (e.g. On Init Done, On Flip), followed by flag callbacks, and concludes with functions invoked by Execute After Ms.

Asynchronous events are processed within a separate thread already created for the script. While they do not introduce the overhead of creating new threads, they execute parallel to the main game thread rather than within it. If an asynchronous event takes longer to complete than the next time it is triggered, especially with the On Flip event, it can pile up in the queue over time. To prevent this, unregistering the event at the beginning of the handler and re-registering it at the end ensures it only triggers once per frame. This is automatically handled for events with the type No Queue.

One Shot

Fires once and will not trigger again during the lifetime of the game process.

Typically used for tasks that should only be executed a single time, such as initialization.

Some events are one-shot by design (e.g. On Init Done), where as others can be executed as one-shot events when needed.