Skip to main content

SpecsInteractionModule

Class

Entry point for the SPECS Interaction System.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported — Available on SPECS only
  • SPECSFully supported
  • Camera Kit WebNot supported — Available on SPECS only
  • Camera Kit MobileNot supported — Available on SPECS only

Platform details

  • Snapchat — Not supported — Available on SPECS only.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported — Available on SPECS only.

  • Camera Kit Mobile — Not supported — Available on SPECS only.

Since Lens Scripting v375

Entry point for the SPECS Interaction System.

Register a SceneObject as an Interactable to add its colliders to the interaction scene, or as an InteractionPlane to define a zone that triggers near-field targeting logic. Registered Interactable colliders drive the system's spatial queries and cursor positioning. Run ray casts, sphere casts, and overlap probes against those colliders. Read activeInteractors for the interactors present now, subscribe to onInteractorAdded and onInteractorRemoved for later changes, and read each interactor's targeting ray. The cursor is rendered for you: use the Interactor to set its visual state, lock it to a position or plane, hide it, or lock its field while an interaction is in progress.

Index

Example

const interaction = require('LensStudio:SpecsInteractionModule');
function onInteractor(interactor) {
const ray = interactor.getTargetingRay();
if (ray) {
print("interactor " + interactor.id + " aiming from " + ray.origin);
}
}
interaction.activeInteractors.forEach(onInteractor);
interaction.onInteractorAdded.add(onInteractor);

Extends

Properties

activeInteractors

readonly activeInteractors: Interactor[]

SPECS

The interactors currently available. Use this to handle interactors that already exist when your script starts, then subscribe to SpecsInteractionModule#onInteractorAdded for later arrivals. Read this and subscribe in the same synchronous block so an interactor that connects in between is not missed. Each entry provides getTargetingRay, getCursor, and the lock APIs while it is live.

Since

Lens Scripting Version 375

Example

const interaction = require('LensStudio:SpecsInteractionModule');
function onInteractor(interactor) {
print("interactor " + interactor.id);
}
interaction.activeInteractors.forEach(onInteractor);
interaction.onInteractorAdded.add(onInteractor);

name

name: string

The name of the Asset in Lens Studio.

Default Value

""

Inherited from

Asset.name


onInteractorAdded

readonly onInteractorAdded: event1<Interactor, void>

SPECS

Fires when an interactor becomes available (a hand starts tracking, a controller connects). Only future arrivals are delivered. Interactors already present when you subscribe are not replayed. To handle those, read SpecsInteractionModule#activeInteractors once before subscribing.

The handler receives the SpecsInteractionModule.Interactor. Retain it to read and control that interactor while it is live.

Since

Lens Scripting Version 375

Example

const interaction = require('LensStudio:SpecsInteractionModule');
interaction.onInteractorAdded.add(function (interactor) {
print("interactor added: " + interactor.id);
});

onInteractorRemoved

readonly onInteractorRemoved: event1<Interactor, void>

SPECS

Fires when an interactor is removed: it disconnects, or interaction is disabled for it. This is not the same as losing tracking (a hand going out of view, for example), which only flips SpecsInteractionModule.Interactor#isTracked and does not fire this event. The delivered SpecsInteractionModule.Interactor has isValid === false; use it only to identify which interactor was removed and tear down any state keyed on its id.

Since

Lens Scripting Version 375

Example

interaction.onInteractorRemoved.add(function (interactor) {
print("removed interactor " + interactor.id);
});

uniqueIdentifier

readonly uniqueIdentifier: string

Since

Lens Scripting Version 176

Inherited from

Asset.uniqueIdentifier

Methods

createBoxOverlapProbe()

createBoxOverlapProbe(sceneObject, enterHalfExtents, exitHalfExtents, queryMask, options?): BoxOverlapProbe

SPECS

Creates an edge-triggered box overlap probe that follows sceneObject, tracking its world position and rotation (uniform scale only). The probe reports colliders entering or leaving the oriented box through its onOverlapEnter and onOverlapExit events, each fired at most once per frame with a batch of that frame's changes. Subscribe immediately after creating the probe, since colliders that enter before you subscribe are not replayed.

