Skip to content

CONTEXT.md

Latest commit

 

History

History
122 lines (96 loc) · 4.63 KB

CONTEXT.md

File metadata and controls

122 lines (96 loc) · 4.63 KB
Raw

XR Blocks agent contract

XR Blocks is a WebXR SDK for AI and XR applications that also run in its desktop simulator. Use this file as the compact authoring contract. Load the manual page and executable example for the specific task instead of guessing from subsystem names.

Authority order

When sources disagree, use this order:

  1. src/xrblocks.ts and an addon's public entry define what application code can import.
  2. Source TSDoc and generated declarations define signatures, defaults, return values, and lifecycle details.
  3. docs/docs/manual/ defines concepts, setup, behavior, limits, and current composition patterns.
  4. templates/ and samples/ provide executable patterns. Prefer a focused template or sample over a large demo.
  5. Consumer task skills define the process for completing a task. They are not API catalogs.

If a symbol is not exported by the intended public entry, it is internal.

Application shape

import * as THREE from 'three';
import * as xb from 'xrblocks';

class MainScript extends xb.Script {
  init() {
    this.add(new THREE.HemisphereLight(0xffffff, 0x666666, 3));
  }

  update() {
    // Per-frame application behavior.
  }

  dispose() {
    // Release owned GPU, listener, timer, media, and network resources.
  }
}

const options = new xb.Options();
xb.add(new MainScript());
await xb.init(options);
  • Register scripts before xb.init(options).
  • Use engine-created objects only in or after init().
  • Put frame behavior in update(). XR Blocks owns the renderer, camera, animation loop, WebXR session, input resolution, and UI renderer.
  • Configure permissions and optional subsystems before initialization.
  • Use formFactor: 'auto' unless the application intentionally targets only one surface. ?formFactor=desktop forces the simulator.

Spatial and UI units

  • World positions, model dimensions, placement offsets, and fixed UICard.size values use meters. Use size.height: 'auto' for a card that fits its child layout while keeping a fixed width.
  • Descendant UI layout numbers use UIKit layout units. Percent strings and auto are accepted where the property type permits them.
  • Numeric lineHeight is a multiplier of fontSize. Use a px or percentage string for an explicit line height.
  • Use UICard for world-space UI, UIOverlay for view-space UI, and UIPanel only as a nested layout group.
  • Built-in UI starts automatically and participates in the normal interaction pipeline. There is no application UI enable call or second UI raycaster.

Interaction vocabulary

XR Blocks resolves one hit for each source:

  • source: the mouse, gaze, hand, or tracked-controller interaction source.
  • target: the logical object that owns the behavior.
  • surface: the public object representing the hit surface. Private renderer meshes are normalized to their public owner.
  • currentTarget: the script currently receiving a bubbled callback.
  • intersection: the resolved ray hit when the source still intersects the surface.

Use the event's resolved fields inside callbacks. Query xb.user.getRayIntersection() only when code outside an event needs the current hit. A reticle displays the resolved hit; it is not a second source of target data.

Configure automatic manipulation through object.xb.manipulation. It supports independent simultaneous object owners and two-source scale. Read Interaction and Placement before implementing manipulation or continuous placement.

Security and runtime limits

  • Never commit provider keys. URL keys and keys.json are local-prototype mechanisms only. Production applications use a server-controlled proxy or short-lived credentials.
  • Camera, microphone, geolocation, depth, and world-sensing support depend on the browser and device. Declare required permissions before entering XR and provide visible unsupported, denied, pending, empty, and failure states.
  • three is a peer dependency. Use one aligned version and one import-map or bundler dependency graph.
  • The package uses private lazy-loaded chunks. Deploy the complete build/ directory and do not import build/internal/ files.

Task workflows

The repository provides six portable consumer workflows:

  • xb-build-app
  • xb-add-spatial-ui
  • xb-add-interactions
  • xb-add-world-sensing
  • xb-add-ai
  • xb-debug-app

Repository contributors use skills/xb-contribute-sdk.

The workflows are not tied to one agent host. Each host can install or expose the skills/<name>/ directories through its supported discovery mechanism.