Events

Table of Contents

• Introduction
• Logic Nodes
  • Sending events
  • Listening to events
• Haxe API
• Event masks

Introduction

Armory is equipped with an event system that makes it possible to send notifications (called events) from one part of the application to another.

Each event has a name used to identify it (you can choose every name you want), and other parts of the application can listen to events with a certain name and then react accordingly to them. For example, in a racing game, every time the player's car enters the next lap, the trait responsible for counting the laps could be configured to send an event called next_lap to the trait controlling the user interface (UI), which then updates the lap displayed on the screen. In order to do that, the UI trait needs to be configured to listen to events with the name next_lap.

*Image below for illustration purposes (non event nodes exits for learning purposes only and cannot be found in Armory 3D).

Terminology used in this article

In this article, the part of the application that is responsible for sending an event is called sender, and those parts that react to a certain event are called listeners of that event.

Events are global by default, which means that every listener can listen to all events with a given name. However, by using event masks, events can be restricted to specific listeners.

Event listeners get immediately notified about an event by the sender, so events are received within the same frame they are sent.

Logic nodes

Sending events

There are two logic nodes that can be used to send events:

• Send Event to Object node: send an event only to listeners that belong to a specific object. The mask of the event is set to the UID (unique ID) of the receiving object.
• Send Global Event node: sends a global event (to all listeners listening to the event's name).

Listening to events

The On Event node receives any global event and every event sent specifically to the object that owns the logic tree's trait instance (i.e. any event whose mask is set to the UID of the trait's owner object).

Haxe API

For detailed documentation on the event system's Haxe API, please refer to the API documentation on armory.system.Event.

Event masks

Masks are signed integral numbers that can be used to restrict which listeners are notified about a certain event. Both events and event listeners can be configured with a mask value, each listener is only notified about global events and events whose mask value exactly matches the listener's mask value. Events with the mask value -1 represent a global event, listeners with a mask value of -1 can only listen to global events.

Examples:

• An event with the mask value 42 and the name abc will notify all listeners listening to abc events and a configured mask value of 42. Listeners with other mask values that are listening to abc events are not notified.
• An event with the mask value -1 and the name xyz will notify all listeners listening to xyz events independent of their configured mask value.