Author Tutorial

Author an authored lesson

A lesson is a file-backed Rhai scenario with optional standard USD scene content. The application Rhai policy reads generic JSON asset snapshots, selects the tutorial catalog, and builds the workbench menu. The shared Rust asset and UI layers know only text assets, JSON values, and generic menu trees. The lesson does not need a Rust type, registry, lifecycle owner, or custom USD schema.

Read author-scenario first, then use assets/tutorials/README.md and the examples under assets/tutorials/.

Add a lesson

1. Add assets/tutorials/<track>/<name>.rhai.
2. If it needs a world, reuse or add an authored scene under assets/.
3. Add an entry to assets/tutorials/catalog.json:

{
  "track": "Sandbox",
  "title": "First Drive",
  "blurb": "Take control of a rover and drive it to a lunar flag.",
  "difficulty": "beginner",
  "source_asset": "lunco://tutorials/sandbox/first_drive.rhai",
  "scene_asset": "lunco://tutorials/sandbox/first_drive.usda"
}

The track value determines the submenu containing the lesson. Reuse an existing track when the lesson belongs to that learning path. The Rhai policy at assets/scripting/policy/application_asset_lifecycle.rhai discovers the unique marked catalog from generic asset-scope events and uses the shared parse_json function; do not add tutorial-specific Rust loading or menu code.

The menu submits the generic RunScenarioAsset command. It uses ScenarioReloadPolicy::Restart for a predictable fresh start and lets the command resolve an omitted host target to the active WorldRoot. Other apps can reuse the command without importing tutorial code.

Rhai contract

Use the shared prelude:

• hint(...), spotlight(anchor, caption), and notify_kind(...) for presentation;
• coach_step(steps, index) with an on_event cursor for a guided tour;
• mission(me, ctx) and objective(...) for an objective-driven exercise;
• input_binding(...)/input_hint(...) for the controller-owned semantic labels.

In LunCoSim, mission objectives are shown in View. Tutorial hints and actions remain visible in every perspective, as do spotlight and coach-step overlays; use those overlays to guide learners toward Builder or Editor panel anchors.

Use panel.center for the viewport or central work area, a generic panel.side_browser, panel.right_inspector, or panel.bottom anchor for a whole dock, and panel.<id> for a specific panel. Choose an anchor published by the active layout; coach_step focuses a named panel before drawing its spotlight.

Progression must observe semantic commands or authoritative state. Never gate a lesson on a physical key name or a timer. A lesson must not open a USD layer directly; if it needs a world, the catalog's scene_asset is the request. Never branch on the Rust build profile (is_debug() or debug_assertions). The authored lint.rhai policy rejects that coupling; use is_unattended() when attended and automated execution need different behavior.

For physical waypoint arrival, author an Avian sensor in USD and map its generic SENSOR_ENTER event to a lesson event in Rhai. Match evt.source to the exact sensor with sensor_entered(evt, sensor_id), then validate that evt.value identifies the intended subject or one of its colliders before emitting the lesson event. Use SensorOccupants in on_start to handle an existing contact. Objectives and task waits consume the lesson event; distance thresholds do not define arrival. Do not add a tutorial-specific TriggerZone label to a shared sensor asset.

Example objective:

fn mission(me, ctx) {
    [
        objective("possess", #{
            text: "Select the rover to take control",
            requires_event: "cmd:AcquireControl",
        }),
        objective("reach_flag", #{
            text: "Drive to the glowing flag",
            requires: ["possess"],
            requires_event: "flag_reached",
        }),
    ]
}