Physics-Based Events

Certain physics-based events are emitted during simulation. They can be listened to client-side in the JS code of your application, or server-side in a script.

The events that are emitted belong to a 3dverse event map called physics.events. This event map will come up in the ‘How to listen to the events’ section.

Trigger Events

The trigger events that can be listened to are the enter_trigger event and the exit_trigger event. The enter_trigger event is sent when a trigger body enters another body (or vice versa). The exit_trigger event is sent when a trigger body exits another body (or vice versa).

These two events are emitted on the entity that is the trigger physics body, and in the data of the event is contained the other entity that entered/exited the trigger. More info on this below.

Collision Events

The collision events that can be listened to are the collision_enter event and the collision_exit event. The collision_enter event is sent whenever a non-trigger physics body begins to overlap with another non-trigger physics body. Coincidingly the collision_exit event is sent whenever a non-trigger physics body stops overlapping with another non-trigger physics body.

These two events are emitted on both entities involved in the collision. The data of the event contains the other entity that was involved in the collision. More info on this below.

Listening to Events

These physics events are no different to other events in 3dverse. They belong to an event map and can be listened to within a script or within JS code with registerToEvent.

The event map they belong to is a default asset accessible in read-only by all users called physics.events, which has UUID:

7a8cc05e-8659-4b23-99d1-1352d13e2020

Script

Open a script in the script editor. Add an event node by right clicking in the Graph and typing the name of the event map, in this case, ‘physics.events’. Toggle ‘Listen event’ and choose the specific physics event you want to listen to. This node will then execute each time the event is emitted.

Note that in the case of trigger events, the event is emitted on the trigger entity, so make sure to attach a script listening to enter_trigger/exit_trigger on the trigger entity in question. In the case of the collision events, the event is emitted on both entities involved in the collision, so your script must be attached to one of those entities.

To get the other entity involved in the collision, you can either click on the link button on the event node to get access to the event data like so:

Or, within a custom code node you can retrieve the event data like so:

Livelink.JS SDK

Listen to events with registerToEvent. There are also two helper functions, onEnterTrigger and onExitTrigger, for the trigger events which call registerToEvent for you behind the scenes.

Collision events

const eventMapUUID = '7a8cc05e-8659-4b23-99d1-1352d13e2020';
const eventName = 'collision_enter';
SDK3DVerse.engineAPI.registerToEvent(eventMapUUID, eventName, async (event) => {
	// entities contains the entities the event was emitted upon, which in this
	// case contains one of the entities that collided.
	// dataObject contains data associated with the event. In this case dataObject.entity
	// is the other entity involved in the collision.
	const { entities, dataObject } = event;
	const entity1 = entities[0];
	const entity2 = await SDK3DVerse.engineAPI.editorAPI.resolveEntityRef(dataObject.entity);
	console.log(entity1, 'entered into collision with', entity2);
});

Trigger events

SDK3DVerse.engineAPI.onEnterTrigger((entity, triggerEntity) =>
{
    console.log(entity, " entered trigger of ", triggerEntity);
});

SDK3DVerse.engineAPI.onExitTrigger((entity, triggerEntity) =>
{
    console.log(entity, " exited trigger of ", triggerEntity);
});