Author Rhai Tool

Author a reusable Rhai tool library

A tool library is named, reusable Rhai policy. It is not a second simulator core, a hidden USD writer, or a vehicle-specific Rust feature. A good tool turns a repeated authoring or inspection decision into a deterministic, discoverable function while leaving USD, the document journal, projection, physics, and solver ownership in their existing typed owners.

Read the focused contract when implementing one: references/tool-authoring-contract.md. For queued pointer/menu calls, follow the canonical one-shot ownership contract.

Choose the tool's home

• Put a reusable engine/editor policy in assets/scripting/tools/<name>.rhai. The authored scripting.source.classify startup policy admits this source as a callable library; it is still a Rhai tool, not a Rust vehicle implementation. Other .rhai files, including tests and scenarios, are loaded only by an explicit scene/runtime request or the CLI test path. In an external Twin session, verify admission with ListToolLibraries after /api/ready; a policy-layer handoff must re-admit standard tools when the classifier returns. Startup admission, Bevy source publication, and runtime preparation are ordered. The runtime keeps the current admitted sources and closes script execution while the required classifier is temporarily unavailable during a policy replacement.
• Put a Twin-specific builder, component lint, or requirement helper in <twin>/tools/<name>.rhai. It is persisted with that Twin and must not leak into unrelated Twins. Persisted library names are portable single file stems; Windows device names, reserved punctuation and trailing dots/spaces are rejected on every host. Literal #, %, spaces and Unicode are supported; runtime discovery uses typed asset paths to preserve their spelling.
• Edit an existing Twin .rhai asset through the source Editor: open its Twin-relative path with OpenTwinSource, edit the buffer, and persist it with SaveSourceText. Use Save & Update when the source needs to be reloaded. The save command only accepts a registered Twin and a file already open in that Editor; do not patch a loaded source file behind its buffer.
• Put a one-off mission sequence in a scenario, not a tool library. Use author-scenario.
• Put continuous control equations in Modelica and generic substrate in Rust. A missing generic typed USD, physics, projection, or solver capability is a capability report, not permission to add a model-specific Rust path.

Name the library after its reusable boundary (assembly_builder, component_requirements), and name functions by intent: *_plan, *_report, *_lint, *_test, or *_query. Avoid names that encode an implementation detail or a temporary failure.

Separate the four responsibilities

Keep these responsibilities distinct even when they live in one small file:

1. Plan — pure calculation of a typed operation list from explicit inputs. A plan must not call cmd, mutate a document, mutate ECS, or repair a failed result. It accepts the exact doc_id, edit_target, paths, and generation needed by its caller.
2. Apply — the caller sends the reviewed plan to the existing document owner, normally assembly_edit::batch or the proposal/review/commit flow. A domain tool may provide a thin apply convenience only if it still routes through that owner and exposes the acknowledgement and new generation.
3. Inspect/lint — read-only queries over composed USD or live runtime state. Return structured facts, errors, warnings, and an ok value. A lint must never hide a missing prim, invent a default, or modify the model to make itself pass.
4. Test — an authored Rhai observer that samples the live model and emits one bounded verdict. Keep component tests separate from assembly integration tests; use the shared auto_tests.rhai assertions rather than private copies.

The normal authoring shape is:

inspect exact target and generation
  -> pure component/assembly plan
  -> typed document batch or reviewed proposal
  -> projection/readback
  -> screenshot in the same headful session
  -> component lint/test
  -> assembly integration test
  -> save through the document owner

For the common post-edit checkpoint, compose the built-in editor_workflow::after_edit(doc) helper after a reviewed apply/commit. It keeps inspect, current projection, document lint, and optional authored save in one explicit result; authored autosave is disabled unless the Twin explicitly sets usd.editor_autosave = true. For physics scene evidence, compose physics_acceptance instead of adding one-off threshold code to every test. It reads existing runtime facts and leaves solver policy in Rust.

Native value boundary

Use the common engine's native Vec3/Quat values for repeated geometry, pose, and control math. They are the simulator's bevy::math::DVec3 and DQuat, registered once by lunco-scripting-rhai-world; do not define tuple/vector helpers in a tool library. world_pos3, world_forward3, and world_rotation_quat keep the hot path native, and vadd/vsub/vscale/ vcross/vdot/vlen/norm_squared/vnorm/qrot dispatch to Rust for native operands. Constructors and quaternion/Euler conversions reject non-finite or degenerate values with a script error.

Use [x, y, z]/[x, y, z, w] only when a standard USD literal, JSON command or query parameter, telemetry payload, or legacy scenario requires the interchange representation. Call vec3_array/quat_array explicitly at that boundary. The bridge accepts native vectors in cmd, query, and set and lowers them once; unknown custom values must be rejected, never stringified or changed into null. Rhai's built-in scalar math (sin, cos, exp, sqrt, atan(x, y), and related functions) is already Rust-backed, so do not shadow those names in a tool.

For reusable mechanical/CAD policy, compose assets/scripting/tools/mechanical_relations.rhai instead of adding a vehicle-specific checker. Pass native vectors and an explicit tolerance; keep the returned residual/evidence record attached to the caller's SysML requirement or verification identity. The library covers distance, coincidence, plane distance, under/clearance, parallel/perpendicular, collinear/coplanar, mirroring, and plane/axis symmetry, and remains reloadable Rhai policy.

