wired:script

A script's lifecycle, and what it can ask the host about itself.

Interface lifecycle

Exported by every script. The host calls into it. A script never calls these itself.

Calls never overlap. Each export returns before the host makes the next call into the same script. A call that is still running when its next turn comes skips that turn rather than queueing it. A script that never returns is stopped and not called again.

tick

When a call is made, measured on one clock this peer's scripts share. The clock is monotonic but is not synchronized with other peers.

init

Called once, before any other export. An error retires the script, with the message logged.

update

Called once per rendered frame. Drawing and animation belong here.

fixed-update

Called at a fixed rate the host chooses (currently 20 Hz), carried in tick.dt. Input, messages and simulation belong here.

Interface host

Uses permission.

What a script can ask the host about itself.

granted

Whether the script's document holds permission now. Grants can change while a script runs, as the user decides how far to trust an author.

Source

/// A script's lifecycle, and what it can ask the host about itself.
package wired:script;

/// Exported by every script. The host calls into it. A script never calls
/// these itself.
///
/// Calls never overlap. Each export returns before the host makes the next
/// call into the same script. A call that is still running when its next
/// turn comes skips that turn rather than queueing it. A script that never
/// returns is stopped and not called again.
interface lifecycle {
  /// When a call is made, measured on one clock this peer's scripts share.
  /// The clock is monotonic but is not synchronized with other peers.
  record tick {
    /// Seconds since the previous call of the same export, zero for the
    /// first.
    dt:    f32,
    /// Seconds on the host clock.
    time:  f64,
    /// How many calls of this export came before this one.
    index: u64,
  }

  /// Called once, before any other export. An error retires the script,
  /// with the message logged.
  init: func() -> result<_, string>;

  /// Called once per rendered frame. Drawing and animation belong here.
  update: func(tick: tick);

  /// Called at a fixed rate the host chooses (currently 20 Hz), carried in
  /// `tick.dt`. Input, messages and simulation belong here.
  fixed-update: func(tick: tick);
}

/// What a script can ask the host about itself.
interface host {
  use wired:core/error.{permission};

  /// Whether the script's document holds `permission` now. Grants can
  /// change while a script runs, as the user decides how far to trust an
  /// author.
  granted: func(permission: permission) -> bool;
}