enterHalfExtents/exitHalfExtents (cm) give per-axis hysteresis. A collider enters at enterHalfExtents and leaves at exitHalfExtents, which should be >= enterHalfExtents per axis. Equal values disable hysteresis.

queryMask matches colliders whose layerMask shares a layer with it; pass LayerSet.all() to match every supported layer. Only layers 0-63 are supported.

options (SpecsInteractionModule.OverlapProbeOptions, optional) configures the probe, e.g. per-member distance tracking via trackDistances.

Store the returned probe: it runs only while you hold a reference to it, and dropping your last one collects the probe along with its handlers. Call its destroy() to stop a probe you still hold and get a final OverlapProbe#onOverlapExit for whatever is inside.

Parameters

ParameterType
sceneObjectSceneObject
enterHalfExtentsvec3
exitHalfExtentsvec3
queryMaskLayerSet
options?OverlapProbeOptions

Returns

BoxOverlapProbe

Since

Lens Scripting Version 375

Example

const half = new vec3(5, 5, 5);
const queryMask = LayerSet.all();
const probe = interaction.createBoxOverlapProbe(script.getSceneObject(), half, half, queryMask);

createSphereOverlapProbe()

createSphereOverlapProbe(sceneObject, enterRadius, exitRadius, queryMask, options?): SphereOverlapProbe

SPECS

Creates an edge-triggered sphere overlap probe that follows sceneObject, tracking its world position. The probe reports colliders entering or leaving the sphere through its onOverlapEnter and onOverlapExit events, each fired at most once per frame with a batch of that frame's changes. Subscribe immediately after creating the probe, since colliders that enter before you subscribe are not replayed.

enterRadius/exitRadius (cm) give hysteresis. A collider enters at enterRadius and leaves at exitRadius, which should be >= enterRadius. Equal values disable hysteresis.

queryMask matches colliders whose layerMask shares a layer with it; pass LayerSet.all() to match every supported layer. Only layers 0-63 are supported.

options (SpecsInteractionModule.OverlapProbeOptions, optional) configures the probe, e.g. per-member distance tracking via trackDistances.

Store the returned probe: it runs only while you hold a reference to it, and dropping your last one collects the probe along with its handlers. Call its destroy() to stop a probe you still hold and get a final OverlapProbe#onOverlapExit for whatever is inside.

Parameters

ParameterType
sceneObjectSceneObject
enterRadiusnumber
exitRadiusnumber
queryMaskLayerSet
options?OverlapProbeOptions

Returns

SphereOverlapProbe

Since

Lens Scripting Version 375

Example

const queryMask = LayerSet.all();
const probe = interaction.createSphereOverlapProbe(script.getSceneObject(), 5, 6, queryMask);
probe.onOverlapEnter.add(function (args) {
print(args.enteredOverlaps.length + " entered");
});

getTypeName()

static getTypeName(): TypeName<SpecsInteractionModule>

SPECS

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<SpecsInteractionModule>

Since

Lens Scripting Version 375

Overrides

Asset.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

Asset.getTypeName


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

Asset.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

Asset.isSame


rayCast()

rayCast(start, end, queryMask, hitCB): void

SPECS

Returns (via callback) the nearest intersection across all registered colliders whose layerMask shares a layer with queryMask. Pass LayerSet.all() to match every supported layer. Only layers 0-63 are supported. start and end are in world space, in centimeters. A hit on an Interactable with SpecsInteractionModule.TargetingPriority.High wins over a nearer Normal-priority hit; within the same priority, the nearest hit wins. If there is no hit, the callback is called with a null hit argument. Ray casts are performed after Update, prior to LateUpdate.

A cast can be blocked by a collider from another Lens, which is not returned as a hit.

Parameters

ParameterType
startvec3
endvec3
queryMaskLayerSet
hitCB(hit?) => void