Use the shared Rust boundary functions for dynamic values: f64_from for the permissive numeric edge, f64_only for settings that must be authored as f64, and array_is/map_is/string_is plus native vector predicates for shape checks. Use sysml_model_is, sysml_quantity_is, and sysml_enum_is for SysML wrapper values. Do not compare type_of(value) strings for ordinary numeric, array, map, string, or SysML-wrapper dispatch. Keep semantic strings for paths, qualified names, relation labels, and enum literals only.

Keep complex Rhai plans readable to the compiler as well as to reviewers. Extract long compound validation conditions and large record construction into named predicates and constructors instead of one deeply nested expression. For UsdGeomMesh edits, keep points and topology as numeric arrays until the schema boundary, then use assembly_builder::mesh_points_update_plan or assembly_builder::mesh_geometry_update_plan. These return ordinary SetAttribute operations and preserve the rest of the composed mesh contract; only the USD attribute's canonical literal is serialized as text.

Resolve a numerical profile from numerical_settings.rhai once per report or solve. Keep length, angle, scalar, time, and solver tolerances as distinct fields. A tool may use a runtime numerical setting for algorithm policy, but a normative requirement tolerance must remain sourced from SysML and appear in the evidence.

Generic parameter edits

Use assembly_builder::parameter_plan(edit_target, path, parameters) for a vehicle-independent parameter update. Each entry is { name, type_name, value }, where value is the canonical USD literal. The function only validates the exact path and unique typed fields and returns SetAttribute operations. Submit those operations with assembly_edit::batch or the proposal/review/commit flow.

The Inspector's Apply action lowers to the same ApplyUsdOps boundary. Rhai may choose which parameters to expose and validate cross-field relationships, but it must not add a second writer, infer targets by name, or encode vehicle policy in a reusable core tool. Modelica parameter meaning and lifecycle stay with the Modelica declaration/compiler; an instance override remains a USD inputs: edit.

AI-readable assembly authoring

For an exact composed prim, call assembly_builder::authoring_context(doc, path, edit_target) before planning. It returns the document generation and resolved edit target together with the prim, topology, collision envelope, exact mount sockets/occupancy, plug frames, and a small authored-affordance list. Treat every returned path and generation as a checkpoint; do not infer a socket, component, or parent from a leaf name.

Use assembly_builder::place_or_attach_plan to keep generated intent dry: attach_component returns a reviewed AttachSpec for the existing generic owner, while realign_existing_mount returns ordinary typed USD operations. After the user or agent reviews the plan, submit .spec through assembly_edit::attach_component or .ops through assembly_edit::propose/review_session/commit_proposal. Do not put this workflow in Rust or create an AI-only writer; Rhai supplies the policy and the existing USD owners supply validation and journalling.

For Editor-driven authoring, add assembly_builder::selected_authoring_context(preview) as the first discovery call. It accepts () for the focused preview or an explicit hidden preview id and fails unless exactly one current, unambiguous prim is selected. It returns the selection identity and generation alongside the normal authoring_context; do not replace those exact values with a display name. Use functional_frame_catalog(doc, edit_target, root_path) to enumerate authored functional frames and align_frames_plan(...) to compute a dry source-frame-to-target-frame placement. Keep the same-parent and rigid-stack constraints visible in the tool result, and send only the returned typed ops through the existing review/journal path.

For a reusable component recipe, compose the existing libraries with ordinary Rhai imports through component_editor::update_context or component_editor::selected_update_context. Its update_plan is a thin facade over assembly_builder::component_bundle_update_plan; keep the bundle recipe in the owning Twin/model package, return a dry plan, and let assembly_edit own proposal, review, commit, generation checks, and journalling. Do not add a Rust component registry or infer a recipe from USD child names.

Model-authoring facades

For a new assembly or scene, prefer the generic model_authoring library. It keeps the workflow in Rhai while reusing the existing typed USD owners:

• model_context(doc, root, edit_target) reads the exact composed subtree and returns paths, references, variants, components, frames, mounts, bodies, joints, colliders, ports, generation, and available actions.
• readiness_report(doc, root, edit_target, policy) combines only the checks requested for topology, physicality, mounts, connections, controls, and runtime. Missing sections are not_requested; failed lookups are errors.
• scene_recipe(doc, edit_target, recipe, parent_generation) returns dry typed USD ops for references, terrain, cameras, and initial state, plus explicit hand-offs for waypoint_editor routes and assembly_edit::attach_program programs.
• Connections source drops use the same typed program lowering and USD journal. diagram.drop.plan chooses parent/name from immutable source facts; its Rhai policy never reads source bytes or authors USD directly. Models-palette drag contracts retain explicitly declared ports. Browser .mo/.rhai drops do not infer ports; inspect InspectConnectionDiagram program facets and then author their port contract through the document tools.
• port_graph(doc, root, edit_target) discovers standard USD inputs:/outputs:/connectors: endpoints and composed connections. wiring_plan(doc, edit_target, root, connections, parent_generation) validates direction and type and returns typed SetConnection ops.
• publish_component(doc, root, edit_target, output, provenance) validates a standalone kind = "component" root, defaultPrim, schemas, references, and provenance, then returns the normal metadata ops and explicit Save-As command. Review/apply through assembly_edit; provenance remains a caller-owned manifest or standard assetInfo, not a new LunCo schema.

When testing a reusable tool or linter behavior, put the authored fixture in assets/scenes/tests/ and the observer in assets/scenarios/tests/. Exercise the production command/query surface and assert the returned facts in Rhai; do not copy a large USDA string or an observable policy assertion into a Rust unit test. Keep Rust coverage only for a generic mechanism that the public Rhai surface cannot reach.