Practical feature guide

This chapter takes you through common jobs and the choices behind them. Start with Getting started, use the module map to find the supporting capability, and consult the public reference for exact calls. Native desktop, browser and headless hosts expose different adapters; a library API does not establish that every installed application provides the same menu.

Make a project without losing the original

In Creator, open the project and use the Asset Browser to navigate, search and filter its files. Double-click or drag a model into the scene to instantiate it. The Asset inspector reports model data and references; selecting a preview is not a second editable copy of the source asset.

Import copies supported models, textures, Lua and JSON into imported/<name>/. A packaged GLB is convenient because it keeps its dependencies together. A glTF may depend on separate local buffers/images; those dependencies are copied as part of import, while parent/external dependency paths are rejected. A file that fails dependency validation should be fixed or repackaged, rather than moved around until a check is accidentally bypassed.

Use New Folder and New Lua for project files. Rename preserves the extension and updates references in the current scene, including references affected by a folder rename. Save that scene afterward. Other saved scenes are not automatically rewritten. A referenced glTF sidecar cannot be renamed independently. Move to Trash uses recoverable project .trash/ storage and refuses current scene references, dependencies and unsaved documents.

For ordinary folders, use Platinum Files. Its Trash, clipboard and spatial placement workflows differ from Creator's project asset lifecycle. An asset hash or a project-relative name identifies data; it does not grant the importer permission to access an arbitrary host file.

Source and detailed workflow: Creator project/assets, prefabs and export, thumbnail cache.

Edit, preview, apply and save

A useful working habit is to distinguish four actions:

In the Scene workspace, select an object in the hierarchy or click its model bounds. Right-drag orbits, middle-drag pans, and the wheel zooms. F frames selection; Home resets the camera. Move/Rotate/Scale tools edit the selected object, Snap quantizes changes, and inspector XYZ fields permit precise values. Stop Play before adding/removing objects or components. Save Scene / Ctrl+S saves the current scene and modified script documents; Reload reads the active scene from disk.

Play starts a runtime session from authored scene data. Stop restores authored transforms/visibility and discards transient runtime activity. Some property changes can propagate while playing, while initial-state values take effect on the next start or respawn. A running character's position, an authored spawn, and a scene-file transform are different state. Save & Restart Lua saves scripts and restarts the whole Play session, including score/runtime state. Check the Console after a script error; the session pauses rather than continuing as if the script succeeded.

For reusable custom editors, authoring_tools.rs demonstrates a hierarchy, typed inspector, timeline, graph canvas and bounded undo in a non-game application. The application validates commands before applying them. One drag should become one committed undoable gesture, rather than hundreds of per-frame history entries. Selection, zoom, scroll and graph placement may be view-local even while the underlying document is shared.

Animate a property or connect an event

Open Creator's Animation workspace and select an animation asset, or choose New Animation Asset. Add object bindings, layers, scalar tracks and keyframes. A key specifies time, an expression and outgoing interpolation: linear, smooth or step. Scrub or preview playback, then use Save + Apply to validate/write the document and refresh the presentation library. Revert reloads the saved version. Save or revert pending edits before opening another asset.

A binding supplied by a caller targets an existing object. An omitted binding with a spawn template can create a runtime object. Existing objects keep their final pose; finite runtime-spawned animation objects are removed when playback finishes or Play stops. Looping clips keep running until stopped by the session lifecycle. Do not confuse this scalar-track behavior with a skeletal rig/pose graph or with the generic authoring timeline, which supplies editing gestures rather than a complete animation engine.

The expression language is bounded arithmetic with named inputs and functions; it is not unrestricted Lua or filesystem access. For example, sin(time * 24) * strength addresses time and an input. Use explicit inputs instead of embedding application authority in an expression.

In Events, choose an object selection column and a trigger row, then click the upper cell area for Conditions or the lower area for Actions. Search, add and order actions, then Save + Apply. The important choices are what gets selected, which condition mode is used, and whether an action runs once for the system or once for each selected instance.

Selections reset for each root event. A cell without a condition can act on every available instance in its column. Inspect this carefully before using broad destructive actions. Event handling never replaces authorization at the operation that writes, connects or discloses data.

Follow Animation and Event Tables, event scopes, event metadata and the Lua guide for full controls and callbacks. The generated Event Table reference connects catalog entries to implementation evidence where an actual mapping exists.

Give a model a schema and recovery policy

A schema says which fields exist and what values are valid. Use the declared schema GUID and version; a human-readable name is an alias rather than permission or an instruction to pick the latest version. The current schema DSL is its own bounded JSON format, not the general JSON Schema standard. Unknown fields, normalization collisions and wrong values are rejected. A required integer range and a string's UTF-8 byte bound mean different things from screen character counts.

A managed BoundModel gives views a shared canonical state. Read a snapshot when updating a view; an old snapshot remains an independent value and does not update itself. Create a draft for editing, then commit against the expected revision. Schema/round-trip/conflict errors retain the draft for a deliberate retry or reconciliation. Changing a detached Lua table or Rust snapshot does not silently edit shared state.

Use the existing notes schema and Rust/Lua examples. Declare persistent model roots and choose the host's automatic/manual/off sync policy through its supported interface. Avoid assuming an unregistered Lua global, coroutine, pointer or OS handle is recoverable. Keep binary content in authorized blob resources rather than raising every structured-data bound to fit a large asset.

