SpecsInteractionModule.Interactor
ClassA live interactor.
- 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
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.
Index
Properties
Methods
Example
interaction.onInteractorAdded.add(function (interactor) {
print("interactor " + interactor.id + ", kind " + interactor.kind);
});
Extends
Properties
engagedPlane
readonlyengagedPlane:SceneObject
SPECS
The SceneObject registered via SpecsInteractionModule#registerInteractionPlane whose InteractionPlane this interactor's field engagement is against. Null when SpecsInteractionModule.Interactor#fieldState is FarField, when the engaged plane belongs to another Lens, or when this handle is invalid. Updates live.
Since
Lens Scripting Version 375
fieldState
readonlyfieldState:FieldState
SPECS
The targeting field SpecsInteractionModule resolved for this interactor: FarField when targeting from a distance, NearField/Physical/BehindNearField relative to an engaged InteractionPlane. Updates live while the handle is held. The engaged plane may belong to another Lens; check SpecsInteractionModule.Interactor#engagedPlane to tell. Reads FarField when this handle is invalid.
Since
Lens Scripting Version 375
id
readonlyid:number
SPECS
The interactor's opaque runtime identity. Stable for the interactor's lifetime and not reused for another Interactor while the Lens is running. Use it to key state and correlate add/remove events. This is not a kind.
Since
Lens Scripting Version 375
isFieldLocked
readonlyisFieldLocked:boolean
SPECS
Whether this interactor's field is currently locked. This is the effective state: the service promotes a lock while a pinch is in progress, so it can be true without a prior SpecsInteractionModule.Interactor#lockField call. Updates live. Reads false when this handle is invalid.
Since
Lens Scripting Version 375
isTracked
readonlyisTracked:boolean
SPECS
Whether the interactor is currently tracked this frame. Updates live while the handle is held.
Since
Lens Scripting Version 375
isValid
readonlyisValid:boolean
SPECS
Whether the handle still refers to a live interactor. Already false by the time
onInteractorRemoved fires, so do not gate removal cleanup on it.
Since
Lens Scripting Version 375
kind
readonlykind:InteractorKind
SPECS
The interactor's category (hand, mobile controller, ...). Immutable for the handle's lifetime.
Since
Lens Scripting Version 375
Methods
getCursor()
getCursor():
Cursor
SPECS
Returns the latest cursor pose for this interactor, or null when it is not present this frame
(see SpecsInteractionModule#activeInteractors). A present interactor that is not currently
tracked still returns a Cursor with isTracked false; null means no such interactor, not an
untracked one. The cursor is sampled before Update and again before LateUpdate, so polling from an
Update or LateUpdate event handler yields the freshest pose available at that phase. position
is in centimeters in world space.
This is a shared, reused instance. Valid for the current frame only, re-fetch each frame. Copy any value you need to keep beyond the current frame.
Returns
Since
Lens Scripting Version 375
Example
const cursor = interactor.getCursor();
if (cursor) {
print("cursor at " + cursor.position + " opacity " + cursor.opacity);
}
getTargetingRay()
getTargetingRay():
TargetingRay
SPECS
Returns the latest targeting ray for this interactor, or null when it has no live state this frame. The ray is sampled before Update and again before LateUpdate, so polling from an Update or LateUpdate event handler yields the freshest ray available at that phase. Coordinates are in world space.
This is a shared, reused instance. Valid for the current frame only, re-fetch each frame. Copy any value you need to keep beyond the current frame.
Returns
Since
Lens Scripting Version 375
Example
const ray = interactor.getTargetingRay();
if (ray) {
print("aim direction " + ray.direction);
}
getTypeName()
staticgetTypeName():TypeName<Interactor>
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<Interactor>
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
lockCursorToCollider()
lockCursorToCollider(
collider,worldPosition):void
SPECS
Lock the cursor for this interactor to a point that follows a registered collider. Pass the point in world space; it need not lie on the collider's surface. The point tracks the collider's position, rotation, and scale. This does not keep the collider alive: if the collider or its SceneObject is destroyed, the cursor stops following and stays at the last position it reached.
The collider must belong to a registered Interactable when this method is called. The lock persists if that Interactable is later unregistered, until you call SpecsInteractionModule.Interactor#unlockCursor, replace it with another cursor lock, the interactor is removed, or the Lens ends. Invalid input is ignored and leaves any existing lock unchanged.
Parameters
| Parameter | Type |
|---|---|
collider | ColliderComponent |
worldPosition | vec3 |
Returns
void
Since
Lens Scripting Version 375
Example
interaction.rayCast(start, end, LayerSet.all(), function (hit) {
if (hit && hit.collider) {
interactor.lockCursorToCollider(hit.collider, hit.position);
}
});
lockCursorToPlane()
lockCursorToPlane(
planeOrigin,planeNormal,fallbackPosition):void
SPECS
Lock the cursor for this interactor to a plane. The cursor is placed where the targeting ray
intersects the plane, including when the ray origin is behind the plane. If the ray is parallel
to the plane (no intersection), the cursor falls back to fallbackPosition. The plane normal
need not be unit length; non-unit vectors are normalized internally.
The lock persists until you call SpecsInteractionModule.Interactor#unlockCursor, the
interactor is removed, or the Lens ends. Call again to update parameters. A degenerate (zero or
near-zero length) or non-finite normal, origin, or fallbackPosition is ignored and leaves any
existing lock unchanged.
Parameters
Returns
void
Since
Lens Scripting Version 375
Example
interactor.lockCursorToPlane(
new vec3(0, 0, 0),
new vec3(0, 0, 1),
new vec3(0, 0, 0));
lockCursorToPosition()
lockCursorToPosition(
position):void
SPECS
Lock the cursor for this interactor to a world-space position. The lock persists until you call SpecsInteractionModule.Interactor#unlockCursor, the interactor is removed, or the Lens ends. Call again to update the position. A non-finite position is ignored and leaves any existing lock unchanged.
Parameters
| Parameter | Type |
|---|---|
position | vec3 |
Returns
void
Since
Lens Scripting Version 375
Example
interactor.lockCursorToPosition(new vec3(0, 0, -50));
lockField()
lockField():
void
SPECS
Lock this interactor's field state, holding its engaged plane and freezing targeting re-evaluation while an interaction is in progress. The lock persists until you call SpecsInteractionModule.Interactor#unlockField, the interactor is removed, or the Lens ends.
Returns
void
Since
Lens Scripting Version 375
Example
interactor.lockField();
setCursorVisible()
setCursorVisible(
visible):void
SPECS
Show or hide the cursor for this interactor. Hiding is visual only: targeting, ray casts, overlap probes, and interaction events continue unaffected. The hidden state persists until you show it again, the interactor is removed, or the Lens ends.
Parameters
| Parameter | Type |
|---|---|
visible | boolean |
Returns
void
Since
Lens Scripting Version 375
Example
interactor.setCursorVisible(false);
setCursorVisualState()
setCursorVisualState(
visualState):void
SPECS
Set this interactor's cursor visual state: the visual mode (manipulation arrows), the long-press hold timer that drives the timer arc, and the press/near-field flags. The state persists until you change it, the interactor is removed, or the Lens ends. Submitting a default-constructed SpecsInteractionModule.CursorVisualState (Auto, zero hold progress, all flags false) clears it.
Parameters
| Parameter | Type |
|---|---|
visualState | CursorVisualState |
Returns
void
Since
Lens Scripting Version 375
Example
const state = new SpecsInteractionModule.CursorVisualState();
state.holdProgress = 0.5;
state.holdThresholdMs = 800;
interactor.setCursorVisualState(state);
unlockCursor()
unlockCursor():
void
SPECS
Release the active cursor lock for this interactor.
Returns
void
Since
Lens Scripting Version 375
Example
interactor.unlockCursor();
unlockField()
unlockField():
void
SPECS
Release a field lock for this interactor immediately.
Returns
void
Since
Lens Scripting Version 375
Example
interactor.unlockField();