Lens Scripting API
    Preparing search index...

    Class 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.

    Lens Scripting Version 375

    interaction.onInteractorAdded.add(function (interactor) {
        print("interactor " + interactor.id + ", kind " + interactor.kind);
    });

    Hierarchy (View Summary)

    Index

    Properties

    engagedPlane fieldState id isFieldLocked isTracked isValid kind

    Methods

    getCursor getTargetingRay getTypeName getTypeName isOfType isSame lockCursorToCollider lockCursorToPlane lockCursorToPosition lockField setCursorVisible setCursorVisualState unlockCursor unlockField

    Properties

    engagedPlane: SceneObject

    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.

    Lens Scripting Version 375

    fieldState: FieldState

    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.

    Lens Scripting Version 375

    id: number

    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.

    Lens Scripting Version 375

    isFieldLocked: boolean

    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.

    Lens Scripting Version 375

    isTracked: boolean

    Whether the interactor is currently tracked this frame. Updates live while the handle is held.

    Lens Scripting Version 375

    isValid: boolean

    Whether the handle still refers to a live interactor. Already false by the time onInteractorRemoved fires, so do not gate removal cleanup on it.

    Lens Scripting Version 375

    kind: InteractorKind

    The interactor's category (hand, mobile controller, ...). Immutable for the handle's lifetime.

    Lens Scripting Version 375

    Methods

    • 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 Cursor

      Lens Scripting Version 375

      const cursor = interactor.getCursor();
      if (cursor) {
          print("cursor at " + cursor.position + " opacity " + cursor.opacity);
      }

    • 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 TargetingRay

      Lens Scripting Version 375

      const ray = interactor.getTargetingRay();
      if (ray) {
          print("aim direction " + ray.direction);
      }

    • 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 string

      Lens Scripting Version 375

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

      Parameters

      • type: string

      Returns boolean

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

      Parameters

      Returns boolean

    • 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

      Returns void

      Lens Scripting Version 375

      interaction.rayCast(start, end, LayerSet.all(), function (hit) {
          if (hit && hit.collider) {
              interactor.lockCursorToCollider(hit.collider, hit.position);
          }
      });

    • 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

      Lens Scripting Version 375

      interactor.lockCursorToPlane(
          new vec3(0, 0, 0),
          new vec3(0, 0, 1),
          new vec3(0, 0, 0));

    • 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

      Returns void

      Lens Scripting Version 375

      interactor.lockCursorToPosition(new vec3(0, 0, -50));

    • 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

      Lens Scripting Version 375

      interactor.lockField();

    • 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

      • visible: boolean

      Returns void

      Lens Scripting Version 375

      interactor.setCursorVisible(false);

    • 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

      Returns void

      Lens Scripting Version 375

      const state = new SpecsInteractionModule.CursorVisualState();
      state.holdProgress = 0.5;
      state.holdThresholdMs = 800;
      interactor.setCursorVisualState(state);

    • Release the active cursor lock for this interactor.

      Returns void

      Lens Scripting Version 375

      interactor.unlockCursor();

    • Release a field lock for this interactor immediately.

      Returns void

      Lens Scripting Version 375

      interactor.unlockField();

    Settings

    Member Visibility

    On This Page

    Properties
    Methods