wired:portal

Portals between spaces, and travel through them.

A two-way portal is two halves, one in each space, bearing the same link. Opening one half asks the scripts of the target space for the other: they hear a link-intent and answer it with pair.

Interface portals

Uses document-id, prim-id, error, document, link-id.

link-intent

A portal in source-space bearing link that nothing in this space answers yet.

intent-subscription

Holds up to 64 intents.

drain

dropped

claim

Takes intent for this script, answering whether it won. Exactly one subscriber in the space does.

open

Points the portal on prim into target-space for this session, keeping its size, as a shared write. Fails with invalid-argument on a prim with no portal.

The link is derived from the prim and the target, so every peer opening the same portal states the same one.

pair

Answers intent with the portal on prim, as a shared write.

travel

Moves the local user into target-space, loading it if needed.

intents

Hears intents addressed to the script's space, each once.

Source

/// Portals between spaces, and travel through them.
///
/// A two-way portal is two halves, one in each space, bearing the same
/// link. Opening one half asks the scripts of the target space for the other:
/// they hear a `link-intent` and answer it with `pair`.
package wired:portal;

interface portals {
  use wired:core/ids.{document-id, prim-id};
  use wired:core/error.{error};
  use wired:scene/document.{document};
  use wired:scene/properties.{link-id};

  /// A portal in `source-space` bearing `link` that nothing in this space
  /// answers yet.
  record link-intent {
    source-space: document-id,
    link:         link-id,
  }

  /// Points the portal on `prim` into `target-space` for this session,
  /// keeping its size, as a `shared` write. Fails with `invalid-argument`
  /// on a prim with no portal.
  ///
  /// The link is derived from the prim and the target, so every peer
  /// opening the same portal states the same one.
  open: func(document: borrow<document>, prim: prim-id, target-space: document-id) -> result<_, error>;

  /// Answers `intent` with the portal on `prim`, as a `shared` write.
  pair: func(document: borrow<document>, prim: prim-id, intent: link-intent) -> result<_, error>;

  /// Moves the local user into `target-space`, loading it if needed.
  travel: func(target-space: document-id) -> result<_, error>;

  /// Hears intents addressed to the script's space, each once.
  intents: func() -> result<intent-subscription, error>;

  /// Holds up to 64 intents.
  resource intent-subscription {
    drain:   func(max: u32) -> list<link-intent>;
    dropped: func() -> u64;
    /// Takes `intent` for this script, answering whether it won. Exactly one
    /// subscriber in the space does.
    claim:   func(intent: link-intent) -> bool;
  }
}