SpecsInteractionModule
ClassEntry 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
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
Properties
Methods
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
readonlyactiveInteractors: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
onInteractorAdded
readonlyonInteractorAdded: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
readonlyonInteractorRemoved: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
readonlyuniqueIdentifier:string
Since
Lens Scripting Version 176
Inherited from
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
| Parameter | Type |
|---|---|
sceneObject | SceneObject |
enterHalfExtents | vec3 |
exitHalfExtents | vec3 |
queryMask | LayerSet |
options? | OverlapProbeOptions |
Returns
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
| Parameter | Type |
|---|---|
sceneObject | SceneObject |
enterRadius | number |
exitRadius | number |
queryMask | LayerSet |
options? | OverlapProbeOptions |
Returns
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()
staticgetTypeName():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
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
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
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
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
| Parameter | Type |
|---|---|
interactableSceneObject | SceneObject |
colliders | ColliderComponent[] |
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
| Parameter | Type |
|---|---|
interactionPlaneSceneObject | SceneObject |
options | InteractionPlaneOptions |
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
| Parameter | Type |
|---|---|
options | DebugVisualizerOptions |
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
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
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
| Parameter | Type |
|---|---|
interactableSceneObject | SceneObject |
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
| Parameter | Type |
|---|---|
interactionPlaneSceneObject | SceneObject |
Returns
void
Since
Lens Scripting Version 375
Example
interaction.unregisterInteractionPlane(script.getSceneObject());
Nested types
Enumerations
| Enumeration | Description |
|---|---|
| CursorVisualMode | Cursor visual treatment. Names the manipulation in progress so the cursor can show matching translate, scale, or rotation artwork. |
| FieldState | The 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. |
| InteractorKind | The 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. |
| TargetingMode | How an interactor can target an Interactable, as a bitmask of interaction methods. Combine bits with ` |
| TargetingPriority | Targeting priority for this Interactable. Higher-priority Interactables are preferred over closer, lower-priority ones when an interactor targets. |
| TargetingVisual | The targeting visual shown while an interactor targets an Interactable or InteractionPlane. |
Classes
| Class | Description |
|---|---|
| BoxOverlapProbe | An 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. |
| CastHit | Hit result returned by SpecsInteractionModule's cast queries. See SpecsInteractionModule#rayCast, SpecsInteractionModule#rayCastAll, SpecsInteractionModule#sphereCast, and SpecsInteractionModule#sphereCastAll. For overlap detection, see OverlapProbe. |
| Cursor | The 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]. |
| CursorVisualState | Cursor 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. |
| DebugVisualizerOptions | Which debug visualizers the interaction system draws for this Lens's interaction content. Every visualizer is off by default. Pass the options to SpecsInteractionModule#setDebugVisualizerOptions. |
| InteractableOptions | Options supplied when registering an interactable. |
| InteractionPlaneOptions | Options supplied when registering an interaction plane. |
| Interactor | A 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. |
| Overlap | One 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. |
| OverlapEnterEventArgs | Args 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. |
| OverlapExitEventArgs | Args 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. |
| OverlapProbe | An 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). |
| OverlapProbeOptions | Options supplied when creating an OverlapProbe. Optional; omitting it (or any field) uses the defaults. |
| SphereOverlapProbe | An OverlapProbe whose volume is a sphere. enterRadius/exitRadius (cm) give hysteresis. Create with SpecsInteractionModule#createSphereOverlapProbe. |
| TargetingRay | The latest targeting ray for an interactor. See SpecsInteractionModule.Interactor#getTargetingRay. origin is in centimeters and direction is unit length in world space. |
| TriangleHit | Triangle hit information, available when a cast from SpecsInteractionModule intersects a collision mesh. |