Controlspreview

Define buttons, sliders, keys, taps and on-screen text in controls.ui.yaml, and handle them in Motoko.

The player draws your game's controls and on-screen text from controls.ui.yaml, and handles keyboard, mouse and touch input. Your actor receives named actions in moxzi_input.

The file's metadata must have kind: ui and address: ui/main, or the player won't find it.

version: 1
title: Drift
labels:
  - id: position
    fallback: "x = 0.0 m"
buttons:
  - id: center
    label: Center
    action: center
    key: space
axes:
  - id: steer
    action: steer
    range: [-5000, 5000]
    initial: 0
    negative_key: a
    positive_key: d
    units_per_second: 4000

Top-level fields#

Unknown fields are an error.

Buttons#

Handle the action in moxzi_input:

public shared ({ caller }) func moxzi_input(command : Input.Command) : async Hud.InputAck {
  assert host == ?caller and not suspended;
  assert command.epoch == epoch and command.at_tick == tick;
  assert command.sequence == sequence + 1;
  sequence := command.sequence;

  let accepted = switch (command.action) {
    case "steer" {
      // Axis values arrive as decimal text, such as "-2500".
      switch (parseInt(command.payload)) {
        case (?mm) { target := mm; true };
        case null false;
      }
    };
    case "center" { target := 0; clickPending := true; true };
    case _ false;
  };
  { epoch; sequence; at_tick = tick; accepted; paused = false; output = ""; hud = ?hud() }
};

Player-only buttons#

A button with local instead of action controls the player itself and never reaches your actor:

Axes#

An axis is a value in a range that keys or dragging change. The player sends the value to your actor as decimal text whenever it changes.

Values arrive as UTF-8 text such as "-2500". Parse them as in Drift's parseInt, and reject anything that doesn't parse.

Dragging in the scene#

With plane, the player projects the pointer onto a plane in the world, so the value follows the finger or mouse exactly. Pong uses this for the paddle:

Tapping the world#

point sends an action when the player taps or clicks the scene:

point:
  action: select
  plane:
    origin: [0, 0, 0]
    normal: [0, 1, 0]
    axis: [1, 0, 0]
    half_extent: [50, 50]
    units_per_meter: 1000

The payload is the position on the plane as "U,V" text.

Labels#

labels:
  - id: position
    fallback: "x = 0.0 m"

The player shows fallback until your actor sets the text. Set label text by returning hud = ?[{ id; text }] from moxzi_advance, moxzi_input or moxzi_snapshot. The list replaces all label text: labels you leave out show their fallback again. Return hud = null to keep the current text.

Keys#

Any other key is rejected when the game is played, with invalid UI YAML: … unknown variant.

Rules for handling input#

• Check that command.at_tick is the current tick and command.sequence is one more than the last. Commands arrive between ticks, in order.
• command.player identifies a player in multiplayer setups. It's game data, not authentication; caller is the player process.
• Return accepted = false for actions or payloads you don't recognise. Don't change state in that case.
• While the game is suspended (see moxzi_lifecycle), the player sends no input.

Limitations#