Event system

Updated: Oct 16, 2024

Overview

The event system is an integral part of Spatial SDK applications. It is built into the DataModel class and is designed to handle various types of events that can occur within a Spatial SDK app.

Event definition

Spatial SDK applications support various types of events. You can define an event by subclassing the EventArgs class:

open class EventArgs(
    val eventName: String,
    val dataModel: DataModel,
    var handled: Boolean = false,
    var throttleTime: Int? = null
) {}

Here are explanations for the properties:

eventName: the name of the event.

dataModel: the dataModel object of the application.

handled: a boolean to indicate whether the event is handled.

throttleTime: an optional time in milliseconds to throttle the event.

The following defines PhysicsCollisionCallbackEventArgs, subclass of the EventArgs class:

class PhysicsCollisionCallbackEventArgs(
    val collidedEntity: Entity,
    val collisionPosition: Vector3,
    val collisionNormal: Vector3,
    val impulse: Float,
    datamodel: DataModel,
) : EventArgs(eventName = PhysicsCollisionCallbackEventArgs.EVENT_NAME, dataModel = datamodel) {
  companion object {
    val EVENT_NAME = "physicscollision"
  }
}

The name of the event above is physicscollision.

Event registration

Events are tied to entities. To register an event for an entity, invoke its registerEventListener method:

Entity.create(...)
      .registerEventListener()<PhysicsCollisionCallbackEventArgs>(
              PhysicsCollisionCallbackEventArgs.EVENT_NAME) { Entity, eventArgs ->
                eventArgs.throttleTime = 200
              }

This code registers an event listener for the physicscollision event on the specified entity and defines the callback function to execute. When the event occurs, the listener will be notified and can perform the necessary actions.

Sending the event

Once an event is defined and registered, you can send it from anywhere in the app.

The following code sends a physicscollision event. Under the hood, the DataModel will retrieve the corresponding listener in the listener registry to handle the event.

val dm = EntityContext.getDataModel()!!
dm.sendEvent(
    Entity(collider),
    PhysicsCollisionCallbackEventArgs.EVENT_NAME,
    PhysicsCollisionCallbackEventArgs(Entity(collided), collisionPos, normal, impulse, dm),
)

Throttling control

You can throttle an event a certain amount of time after the first event that type is sent.

In this example, the DataModel will remove the listener for physicscollision 200 milliseconds after the first physicscollision event is sent. After that, sending physicscollision will no longer trigger the event callback.

Entity.create(...)
      .registerEventListener()<PhysicsCollisionCallbackEventArgs>(
              PhysicsCollisionCallbackEventArgs.EVENT_NAME) { Entity, eventArgs ->
                eventArgs.throttleTime = 200
              }

Did you find this page helpful?