Returns

void

Since

Lens Scripting Version 375

Example

const queryMask = LayerSet.all();
interaction.rayCast(rayStart, rayEnd, queryMask, function (hit) {
if (hit && hit.collider) {
print("hit " + hit.collider.getSceneObject().name);
}
});

rayCastAll()

rayCastAll(start, end, queryMask, allHitsCB): void

SPECS

Returns (via callback) all intersections across all registered colliders whose layerMask shares a layer with queryMask. Pass LayerSet.all() to match every supported layer. Only layers 0-63 are supported. start and end are in world space, in centimeters. The callback receives an array of hits ordered by targeting priority first (Interactables with SpecsInteractionModule.TargetingPriority.High before Normal-priority ones), then by distance, nearest to farthest, within each priority. If there were no hits, the array length is 0. Ray casts are performed after Update, prior to LateUpdate.

A cast can be blocked by a collider from another Lens, which is not returned as a hit.

Parameters

ParameterType
startvec3
endvec3
queryMaskLayerSet
allHitsCB(hits) => void

Returns

void

Since

Lens Scripting Version 375

Example

const queryMask = LayerSet.all();
interaction.rayCastAll(rayStart, rayEnd, queryMask, function (hits) {
print(hits.length + " hits");
});

registerInteractable()

registerInteractable(interactableSceneObject, colliders, options?): void

SPECS

