Proximity Events

Detect when a player enters or leaves the proximity of an entity.

Proximity interactions let entities react to button events when a player enters is near and roughly facing it, without requiring them to aim their cursor at the entity.

Traditional pointer events use ray-casting: the player must aim their cursor at an entity's collider before they can press a button to trigger the event. Proximity events instead check for entities that are inside a given area around the avatar, regardless of where the player's cursor is aiming at.

The interactive area considered for proximity interactions is a wide triangular slice of a sphere, projecting forward from the player's position. Unlike with pointer events, the direction that the avatar is facing is important, independently of the direction that the camera is facing.

To set more specific custom logic, you might want to deal with the raw data and use the Advanced approach.

For an entity to be interactive, it must have a collider. See obstacles for more details.

Register proximity callbacks

The pointerEventsSystem includes helper functions for proximity events, following the same pattern as pointer event callbacks.

Proximity button presses

Use pointerEventsSystem.onProximityDown to detect button presses while the player is within range. Unlike onPointerDown, this does not require the player to aim their cursor at the entity.

pointerEventsSystem.onProximityDown(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Press E',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player pressed button near entity')
    }
)

Use pointerEventsSystem.onProximityUp to detect when the player releases a button while in range.

pointerEventsSystem.onProximityUp(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Release E',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player released button near entity')
    }
)

📔 Note: Only one onProximityDown and one onProximityUp can be registered per entity. Once added, they keep listening until removed. Do not call these within a system loop, as that would keep rewriting the behavior.

Proximity event types

Two new values have been added to the PointerEventType enum:

• PET_PROXIMITY_ENTER: Triggered when the player walks within the entity's proximity range.

• PET_PROXIMITY_LEAVE: Triggered when the player moves out of the entity's proximity range.

These can be used with a PointerEvents component and the inputSystem for the system-based approach. That approach also supports proximity button presses using the InteractionType.PROXIMITY field.

Priority

When multiple entities are within range and could respond to the same input, only one is activated, the closest one by default. Use the priority field to control which one takes precedence. Entities with a higher number as their priority value respond first.

If the player is both within the range of an entity with a proximity interaction and the player's cursor is pointing at an entity that has a pointer interaction, the entity with the pointer interaction is always given priority. Again, only one entity is activated.

pointerEventsSystem.onProximityDown(
    {
        entity: doorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Open door',
            maxPlayerDistance: 5,
            priority: 2,
        },
    },
    function () {
        console.log('Door activated')
    }
)

pointerEventsSystem.onProximityDown(
    {
        entity: floorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Step here',
            maxPlayerDistance: 5,
            priority: 1,
        },
    },
    function () {
        console.log('Floor activated')
    }
)

In the example above, if both entities are within range, the door entity responds because it has the higher priority.

The priority field can also be set in the properties of a PointerEvents component.

Options

The proximity helper functions accept the same options as their pointer counterparts:

• button: Which button to listen for. See Pointer buttons for supported options.

• maxDistance: Maximum distance from the player's camera to the entity, in meters.

• maxPlayerDistance: Maximum distance from the player's avatar to the entity, in meters. This is the most relevant setting for proximity events.

• hoverText: Text to display in the UI when the player is near the entity.

• showHighlight: If true, shows an edge highlight on the entity when the player is in range. true by default.

• showFeedback: If true, shows hover feedback, hovering around the center of the entity. true by default.

• priority: Resolves conflicts when multiple entities are in proximity. Higher values take precedence. If multiple entities have the same priority value, the closest one is picked.

Remove callbacks

To remove a proximity callback, use the corresponding remove function:

pointerEventsSystem.removeOnProximityDown(myEntity)
pointerEventsSystem.removeOnProximityUp(myEntity)
pointerEventsSystem.removeOnProximityEnter(myEntity)
pointerEventsSystem.removeOnProximityLeave(myEntity)

Once removed, the entity is no longer reactive to that proximity event.

Proximity enter and leave

Use pointerEventsSystem.onProximityEnter to run a callback when the player walks into the entity's proximity range, and pointerEventsSystem.onProximityLeave when they walk out. This can be used to display extra feedback hints to the player, for example a sound or an animation when an item can be interacted with.

pointerEventsSystem.onProximityEnter(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Nearby',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player entered proximity')
    }
)

pointerEventsSystem.onProximityLeave(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Nearby',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player left proximity')
    }
)

Example: proximity door

The following example opens or closes a door when the player presses a button while standing nearby, without needing to aim at the door.

const doorPivot = engine.addEntity()
Transform.create(doorPivot, { position: Vector3.create(3, 0, 4) })

const door = engine.addEntity()
GltfContainer.create(door, { src: 'assets/door.glb' })
Transform.create(door, { position: Vector3.create(-1, 0, 0), parent: doorPivot })

let isDoorOpen = false
const closedRot = Quaternion.fromEulerDegrees(0, 0, 0)
const openRot = Quaternion.fromEulerDegrees(0, 90, 0)

pointerEventsSystem.onProximityDown(
    {
        entity: door,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Open / Close',
            maxPlayerDistance: 5,
            priority: 1,
        },
    },
    function () {
        if (isDoorOpen) {
            Tween.setRotate(doorPivot, openRot, closedRot, 700)
            isDoorOpen = false
        } else {
            Tween.setRotate(doorPivot, closedRot, openRot, 700)
            isDoorOpen = true
        }
    }
)