Undo, recovery and backup answer different questions. Undo reverses local edits within a history policy. Recovery restores covered acknowledged/checkpointed state after interruption. A backup retains an independent copy. A preview becoming visible is not a durable-save receipt. See Live Objects, tracked state, managed recovery and recoverable text saves.

Connect without silently weakening tunnel policy

Start with the actual adapter your application uses. A routing/queue library alone cannot open a socket or supply authenticated encryption. Ask the host to show the requested policy, effective global/application policy and authenticated transport result. Force Encryption on All Tunnels sets a system floor; an application's high-throughput request cannot weaken it. A peer can refuse either mode, so a refusal can be a correct result rather than a network fault. Change a policy deliberately, then reconnect; do not present a failed negotiation as a working plaintext connection.

For game deployments, Multiplayer endpoints and TLS documents the actual routes. WebTransport uses encrypted QUIC/UDP, with control/input edges on reliable streams and replaceable snapshots on datagrams. WebSocket is a separate adapter and deployment path. The native development ws:// route must not be mistaken for encrypted public play.

A locally pinned certificate join URI contains a public certificate SHA-256, not the private key. When putting that whole URI in a browser query value, encode it so the # survives as %23. A public deployment can use its trusted certificate chain; an HTTP reverse-proxy configuration does not automatically proxy a QUIC UDP endpoint. Never place private TLS keys in an export, query string or endpoint metadata.

A shared world view should attach to the chosen authoritative session, not start another independent simulation. Choose camera-follow/control permissions and audio policy explicitly: opening another view should not unexpectedly duplicate sound. Compare world session contract, and the module map for the current component boundaries.

Browser links, Back and returning to work

The following workflow is the required browser experience under WEB01–WEB10. That document explicitly specifies integration work; do not treat this section as proof that a particular deployed app has passed browser acceptance.

Use an app's normal link or named-screen navigation to move between views. A meaningful tab/filter change belongs in its permanent URL when the app supports sharing it. Copy that link or open it in another tab to request the same authorized screen. Back and Forward restore a presentation entry; they must not repeat a purchase, send, deletion or other mutation. Refresh and a direct nested link should reach the same screen after the server serves the app shell at its configured mount path. A #heading targets a section/focus position; deployments without server rewrites may offer an explicit hash-route format.

A link requests a resource. It does not bypass login or a revoked grant. After a fresh sign-in or recovery, return to the requested route only when authorized. A forbidden/missing screen must not expose a private record's title in an error. After a restored browser tab, BFCache return or reconnect, the service must validate the session again before showing protected cached content or performing an operation.

Drafts, cursor/selection and scroll can be restored under an app's bounded storage policy. Tab-local state belongs to that tab. Private caches/drafts must be scoped to the app, issuer, account and document, then removed or sealed when the account changes or access is revoked. Storage disabled, private mode, quota exhaustion or corrupted state should preserve a usable screen and an honest recovery message. Do not put tokens, passwords or recovery codes into URLs, browser history, localStorage or a diagnostic report.

The app should preserve ordinary link behavior, keyboard/IME input, password-manager/autofill semantics and meaningful unsaved-change prompts. It should reuse its loaded runtime between screens and show cancellable progress while authorized data loads. A slow response from a previous route must not overwrite your current route. These are the SDK browser acceptance requirements, including accessibility; they are not inherent guarantees of drawing a UI into a canvas.

Accounts, independent sessions and roaming

Token security is a policy for each issued session/token family. It is separate from owning software or having a grant to a document. The requested account/session experience is specified in TOK01–TOK08; deployment enforcement, key storage, recovery providers and real UI acceptance must accompany it before a release claims these options work.

An account preference supplies defaults for new sessions. An individual session can have its own policy, subject to an explicitly displayed deployment minimum. A policy change requires recent authentication and rotates/rebinds affected credentials. It cannot be implemented by changing a client-side switch alone.

Inspect the session label, creation/last-use times, policy and recent network-change events before revoking a session. Several separately authenticated devices/networks can use one account legitimately. A suspected stolen family does not imply every other family is stolen. Revoke-all is a separate explicit action or verified-policy outcome.

When blocked, complete the configured recovery flow. It should first use an already verified enrolled email, then allowed enrolled alternatives such as SMS/authenticator where appropriate. It must not send a challenge to an address supplied by the blocked request. If no safe method exists, access stays denied and the configured recovery path is shown. Successful recovery rotates/revokes the affected family and issues an appropriately bound replacement; it does not erase purchased software or documents.

Keep the identity server visible in account selection. A global Runtime account and an application's separately configured issuer/account can be different identities, even if they show the same email. Issuer, audience, subject and app scope determine which data/session applies. Signing into an app-specific server is not permission for it to read the global Runtime's profile, private caches, purchases or keys. An existing cookie or a catalog entry is not proof of current authority.

A purchase ownership record can persist while a session is revoked. Access capabilities, staff roles, sharing grants and subscription entitlements have their own revocation/expiry policies. Recovery reestablishes identity under those policies; it cannot manufacture another person's rights. See Security and the Auth/Hub owner handoffs for the release's actual provider boundaries.

Find the right next reference

For a fault report, record the app/runtime build, host/platform, exact action/error, selected provider/transport, and whether work was draft, pending, accepted or saved. Include the resource identifier only if it is safe to disclose. Redact keys, passphrases, credentials and private records. A useful report preserves evidence of failure without turning the report into a new disclosure.