Registers a SceneObject with a set of ColliderComponents as an Interactable. The colliders become interaction targets: they are targetable by interactors (driving the cursor per the options' targetingMode and targetingVisual) and are hit by SpecsInteractionModule's casts and overlap probes.

Colliders do not have to be on interactableSceneObject. Each is hit-tested where it sits in the world, following its own SceneObject rather than interactableSceneObject. Disabling interactableSceneObject suspends hit-testing for all of its colliders, re-enabling resumes, and destroying it drops the registration. An individual collider that is disabled or destroyed drops out of hit-testing while the registration lives on, and re-enabling it restores it.

Registering again for the same SceneObject replaces the previous registration, so call this whenever the colliders or options change.

options (SpecsInteractionModule.InteractableOptions, optional) configures the Interactable, e.g. its targetingMode or layerMask; omitting it uses the defaults.

Parameters

ParameterType
interactableSceneObjectSceneObject
collidersColliderComponent[]
options?InteractableOptions

Returns

void

Since

Lens Scripting Version 375

Example

interaction.registerInteractable(script.getSceneObject(), [collider]);

registerInteractionPlane()

registerInteractionPlane(interactionPlaneSceneObject, options): void

SPECS

Registers a SceneObject as an InteractionPlane, a zone that triggers near-field targeting logic for hand interactors. Add one to dense 2D UI, such as a menu of closely packed buttons, to stabilize targeting between neighbors. The options size its interaction zones and set the targeting visual shown while an interactor targets it.

Registering again for the same SceneObject replaces the previous registration, so call this whenever the options change.

Parameters

ParameterType
interactionPlaneSceneObjectSceneObject
optionsInteractionPlaneOptions

Returns

void

Since

Lens Scripting Version 375

Example

interaction.registerInteractionPlane(script.getSceneObject(), new SpecsInteractionModule.InteractionPlaneOptions());

setDebugVisualizerOptions()

setDebugVisualizerOptions(options): void

SPECS

Sets which debug visualizers to draw for this Lens's interaction content (colliders, casts, overlap probes, the cursor, and InteractionPlanes). options is a SpecsInteractionModule.DebugVisualizerOptions; turn on each visualizer you want. The visualizers are drawn every frame until you pass different options. Pass a new DebugVisualizerOptions to turn all debug visualizers off. Has no effect in Lens Studio Preview.

Parameters

ParameterType
optionsDebugVisualizerOptions

Returns

void

Since

Lens Scripting Version 387

Example

const interaction = require('LensStudio:SpecsInteractionModule');
const options = new SpecsInteractionModule.DebugVisualizerOptions();
options.showColliders = true;
options.showQueries = true;
interaction.setDebugVisualizerOptions(options);

sphereCast()

sphereCast(radius, start, end, queryMask, hitCB): void

SPECS

Returns (via callback) the nearest intersection while sweeping a sphere from start to end across all registered colliders whose layerMask shares a layer with queryMask. Pass LayerSet.all() to match every supported layer. Only layers 0-63 are supported. radius is in centimeters; start and end are in world space, in centimeters. A hit on an Interactable with SpecsInteractionModule.TargetingPriority.High wins over a nearer Normal-priority hit; within the same priority, the nearest hit wins. If there is no hit, the callback is called with a null hit argument. Sphere casts are performed after Update, prior to LateUpdate.

A cast can be blocked by a collider from another Lens, which is not returned as a hit.

Parameters

ParameterType
radiusnumber
startvec3
endvec3
queryMaskLayerSet
hitCB(hit?) => void

Returns

void

Since

Lens Scripting Version 375

Example

const queryMask = LayerSet.all();
interaction.sphereCast(2, rayStart, rayEnd, queryMask, function (hit) {
if (hit) {
print("nearest hit at " + hit.position);
}
});

sphereCastAll()

sphereCastAll(radius, start, end, queryMask, allHitsCB): void

SPECS

Returns (via callback) all intersections while sweeping a sphere from start to end across all registered colliders whose layerMask shares a layer with queryMask. Pass LayerSet.all() to match every supported layer. Only layers 0-63 are supported. radius is in centimeters; start and end are in world space, in centimeters. The callback receives an array of hits ordered by targeting priority first (Interactables with SpecsInteractionModule.TargetingPriority.High before Normal-priority ones), then by distance, nearest to farthest, within each priority. If there were no hits, the array length is 0. Sphere casts are performed after Update, prior to LateUpdate.

A cast can be blocked by a collider from another Lens, which is not returned as a hit.

Parameters

ParameterType
radiusnumber
startvec3
endvec3
queryMaskLayerSet
allHitsCB(hits) => void

Returns

void

Since

Lens Scripting Version 375

Example

const queryMask = LayerSet.all();
interaction.sphereCastAll(2, rayStart, rayEnd, queryMask, function (hits) {
print(hits.length + " hits");
});

unregisterInteractable()

unregisterInteractable(interactableSceneObject): void

SPECS

Unregisters an Interactable. Its colliders are no longer targetable by interactors or hit by SpecsInteractionModule's casts and overlap probes.

Parameters

ParameterType
interactableSceneObjectSceneObject

Returns

void

Since

Lens Scripting Version 375

Example

interaction.unregisterInteractable(script.getSceneObject());

unregisterInteractionPlane()

unregisterInteractionPlane(interactionPlaneSceneObject): void

SPECS

Unregisters an InteractionPlane, removing its near-field targeting zone from SpecsInteractionModule.

Parameters

ParameterType
interactionPlaneSceneObjectSceneObject

Returns

void

Since

Lens Scripting Version 375

Example

interaction.unregisterInteractionPlane(script.getSceneObject());

Nested types

Enumerations

EnumerationDescription
CursorVisualModeCursor visual treatment. Names the manipulation in progress so the cursor can show matching translate, scale, or rotation artwork.
FieldStateThe targeting field an interactor is in, resolved by SpecsInteractionModule against the registered InteractionPlanes: targeting from a distance (FarField), hovering inside a plane's near-field zone (NearField), touching its physical zone (Physical), or having passed behind it (BehindNearField). Read it from SpecsInteractionModule.Interactor#fieldState.
InteractorKindThe category of an interactor. Distinct from an interactor's id, which is its runtime identity: two interactors can share a kind while having different ids.
TargetingModeHow an interactor can target an Interactable, as a bitmask of interaction methods. Combine bits with `
TargetingPriorityTargeting priority for this Interactable. Higher-priority Interactables are preferred over closer, lower-priority ones when an interactor targets.
TargetingVisualThe targeting visual shown while an interactor targets an Interactable or InteractionPlane.

Classes

ClassDescription
BoxOverlapProbeAn OverlapProbe whose volume is an oriented box that tracks the SceneObject's world rotation (uniform scale only). enterHalfExtents/exitHalfExtents (cm) give per-axis hysteresis. Create with SpecsInteractionModule#createBoxOverlapProbe.
CastHitHit result returned by SpecsInteractionModule's cast queries. See SpecsInteractionModule#rayCast, SpecsInteractionModule#rayCastAll, SpecsInteractionModule#sphereCast, and SpecsInteractionModule#sphereCastAll. For overlap detection, see OverlapProbe.
CursorThe latest cursor pose for an interactor. See SpecsInteractionModule.Interactor#getCursor. position is in centimeters in world space and opacity is in the range [0, 1].
CursorVisualStateCursor visual state, passed to SpecsInteractionModule.Interactor#setCursorVisualState. A default-constructed instance (Auto mode, no hold, all flags false) clears any state previously set for the interactor.
DebugVisualizerOptionsWhich debug visualizers the interaction system draws for this Lens's interaction content. Every visualizer is off by default. Pass the options to SpecsInteractionModule#setDebugVisualizerOptions.
InteractableOptionsOptions supplied when registering an interactable.
InteractionPlaneOptionsOptions supplied when registering an interaction plane.
InteractorA live interactor. Read SpecsInteractionModule#activeInteractors for those present now and subscribe to SpecsInteractionModule's onInteractorAdded event for later arrivals. Call its methods to read targeting state and control its cursor and field locks. id is the interactor's opaque runtime identity, useful for maps and event correlation. It is not an SpecsInteractionModule.InteractorKind and must not be compared against kind values. Its numeric value is not reused for another Interactor while the Lens is running. The handle is valid until onInteractorRemoved. After removal isValid is false, reads return null, control methods do nothing, and it should only be used to identify which instance to tear down. Retain it across frames during that window. isTracked updates live.
OverlapOne collider inside an overlap probe's volume, with an id stable from the enter to the exit of that membership. Delivered via OverlapEnterEventArgs#enteredOverlaps and OverlapExitEventArgs#exitedOverlaps.
OverlapEnterEventArgsArgs for OverlapProbe#onOverlapEnter, delivered once per frame: enteredOverlaps, every membership that entered the probe's volume this frame. To track the full set currently inside, keep a collection keyed by Overlap#id, adding on enter and removing on OverlapExitEventArgs#exitedOverlaps.
OverlapExitEventArgsArgs for OverlapProbe#onOverlapExit, delivered once per frame: exitedOverlaps, every membership that left the probe's volume this frame (or whose collider was removed while a member, or that remained when the probe itself was removed). To track the full set currently inside, keep a collection keyed by Overlap#id, adding on OverlapEnterEventArgs#enteredOverlaps and removing on exit.
OverlapProbeAn edge-triggered overlap probe. Follows a SceneObject and reports, at most once per frame, the colliders that entered or left a volume around it, via OverlapProbe#onOverlapEnter and OverlapProbe#onOverlapExit. The volume's shape is fixed at creation: a SpecsInteractionModule.SphereOverlapProbe (see SpecsInteractionModule#createSphereOverlapProbe) or a SpecsInteractionModule.BoxOverlapProbe (see SpecsInteractionModule#createBoxOverlapProbe).
OverlapProbeOptionsOptions supplied when creating an OverlapProbe. Optional; omitting it (or any field) uses the defaults.
SphereOverlapProbeAn OverlapProbe whose volume is a sphere. enterRadius/exitRadius (cm) give hysteresis. Create with SpecsInteractionModule#createSphereOverlapProbe.
TargetingRayThe latest targeting ray for an interactor. See SpecsInteractionModule.Interactor#getTargetingRay. origin is in centimeters and direction is unit length in world space.
TriangleHitTriangle hit information, available when a cast from SpecsInteractionModule intersects a collision mesh.