wired:input

Pointer input from the local user: aimed at prims, or for the whole device.

A pointer is the screen cursor on desktop, or a hand in VR. Its trigger acts on what it points at. Its grip takes hold of it.

Interface types

Uses vec2, vec3, ray, prim-ref.

pointer-kind

button

hit

Where a pointer's ray met a collider.

action

What reaches which listener:

input-event

pointer

A pointer's state this frame.

input-subscription

Holds up to 64 events.

drain

dropped

Interface targeted

Uses prim-id, error, document, input-subscription.

Input aimed at a prim.

listen

Input aimed at prim or anything beneath it, in a document the script may write. Only prims with a collider can be aimed at.

Interface device

Uses error, input-subscription, pointer.

Every input of the local user's devices.

listen

pointers

Every pointer kind, active or not.

Source

/// Pointer input from the local user: aimed at prims, or for the whole
/// device.
///
/// A pointer is the screen cursor on desktop, or a hand in VR. Its trigger
/// acts on what it points at. Its grip takes hold of it.
package wired:input;

interface types {
  use wired:core/math.{vec2, vec3, ray};
  use wired:core/ids.{prim-ref};

  enum pointer-kind {
    /// The desktop cursor, aimed from the camera.
    screen,
    left-hand,
    right-hand,
  }

  enum button {
    trigger,
    grip,
    menu,
  }

  /// Where a pointer's ray met a collider.
  record hit {
    /// The prim whose collider it met, when it belongs to a document.
    target:   option<prim-ref>,
    position: vec3,
    normal:   vec3,
    distance: f32,
  }

  /// What reaches which listener:
  ///
  /// | action               | targeted | device |
  /// |----------------------|----------|--------|
  /// | trigger, grip        | yes      | yes    |
  /// | menu                 | no       | yes    |
  /// | scroll               | yes      | yes    |
  /// | entered, left        | yes      | no     |
  variant action {
    pressed(button),
    /// A targeted listener hears the release of every press it heard,
    /// wherever the pointer has since moved.
    released(button),
    /// Notches turned on each axis.
    scroll(vec2),
    entered,
    left,
  }

  record input-event {
    pointer: pointer-kind,
    action:  action,
    ray:     ray,
    hit:     option<hit>,
  }

  /// A pointer's state this frame.
  record pointer {
    kind:    pointer-kind,
    /// Whether it is tracked and usable this frame. An inactive pointer's
    /// other fields are zero.
    active:  bool,
    ray:     ray,
    /// How far the trigger is pulled, 0 to 1.
    trigger: f32,
    /// How far the hand is closed, 0 to 1.
    grip:    f32,
    /// Thumbstick travel, each axis -1 to 1.
    axis:    vec2,
    hit:     option<hit>,
  }

  /// Holds up to 64 events.
  resource input-subscription {
    drain:   func(max: u32) -> list<input-event>;
    dropped: func() -> u64;
  }
}

/// Input aimed at a prim.
interface targeted {
  use wired:core/ids.{prim-id};
  use wired:core/error.{error};
  use wired:scene/document.{document};
  use types.{input-subscription};

  /// Input aimed at `prim` or anything beneath it, in a document the script
  /// may write. Only prims with a collider can be aimed at.
  listen: func(document: borrow<document>, prim: prim-id) -> result<input-subscription, error>;
}

/// Every input of the local user's devices.
interface device {
  use wired:core/error.{error};
  use types.{input-subscription, pointer};

  listen:   func() -> result<input-subscription, error>;
  /// Every pointer kind, active or not.
  pointers: func() -> result<list<pointer>, error>;
}