📰Getting Started | ⭐**Updates |** 📝 Guides | 🔢 API | ❓FAQ

Guides Overview

• Web Editor Basics

• HoloLens

• Mobile

• Meta Quest

• Chapter Series Documentation

• Assets

• Scripting

• Enklu Embedded

• API Reference

  Scripting Overview

  Proximity

  Random

• Release Notes

  Release Notes

• FAQ

  FAQ

  Privacy Policy

• Contact

The Proximity API allows functions in Behavior scripts to be executed as a response to distance-based proximity events on Elements.

Essentially, when you get close (or far away) enough to an object, you can make events occur at that moment using this API.

This API is available via require statements.

const proximity = require('proximity');

Distance Calculations

The Proximity API measures whether or not elements are in proximity of others using an internal distance calculation method. When the distance calculated is close enough to the proximity radius you set in the Schema section below, an event will occur.

There are two methods for calculating distance, that are more helpful in different scenarios.

• (Default) Horizontal Distance
  • Calculates distance purely based on how far away from an object you are on a horizontal plane.
  • This means that your Y-value or altitude is not taken into account. You will always register proximity events if you are directly above or below an object even if you are still quite a vertical distance away, since you are technically intersecting the object on a horizontal plane, if you’re looking from a top-down perspective.
  • You can think of the proximity radius as an infinitely tall cylinder.
    • Once you enter this cylinder at any altitude, proximity will be triggered, since it has infinite height.
• 3D Distance
  • Calculates distance based on your distance from the object in a 3D space.
  • This takes your Y-value or altitude into account. Even if you are directly above an object, you may not trigger a proximity event since your distance may still exceed the proximity radius in 3D space.
  • You can think of the proximity radius as a sphere.
    • Once you enter this sphere, proximity will be triggered, but if you are anywhere outside of the sphere, no matter above, below or to the side, you will not trigger it.

These methods can be toggled with the two functions below. Once either of these functions are called, the Proximity API will calculate distance based on the specified method until it is changed.

The distance method is set globally. Different scripts can not use different distance calculation methods, for example. Once you set it in one script, you will set it for all of them.

const proximity = require('proximity');

// sets proximity to calculate horizontal distance
proximity.useHorizontalDistance();

// sets proximity to calculate horizontal distance
proximity.use3DDistance();

You can call either of these functions in the enter() function of a script to set the distance method you want to use from the moment that script is created.

Subscriptions

Proximity events are dispatched when a Trigger enters a subscribed Element's radius. By default the user is a Trigger, and other Elements can be set as Triggers through their schema. Additionally, a trigger or subscribed Element's radius can be configured through schema editing.

function enter(){
    proximity.subscribe(this, 'enter', onTriggerEnter);
    proximity.subscribe(this, 'exit', onTriggerExit);
}

function onTriggerEnter(){
this.transform.scale = vec3(0.5, 0.5, 0.5);
}

function onTriggerExit(){
this.transform.scale = vec3(1, 1, 1);
}

function exit(){
    proximity.unsubscribe(this, 'enter', onTriggerEnter);
    proximity.unsubscribe(this, 'exit', onTriggerExit);
}

Any Element can be subscribed for a proximity event. Callbacks are invoked with a reference to the Trigger that entered its innerRadius. Any Trigger that is above or below a subscribed Element in the hierarchy won't invoke events. It is good practice to call subscribe in a script's enter and unsubscribe in exit.

The proximity callbacks have optional arguments, which contain information on which listener & trigger were responsible for the event.

function onTriggerEnter(listener, trigger) {
  log.info('Proximity Event!');
  log.info('Listener: ' + listener);
  log.info('Trigger: ' + trigger);
}

Schema

All schema configuration is done under the proximity namespace.

// marks an element as a trigger.
this.schema.setNumber('proximity.trigger', true);

// The distance where an element or trigger will dispatch 'enter' events.
this.schema.setNumber('proximity.innerRadius', 0.25);

// The distance where an element or trigger will dispatch 'exit' events.
this.schema.setNumber('proximity.outerRadius', 2);

Module Events

• enter - Dispatched when a Trigger first enters a subscribed Element's innerRadius..
• stay - Dispatched every frame after a Trigger enters a subscribed Element's innerRadius, but hasn't exited its outerRadius.
• exit - Dispatched when a Trigger exits a subscribed Element's outerRadius.

Module Methods

subscribe(element, event, callback)

• element <Element> The element to listen for events applied to it.
• event <string> The event to subscribe to.
• callback <function> The function invoked when the event occurs.

Subscribes to a proximity event.

unsubscribe(element, event, callback)

• element <Element> The element that will be unsubscribed.
• event <string> The event to unsubscribe from.
• callback <function> The callback to unsubscribe.

Unsubscribes from a proximity event.

useHorizontalDistance()

Sets the Proximity API to trigger proximity events based on your distance from an element on a horizontal plane.

use3DDistance()

Sets the Proximity API to trigger proximity events based on your distance from an element in 3D space.

forceProximityCheck()

Forces an event check regardless of any previous collisions.

Next: Random

Sidebar Table of Contents