Warp turns a game project into shared live state. You edit a scene or gameplay property once, and every connected editor and player receives the same narrow change without rebuilding the game or reopening the level.
\nThis guide takes you through that loop. You do not need to understand OpenUSD, ECS internals, or the content pipeline first.
\nThe fastest path is the Web Editor at warp.billrey.net/editor. It runs in a current Safari or Chrome browser and needs no installation.
\nFor a native Mac workspace, download Warp Editor from the About page. The Mac editor and web editor operate on the same hosted projects and use the same project, workspace, scene, and layer destinations.
\nTo run the engine without editing, open the browser player or install a native Warp Player. Players receive the same cooked scene and live patches as the editor viewport.
\nmain is an ordinary workspace and follows the same switching rules as every other workspace.Warp keeps the current viewport alive while switching. Content-addressed assets that are identical in the next destination remain resident; only missing or changed payloads are fetched.
\n\nA project is the durable game package. A workspace is an isolated line of changes inside that project. A scene is the authored world you open. A layer is the current OpenUSD authoring target within that scene.
Select an object in the hierarchy or viewport. The Inspector shows authored components for that object.
\nTry one of these safe edits:
\nThe editor applies the value optimistically, sends a scoped authored edit, and then reconciles with the authoritative revision. Connected players receive a compact runtime patch for the affected entities.
\nThere is no manual save step for hosted authoring. Before Warp switches to another destination, it waits for pending edits to be acknowledged so a fast switch cannot discard the latest change.
\nUse Share to open the current destination in a player or copy a link. A canonical project link can identify:
\nKeep the editor and player open side by side. Editing a supported component should update the running player in place. Asset changes stream in the background and use stable asset IDs plus content hashes to avoid unnecessary downloads.
\nCreate or select a non-main workspace when you want an isolated experiment. Other people and AI agents can work in their own workspaces without replacing your accepted project state.
\nSwitching workspaces does not mean cloning the whole project. Warp composes the selected workspace, retains matching content, rejects stale responses from the destination you left, and replaces the visible state when the new authoritative revision arrives.
\nWarp uses Lua as a small orchestration layer over its native ECS runtime. Create a script in the editor and start with a behavior:
\nreturn furry.behavior("scripts.RotatePickup", {\n writes = { "RuntimeTransform" }\n}, function(world, entity, dt, script)\n world:spin(entity, { axis = { 0, 1, 0 }, degrees_per_second = 90 })\nend)Continuous motion runs in native C++, not as a large per-frame loop in Lua. Read Lua gameplay scripting for components, native queries, physics, animation, audio, state, timers, streaming, and lifecycle APIs.
\nThe Runtime Debugger can discover a connected player for the current project, scene, and workspace. From there you can:
\nThis is useful for bugs that are difficult to describe. Instead of sending a screenshot and a list of reproduction steps, send the exact state link. See Runtime introspection.
\nChoose Open in Codex or Open in Claude Code from an editor. Warp installs the official host plugin, completes OAuth, and gives the agent authenticated project and selection context through its remote tool surface. Claude, Claude Desktop, and Cowork use the native Warp Connector. Agent mutations begin in a separate workspace and remain reviewable.
\nAgents should query context, author structured changes, validate them, and return the resulting revision and diagnostics. Read AI and automation for the complete workflow.
\nWarp clients use shared, actionable connection states. They preserve the visible scene during transient network failures and retry without pretending a rejected edit succeeded.
\nWhen reporting a reproducible runtime problem, include:
\nThat information is enough for a person, test runner, or agent to reopen the same context.
\nWarp deliberately separates authoring from runtime execution while keeping them connected by the same live project state. Editors author OpenUSD-backed changes. Players consume cooked ECS data and narrow live patches. This gives creators rich source data without forcing shipping runtimes to carry an authoring SDK.
\nWarp provides a web editor and a native Mac editor. Their presentation follows the platform, but their destination, switching, revision, validation, and live-edit behavior is shared.
\nBoth editors provide:
\nFull-screen mode keeps the 3D viewport edge to edge and moves secondary information into compact contextual controls and optional floating panels.
\nThese four scopes answer different questions:
\n| Scope | \nWhat it represents | \nExample | \n
|---|---|---|
| Project | \nThe durable game package, assets, settings, and workspace catalog. | \nMyPlatformGame | \n
| Workspace | \nAn isolated branch of authored project state. | \nmain or lighting-review | \n
| Scene | \nThe OpenUSD world currently open in the editor and player. | \nScenes/Main.usda | \n
| Layer | \nThe active OpenUSD edit target within the scene. The root layer is still a real layer. | \nScenes/Layers/Gameplay.usda | \n
main is not a special client mode. Omitting its workspace key from a public URL is only a compact-link optimization; internally it is normalized and routed like every other workspace.
Every mutation carries a complete destination: project, workspace, scene, layer, and client identity. If a switch starts while edits are pending, the shared switch coordinator waits for their acknowledgements before accepting the new destination.
\nProject and workspace switching use the same retained-view fast path:
\nThe result should feel like replacing live data, not restarting an application. A small, non-blocking status indicator may appear while changed content catches up.
\nAn editor change is first represented as a structured authored operation. The authoring service validates the operation against the current destination and revision, applies it to the correct OpenUSD layer, and exports only the runtime records affected by that edit.
\nConnected runtimes use the same cooked component format for initial load and live patches. Large payload bytes travel through content URLs or blob endpoints; control messages carry stable IDs, hashes, and small component data.
\nFor rapid transforms, Warp may stream previews more frequently than it authors durable changes. Sequence and revision guards prevent an older preview or patch from replacing a newer state. Falling behind must trigger resynchronization rather than permanently stalling a player.
\nViewport picking uses visible geometry rather than treating an object's entire bounding box as an opaque selection blocker. This permits selecting through empty space inside a large or concave bound.
\nFrame Selected and Frame All animate the camera to a computed target. Their animation must remain render-loop work; asset decode, network parsing, and stage reconciliation run away from the presentation thread wherever the platform allows it.
\nThe editor viewport can show authored state while a player runs simulation. The browser, Mac, iPad, Windows, and Linux runtime clients share the same project destination and cooked live-update model.
\nPlayers should open either:
\nThey should never invent a fallback local project. Project and workspace pickers must show one canonical current selection and allow switching back to main normally.
Use Share to copy a canonical URL or open a player. Object-aware links add the selected prim path. Review and runtime-state links add their own stable identifiers.
\nComments are anchored to scene context. When a comment is open, its viewport badge and hover preview are suppressed so the same information is not presented twice. Replies and comments can notify project members by email and include a deep link back to the context.
\nOpen Runtime Debugger to inspect the currently connected player. Read operations require project viewer access. Mutating controls such as pause, step, recording mode, and restore require editor access.
\nNormal gameplay leaves observation off. Use observe for on-demand inspection and record for a short, bounded exact-tick history. Capturing a state returns a shareable project-scoped capsule link.
\nWarp prioritizes fast optimistic interaction, but never at the expense of silently accepting the wrong state.
\nFor the stable client error contract, see Client connection states.
", "icon": "viewport", "order": 1, "searchText": "Editors and players Warp deliberately separates authoring from runtime execution while keeping them connected by the same live project state. Editors author OpenUSD-backed changes. Players consume cooked ECS data and narrow live patches. This gives creators rich source data without forcing shipping runtimes to carry an authoring SDK. Editor surfaces Warp provides a web editor and a native Mac editor. Their presentation follows the platform, but their destination, switching, revision, validation, and live-edit behavior is shared. Both editors provide: - a hierarchy for scene entities; - an Inspector for components and authored properties; - a project asset browser; - project, workspace, scene, and layer selection; - viewport selection and transform tools; - play and camera controls; - comments, review links, and sharing; - AI-agent entry points; - runtime debugging controls. Full-screen mode keeps the 3D viewport edge to edge and moves secondary information into compact contextual controls and optional floating panels. Projects, workspaces, scenes, and layers These four scopes answer different questions: Scope What it represents Example --- --- --- Project The durable game package, assets, settings, and workspace catalog. MyPlatformGame Workspace An isolated branch of authored project state. main or lighting-review Scene The OpenUSD world currently open in the editor and player. Scenes/Main.usda Layer The active OpenUSD edit target within the scene. The root layer is still a real layer. Scenes/Layers/Gameplay.usda main is not a special client mode. Omitting its workspace key from a public URL is only a compact-link optimization; internally it is normalized and routed like every other workspace. Every mutation carries a complete destination: project, workspace, scene, layer, and client identity. If a switch starts while edits are pending, the shared switch coordinator waits for their acknowledgements before accepting the new destination. Fast switching Project and workspace switching use the same retained-view fast path: 1. Keep the viewport and renderer alive. 2. Keep immutable payloads whose stable key and content hash still match. 3. Begin loading the next authoritative stage without clearing useful presentation. 4. Reject late responses from the previous switch generation. 5. Reconcile hierarchy, Inspector, viewport, and players against one accepted destination. The result should feel like replacing live data, not restarting an application. A small, non-blocking status indicator may appear while changed content catches up. Live editing An editor change is first represented as a structured authored operation. The authoring service validates the operation against the current destination and revision, applies it to the correct OpenUSD layer, and exports only the runtime records affected by that edit. Connected runtimes use the same cooked component format for initial load and live patches. Large payload bytes travel through content URLs or blob endpoints; control messages carry stable IDs, hashes, and small component data. For rapid transforms, Warp may stream previews more frequently than it authors durable changes. Sequence and revision guards prevent an older preview or patch from replacing a newer state. Falling behind must trigger resynchronization rather than permanently stalling a player. Selection and framing Viewport picking uses visible geometry rather than treating an object's entire bounding box as an opaque selection blocker. This permits selecting through empty space inside a large or concave bound. Frame Selected and Frame All animate the camera to a computed target. Their animation must remain render-loop work; asset decode, network parsing, and stage reconciliation run away from the presentation thread wherever the platform allows it. Play mode and connected players The editor viewport can show authored state while a player runs simulation. The browser, Mac, iPad, Windows, and Linux runtime clients share the same project destination and cooked live-update model. Players should open either: - the last valid remote project; or - an empty project picker when no valid remote destination exists. They should never invent a fallback local project. Project and workspace pickers must show one canonical current selection and allow switching back to main normally. Sharing and comments Use Share to copy a canonical URL or open a player. Object-aware links add the selected prim path. Review and runtime-state links add their own stable identifiers. Comments are anchored to scene context. When a comment is open, its viewport badge and hover preview are suppressed so the same information is not presented twice. Replies and comments can notify project members by email and include a deep link back to the context. Runtime debugging Open Runtime Debugger to inspect the currently connected player. Read operations require project viewer access. Mutating controls such as pause, step, recording mode, and restore require editor access. Normal gameplay leaves observation off. Use observe for on-demand inspection and record for a short, bounded exact-tick history. Capturing a state returns a shareable project-scoped capsule link. Recovery principles Warp prioritizes fast optimistic interaction, but never at the expense of silently accepting the wrong state. - A failed durable edit restores the authoritative value and explains what can be done next. - A stale response cannot update a newly selected destination. - A reconnecting player supersedes its old logical runtime instance. - A missing payload is fetched by stable ID and hash without evicting unrelated resident content. - An incomplete destination is repaired from the accepted shared scope before a mutation is sent. - Transient errors preserve the current viewport and offer retry. For the stable client error contract, see Client connection states.", "slug": "editor-and-players", "source": "docs/EDITOR_AND_PLAYERS.md", "sourceHash": "e6b311a6b541ff8d6961ad868dc6ce2a2ccaf13b5848f0c63575ef0406050ee8", "summary": "A practical guide to projects, workspaces, scenes, layers, live editing, play mode, sharing, and recovery.", "tags": [ "editor", "player", "workspace", "layers", "live updates" ], "title": "Editors and players" }, { "audience": "Game developers", "featured": true, "group": "create", "headings": [ { "id": "minimal-behavior", "level": 2, "title": "Minimal Behavior" }, { "id": "manual-module-shape", "level": 2, "title": "Manual Module Shape" }, { "id": "behavior-helper", "level": 2, "title": "Behavior Helper" }, { "id": "scene-wide-system-helper", "level": 2, "title": "Scene-wide system helper" }, { "id": "script-properties", "level": 2, "title": "Script Properties" }, { "id": "components", "level": 2, "title": "Components" }, { "id": "world-api", "level": 2, "title": "World API" }, { "id": "hierarchy-groups-and-enable-state", "level": 3, "title": "Hierarchy, groups, and enable state" }, { "id": "events", "level": 3, "title": "Events" }, { "id": "game-ui", "level": 3, "title": "Game UI" }, { "id": "entity-lifecycle", "level": 3, "title": "Entity lifecycle" }, { "id": "state-and-timers", "level": 3, "title": "State and timers" }, { "id": "local-world-and-persistent-transforms", "level": 3, "title": "Local, world, and persistent transforms" }, { "id": "animation-audio-effects-and-streaming", "level": 3, "title": "Animation, audio, effects, and streaming" }, { "id": "demo-library", "level": 2, "title": "Demo library" }, { "id": "examples", "level": 2, "title": "Examples" }, { "id": "3d-character-controller", "level": 3, "title": "3D Character Controller" }, { "id": "touch-and-tilt-controller", "level": 3, "title": "Touch And Tilt Controller" }, { "id": "one-shot-sound", "level": 3, "title": "One-Shot Sound" }, { "id": "named-animation", "level": 3, "title": "Named Animation" }, { "id": "legacy-animation-range", "level": 3, "title": "Legacy Animation Range" }, { "id": "editing-scripts", "level": 2, "title": "Editing Scripts" }, { "id": "in-the-editors", "level": 3, "title": "In The Editors" }, { "id": "vs-code", "level": 3, "title": "VS Code" }, { "id": "http-endpoints", "level": 3, "title": "HTTP Endpoints" }, { "id": "cli-agent-editing", "level": 3, "title": "CLI / Agent Editing" }, { "id": "runtime-behavior", "level": 2, "title": "Runtime Behavior" }, { "id": "guardrails", "level": 2, "title": "Guardrails" } ], "html": "Furry scripts are small sandboxed Lua system modules. They run inside the runtime ECS, not inside the authoring server, and they are meant for gameplay logic that can be hot-reloaded from the editor, VS Code, or CLI/agent tools.
\nThe API is ECS-first. A module declares its component access, queries native component storage, and queues structural changes that are committed after the current update. Lua orchestrates decisions; native C++ systems own dense iteration, physics, animation, audio, rendering, streaming, and continuous motion.
\nScripts are not native plugins. They do not get raw EnTT handles, C++ pointers, filesystem access, OS access, package loading, renderer internals, or direct USD access.
\nMost scripts should use furry.behavior:
return furry.behavior("scripts.PlayerMovement", {\n properties = {\n speed = { type = "number", default = 3.0 }\n }\n}, function(world, entity, dt, script)\n world:move_by_input(entity, script.speed or 3.0, dt)\nend)The module name is the stable script address. For v1 remote editing, modules are flat:
\nscripts.PlayerMovement -> Scripts/PlayerMovement.luaUse alphanumeric and underscore stems. Do not use slashes, traversal, nested modules, or arbitrary filesystem paths.
\nfurry.behavior returns this table shape for you, but a script may return it directly:
return {\n schema = {\n reads = { "Script", "RuntimeTransform" },\n writes = { "RuntimeTransform" }\n },\n update = function(world, dt)\n for entity, script, transform in world:view("Script", "RuntimeTransform") do\n if script.module == "scripts.LiveSpeed" then\n transform.translation_x = transform.translation_x + (script.speed or 0.0) * dt\n end\n end\n end\n}schema.reads declares components the script inspects. schema.writes declares components the script mutates. Reads and writes not declared in the schema fail with diagnostics. This explicit access model keeps dependencies visible and allows native query paths to evolve without turning Lua modules into opaque object scripts. Manual modules must declare Script when they query it. furry.behavior adds its own engine-owned Script read automatically because the wrapper uses that component to select matching entities.
furry.behavior(module, options, update_fn)options may contain:
properties: editor-visible script properties.reads: replace the user-visible default reads. The wrapper always adds its engine-owned Script read if it is not already present.writes: override default writes.Defaults:
\nreads = { "Script", "RuntimeTransform" }\nwrites = { "RuntimeTransform" }update_fn(world, entity, dt, script) is called for each entity whose Script.module matches the behavior module.
Use furry.system when a module is a system rather than an entity behavior:
return furry.system("scripts.DamageSystem", {\n reads = { "RuntimeTransform", "RenderShape" },\n writes = {},\n query = {\n all = { "RuntimeTransform", "RenderShape" },\n groups = { "damageable" }\n }\n}, function(world, dt)\n for event in world:events("damage") do\n if event.target ~= nil and world:is_in_group(event.target, "damageable") then\n local health = world:entity_state_get(event.target, "health", 3) - (event.value or 1)\n world:entity_state_set(event.target, "health", health)\n end\n end\nend)furry.system(module, options, update_fn) runs once per runtime update. Its options are:
reads and writes: required component access declarations.query: an optional native query condition; the update is skipped when it has no match.interval: an optional native timer interval for logic that need not run every frame.Modules update in stable module-name order. Structural changes and emitted events do not depend on hash-table iteration order.
\nScript component properties are authored as USD attributes named furry:prop:<name>. Lua reads them as fields on the script userdata:
local speed = script.speed or 3.0\nlocal enabled = script.enabled ~= false\nlocal label = script.label or "Player"Supported property values are currently number, bool, string, and token-like strings. script.module is read-only.
Known script-visible components:
\n| Component | \nRead | \nWrite | \nNotes | \n
|---|---|---|---|
Entity | \nyes | \nno | \nHandles expose id, path, name, parent, enabled, and enabled_self. | \n
Script | \nyes | \nno | \nmodule plus authored script properties. | \n
RuntimeTransform | \nyes | \nyes | \nFrame-local translation/scale fields; persistent transforms and continuous motion use native World commands. | \n
AudioSource | \nyes | \nyes | \nVolume, loop, autoplay; asset_id is read-only. | \n
AnimationPlayback | \nyes | \nhelper only | \nRead playback state; use the named clip, named clip subrange, or legacy range APIs to write. | \n
RuntimeUvAnimation | \nyes | \nhelper only | \nPer-instance UV transform state; use world:tween_uv so native ECS advances it and the GPU applies it. | \n
RuntimePhysicsControl | \nno direct userdata | \nhelper only | \nUse movement helpers or world:set_velocity_2d. | \n
UiText | \nquery only | \nhelper only | \nUse world:ui_set_text; native code retains and renders the result. | \n
UiLayout | \nquery only | \nhelper only | \nUse world:ui_set_visible; native code recomputes layout only when dirty. | \n
UiInteraction | \nquery only | \nhelper only | \nUse world:ui_set_enabled and world:ui_focus. | \n
Native queries can also test Name, Parent, Transform, RigidBody, RenderShape, MeshAsset, MaterialBinding, Light, Camera, RuntimeLifetime, RuntimeGroups, and RuntimeDisabled. These are query predicates, not mutable Lua objects. Add every queried component to reads or writes except the always-available Entity identity.
RuntimeTransform fields:
translation_x, translation_y, translation_zscale_x, scale_y, scale_ztranslate(x, y, z)rotation_w, rotation_x, rotation_y, rotation_zrotate(xDegrees, yDegrees, zDegrees) for a frame-local rotationAudioSource fields:
asset_id read-onlyvolumeloopautoplayAnimationPlayback is exposed as a read-only table:
start_frameend_frameframes_per_secondelapsed_secondsloopplayingclip when named-clip playback is activeclip_range_enabled, plus clip_start_frame and clip_end_frame when a named subrange is activespeedtransition_alphaRuntimeUvAnimation is exposed as a read-only table with offset, scale, rotation_degrees, elapsed_seconds, duration_seconds, and playing.
world:view(component, ...)Script, RuntimeTransform, AudioSource, and AnimationPlayback.for entity, script, transform in world:view("Script", "RuntimeTransform") do\n transform:translate(0.0, 1.0 * dt, 0.0)\nendworld:query(options)all, any, none, groups, and include_disabled.for entity in world:query({\n all = { "RuntimeTransform", "RigidBody" },\n none = { "RuntimeDisabled" },\n groups = { "enemy", "active" }\n}) do\n -- make a small number of gameplay decisions\nendworld:query_count(options) and world:query_first(options) use the same native query. world:has_component(entity, name) tests one entity. Queries are backed by EnTT component storage rather than a Lua scan of every entity; Lua is entered only for results the script chooses to iterate.
world:find_path(path)nil.world:find_name(name, root, includeDisabled)world:find_transform_overlap(root, center, halfExtents, includeDisabled)root whose world-space transform volume overlaps the supplied axis-aligned query box, or nil. Descendant discovery is cached and the hierarchy traversal, world-transform composition, and overlap test run in native C++; use this instead of recursively scanning a stable volume hierarchy in Lua every frame. Declare RuntimeTransform in reads or writes.world:parent(entity), world:children(entity, recursive, includeDisabled), and world:root(entity) navigate stable entity handles.world:reparent(entity, parentOrNil, preserveWorld) changes hierarchy after the current Lua update. preserveWorld defaults to true and cycle-forming requests are rejected.world:set_enabled(entity, enabled) changes local enable state after the current Lua update. Disabled parents disable their descendants for scripts, native simulation, physics, rendering, lights, cameras, and audio.world:is_enabled(entity, effective) reads effective hierarchical state by default; pass false to read only local state.world:add_to_group, remove_from_group, and is_in_group provide lightweight runtime grouping without adding a Lua object to every entity.Structural commands are deferred like an ECS command buffer. A query that is already being iterated is never invalidated by spawn, destroy, reparent, group, or enable operations.
\nworld:emit(name, valueOrOptions) queues a typed gameplay event. An options table may provide source, target, and a scalar value (number, boolean, or string). world:events(name, target) iterates matching events on the next update:
world:emit("damage", { source = attacker, target = victim, value = 2.0 })\n\nfor event in world:events("damage", victim) do\n -- event.name, source, target, value\nendEvents are broadcast deterministically for that update; one system does not consume an event before another system can observe it.
\nNative UI interactions emit ui.action events. event.target is the stable UI entity and event.value is the semantic action string authored on its UiInteraction component.
world:ui_set_text(entity, text)UiText in schema.writes.world:ui_set_visible(entity, visible)UiLayout in schema.writes.world:ui_set_enabled(entity, enabled)UiInteraction in schema.writes.world:ui_focus(entity)UiInteraction in schema.writes.See Game UI for the authored components and a complete example.
\nworld:input_axis()x, y. Gamepad sticks preserve their analogue magnitude after the platform radial deadzone. The combined vector is normalized only when its length exceeds one, so partial stick movement stays partial and diagonals never receive a speed boost.world:input(){ move_x, move_y, look_x, look_y, primary_down, primary_pressed, primary_released, secondary_down, secondary_pressed, secondary_released, jump_pressed }. Movement and held actions persist while active. Look deltas and pressed/released edges are consumed once by the simulation tick.world:look_delta()x, y degrees for the current simulation tick. Pointer motion, touch drags, and gamepad right-stick input use this same contract. Right-stick magnitude remains analogue and is kept separate from the movement axis.world:set_character_velocity(entity, x, y, z)world:set_linear_velocity so their authored bounce remains intact. Declare RuntimePhysicsControl in writes.world:set_character_movement(entity, { step_height, ground_snap, step_down_extra, max_slope_degrees })set_character_velocity is the recommended pattern (it then also survives runtime state restores). Declare RuntimePhysicsControl in writes.world:primary_down() / world:primary_pressed()world:tilt()x, y, z, or zeros when unavailable.world:touch(){\n active = false,\n x = 0.0,\n y = 0.0,\n axis_x = 0.0,\n axis_y = 0.0,\n delta_x = 0.0,\n delta_y = 0.0,\n tap_count = 0,\n tap_x = 0.0,\n tap_y = 0.0\n}world:jump_pressed()world:is_on_ground(entity, probeDistance)probeDistance defaults to 0.08.world:raycast(origin, direction, maxDistance, ignoreEntity)nil or { entity, position, normal, distance }. Declare RigidBody in reads.world:sweep_box(center, halfExtents, rotationDegrees, displacement, ignoreEntity)raycast, or nil. rotationDegrees is an Euler { x, y, z } orientation and displacement is the complete motion vector for the cast. Use one swept hull for vehicle or moving-volume collision prediction instead of issuing a fan of individual Lua raycasts. Declare RigidBody in reads.world:get_linear_velocity(entity) / world:get_angular_velocity(entity){ x, y, z }, or nil.world:set_linear_velocity, set_angular_velocity, apply_impulse, and
apply_angular_impulseRuntimePhysicsControl in writes. Impulses are applied once even when the renderer catches up with several fixed physics steps in one frame.world:move_by_input(entity, speed, dt)RuntimeTransform.world:move_by_input_3d(entity, speed, dt, jumpVelocity)move_by_input, but can jump and rotates the entity toward the X/Z run direction.world:move_by_input_2d(entity, speed, dt, jumpVelocity)Z = 0.world:set_velocity_2d(entity, xVelocityOrNil, yVelocityOrNil)RuntimePhysicsControl in schema.writes.world:play_animation_range(entity, startFrame, endFrame, framesPerSecond, loop)AnimationPlayback in schema.writes.world:play_animation(entity, clipName, fadeSeconds, loop, speed)AnimationPlayback in schema.writes.world:play_animation_clip_range(entity, clipName, startFrame, endFrame, fadeSeconds, loop, speed)AnimationPlayback in schema.writes.world:tween_uv(entity, options)offset={u,v}, scale={u,v}, rotation_degrees, duration, and relative. The scalar forms offset_u, offset_v, scale_u, and scale_v update one channel without disturbing a simultaneous tween on the other channel. Declare RuntimeUvAnimation in schema.writes.world:stop_uv_animation(entity, reset)true to reset the transform to identity; otherwise the last sampled UV transform remains visible.world:play_sound(assetRef, volume)assetRef may be a numeric asset id, a full asset reference path, a store URI, or a short sound name that resolves under the asset registry.world:spawn(template, options) clones an existing runtime entity. template may be an entity handle or scene path. The clone is installed after all Lua modules finish their current update, so an ECS view is never invalidated during iteration. A reserved entity handle is returned immediately and can be passed to other queued commands in the same update.
local enemy = world:spawn("/World/Templates/Enemy", {\n name = "Enemy",\n parent = world:find_path("/World/Enemies"),\n position = { 4, 0, -2 },\n rotation = { 0, 90, 0 }, -- degrees\n scale = 1.25,\n lifetime = 15.0,\n include_children = true,\n include_scripts = false\n})Scripts are not copied by default, which prevents a spawner template from accidentally recursively spawning. Spawned entities are runtime-only and are removed when play mode resets. world:spawn_effect is an alias intended for short-lived visual templates.
world:destroy(entity, recursive) safely destroys at the end of the Lua update.world:destroy_after(entity, seconds) installs a native lifetime component.world:is_alive(entity) also recognizes a spawn reserved during this update.State is held in a typed native store, survives ordinary frames and script hot reload, and resets with the game. Values are number, boolean, string, or nil.
\nworld:state_get(key, default) / state_set(key, value) are shared game state, so separate behavior modules can coordinate.world:state_add(key, delta, initial) is an atomic numeric update.world:state_toggle(key) is an atomic boolean update.world:entity_state_get(entity, key, default) / entity_state_set add entity scope.world:time() returns native simulation time.world:after(key, seconds) fires once after the key is first registered.world:every(key, seconds) fires repeatedly without a Lua delta accumulator.world:cancel_timer(key) removes either kind of timer.Timer keys must distinguish behavior instances when appropriate:
\nif world:every("spawn:" .. tostring(entity.id), 1.5) then\n -- make one orchestration decision; native systems do the continuing work\nendThe fields returned by world:view("RuntimeTransform") remain useful for a frame-local procedural offset. For persistent gameplay changes, use the World commands below. Declare RuntimeTransform in schema.writes.
world:get_transform(entity) returns the local ECS transform as { position, rotation_quaternion, scale }.world:set_transform(entity, { position, rotation, scale }) sets supplied local fields.world:get_world_transform and world:set_world_transform perform explicit hierarchy conversion while keeping component storage local.world:transform_point(entity, value, inverse) converts points between local and world space, including translation, rotation, and scale.world:transform_direction(entity, value, inverse) converts directions using world orientation without applying translation or scale.world:translate(entity, x, y, z), rotate(entity, xDeg, yDeg, zDeg), and scale_by(entity, x, y, z) persist a relative change.world:look_at(entity, target) and distance(a, b) use world-space native transform math.world:tween_transform(entity, options) interpolates in C++. Options are position, rotation, scale, duration, and easing (linear, smooth, ease_in, or ease_out).world:follow(entity, target, { offset, response, copy_rotation, local_offset, look_at }) follows in native code after physics. local_offset rotates the offset with the target, and look_at smoothly tracks the target.world:spin, orbit, ping_pong, and pulse install native motion jobs.world:stop_motion(entity) cancels those jobs without discarding the final transform.Lua should not implement a tween by adding a small amount every update. A native motion job avoids Lua calls for every moving entity and uses the same high-performance ECS path on Mac, iPad, and web.
\nFor dynamic rigid bodies, persistent translation and rotation commands are forwarded to Jolt as native position/rotation targets. A discrete scale change rebuilds the collider once. A scale tween updates the rendered scale every frame and rebuilds the collider at completion; pulse is intentionally a visual effect. Rebuilding a dynamic collision shape every animation frame would be disproportionately expensive and is not hidden behind the Lua API.
world:load_scene(sceneId) requests an asynchronous replace-mode transition using a project-relative id such as Scenes/Game.usda. The current scene remains live while the destination loads. Once its authoritative snapshot arrives, Warp atomically replaces the runtime world and unloads the previous entities, assets, UI, physics, scripts, and playing audio. If loading fails, the current scene remains visible and usable. Absolute paths, URLs, and paths containing .. are rejected so the script stays portable across players.world:pause_animation, resume_animation, and stop_animation(entity, reset) complement named and range playback.world:tween_uv(entity, options) changes UV targets only when animation commands change. Native ECS interpolates independent U/V scale, offset, and rotation channels, while the renderer applies one compact transform per instance without mutating vertices, duplicating materials, or re-uploading textures. world:stop_uv_animation(entity, reset) stops or resets it.world:set_loop_sound(key, assetRef, playing, volume) owns a named loop and prevents overlapping copies.world:preload_asset(assetRef) asynchronously schedules existing threaded mesh/audio decode or material load and pins the result.world:release_asset(assetRef) removes the script pin. It does not synchronously evict a resource that visible geometry may still use.\u00000\u0000 contains ready-to-copy examples for scene-wide ECS systems, native queries, groups/events, hierarchy and enable state, local/world transforms, native raycasts and impulses, spawning and killing objects, timed waves, typed state, streaming, motion, animation, audio, proximity triggers, and short-lived effects. The same core examples are available from the New Script example pickers in both web and Mac editors.
\nfurry.random()return furry.behavior("scripts.CharacterController3D", {\n properties = {\n speed = { type = "number", default = 3.0 },\n jumpSpeed = { type = "number", default = 6.0 }\n }\n}, function(world, entity, dt, script)\n world:move_by_input_3d(entity, script.speed or 3.0, dt, script.jumpSpeed or 6.0)\nend)return furry.behavior("scripts.TouchTiltController", {\n properties = {\n moveSpeed = { type = "number", default = 3.0 },\n tiltSpeed = { type = "number", default = 2.0 },\n tapImpulse = { type = "number", default = 0.35 }\n }\n}, function(world, entity, dt, script)\n local axisX, axisY = world:input_axis()\n local tiltX, tiltY, _ = world:tilt()\n local touch = world:touch()\n for e, s, transform in world:view("Script", "RuntimeTransform") do\n if e.id == entity.id then\n transform:translate(\n (axisX * (script.moveSpeed or 3.0) + tiltX * (script.tiltSpeed or 2.0)) * dt,\n (axisY * (script.moveSpeed or 3.0) - tiltY * (script.tiltSpeed or 2.0)) * dt,\n touch.tap_count * (script.tapImpulse or 0.35))\n end\n end\nend)return furry.behavior("scripts.SoundTest", {\n reads = { "Script" },\n writes = {}\n}, function(world, entity, dt, script)\n if world:jump_pressed() then\n world:play_sound("Jump", script.volume or 1.0)\n end\nend)return furry.behavior("scripts.GuardAnimation", {\n writes = { "AnimationPlayback" }\n}, function(world, entity, dt, script)\n if world:entity_state_get(entity, "moving", false) then\n world:play_animation(entity, "walking", 0.15, true, 1.0)\n else\n world:play_animation(entity, "idle", 0.15, true, 1.0)\n end\nend)return furry.behavior("scripts.PlayRun", {\n writes = { "RuntimeTransform", "AnimationPlayback" }\n}, function(world, entity, dt, script)\n world:play_animation_range(entity, 1, 30, 24.0, true)\nend)Both web and Mac editors create Lua files under the project Scripts/ folder and register them as script assets. Adding script examples should create the asset immediately and use the filename/module name derived from the script name.
A runnable behavior has two linked pieces: a registered project script asset, and a Script component on an entity whose module names that asset. Agent tools complete this lifecycle together. warp_write_script accepts optional targetEntities to write, register, and attach in one call. To attach an existing source without rewriting it, use a warp_apply_operations scriptWrites entry with module and targetEntities only; Warp verifies and re-registers the asset before attaching it. warp_list_scripts reports registered, attachedEntities, and lifecycleHealthy, and warp_validate rejects missing or unregistered module references.
The web editor exposes an Open in VS Code flow through the share menu. It creates a short-lived token and opens the Warp Scripts extension with a vscode:// URI.
Install the extension:
\n./tools/install_vscode_furry_scripts.shOnce connected, the VS Code side panel lists modules such as scripts.PlayerMovement. Opening a module gives a normal editable Lua document. Saving pushes the complete source back to the server.
Remote script editing is served by the web editor server:
\nGET /api/scriptsGET /api/script?module=scripts.NamePUT /api/script?module=scripts.NamePOST /api/vscode-sessionTokens are short-lived and scoped to script read/write for the current project. Modules are validated server-side and mapped only to Scripts/<Name>.lua.
For an active local editor session, prefer furry_ai:
./tools/furry_ai context\n./tools/furry_ai validateWrite or update a script:
\ncat <<'JSON' | ./tools/furry_ai write-script\n{\n "scriptWrites": [\n {\n "module": "scripts.PlayerMovement",\n "contents": "return furry.behavior(\\"scripts.PlayerMovement\\", {}, function(world, entity, dt, script)\\\\n world:move_by_input_3d(entity, script.speed or 3.0, dt, 6.0)\\\\nend)\\\\n"\n }\n ]\n}\nJSONWrite and attach a script to an entity:
\ncat <<'JSON' | ./tools/furry_ai apply\n{\n "scriptWrites": [\n {\n "module": "scripts.PlayerMovement",\n "targetEntities": ["/World/Player"],\n "contents": "return furry.behavior(\\"scripts.PlayerMovement\\", {}, function(world, entity, dt, script)\\\\n world:move_by_input_3d(entity, script.speed or 3.0, dt, 6.0)\\\\nend)\\\\n"\n }\n ]\n}\nJSONAlways validate after meaningful edits:
\n./tools/furry_ai validateFor hosted/remote projects, use tools/furry_remote:
./tools/furry_remote connect --server https://warp.billrey.net\n./tools/furry_remote scripts\n./tools/furry_remote read-script scripts.PlayerMovement\n./tools/furry_remote write-script scripts.PlayerMovement ./PlayerMovement.luaLocal Claude can be launched with a prompt that includes the remote project context and CLI commands:
\n./tools/furry_remote claude "make PlayerMovement jump on tap"FURRY_ENABLE_LUA=ON.full-demo builds enable Lua.schema.writes.schema.reads (or writes).while true do and repeat are rejected as obvious unbounded loops.require, dofile, loadfile, and collectgarbage are unavailable.Copy a file into a project's Scripts/ directory and attach its matching scripts.<FileName> module to an entity. Examples that spawn or follow objects expect the template or target paths exposed as script properties to exist in the scene.
The examples deliberately avoid per-frame Lua interpolation and large entity loops. Prefer world:tween_transform, world:follow, world:spin, world:orbit, world:ping_pong, world:pulse, world:every, and native lifetime commands for work that continues over time.
The ECS-oriented examples use a RealityKit-like split:
\nEcsDamageSystem.lua is a scene-wide system with a native component/group query and next-update events.HierarchyAndEnable.lua demonstrates deferred reparenting, groups, and hierarchical enable state.PhysicsRaycast.lua delegates ray queries and impulses to native Jolt code.WorldSpaceTransform.lua makes the local/world transform boundary explicit.ui_menu.lua handles semantic ui.action events and requests coarse text and interaction changes while native code owns layout, rendering, and input.Use furry.system for orchestration that runs once per scene update. Use furry.behavior when logic belongs to entities carrying a matching Script component. Both declare component access up front; neither should replace a native C++ system for dense per-entity work.
| Component | \nPurpose | \n
|---|---|
UiCanvas | \nReference resolution, scale matching, visibility, and draw order | \n
UiLayout | \nRow/column flow, alignment, edge-anchored absolute positioning, pixels/percent/auto sizing, padding, margin, gaps, clipping, and flex growth | \n
UiVisual | \nBackground, opacity, border, and rounded corners | \n
UiImage | \nCooked texture image with contain, cover, or stretch fitting | \n
UiText | \nText, size, color, alignment, and basic wrapping intent | \n
UiInteraction | \nNative hover, press, focus, pointer capture, and a semantic action string | \n
The layout, rendering, image residency, clipping, hit testing, pointer capture, and interaction tinting happen in C++. Lua does not run per widget or per pixel.
\nUiCanvas. Its children form that canvas's UI tree.UiLayout, UiVisual, UiText, and UiInteraction to a child entity.UiInteraction.action to a stable semantic name such as menu.play.The editor's component menu and inspector expose all of these components on web and Mac. Changes use the normal authoring transaction and appear in connected players as component-level live patches.
\nreturn {\n schema = {\n reads = {},\n writes = { "UiText", "UiLayout", "UiInteraction" },\n },\n\n update = function(world, dt)\n for event in world:events("ui.action") do\n if event.value == "menu.play" then\n world:ui_set_text(event.target, "Starting...")\n world:ui_set_enabled(event.target, false)\n end\n end\n end,\n}Open \u00000\u0000 for a ready-made responsive panel and button. \u00001\u0000 shows the matching action handler.
\nAbsolute UI can anchor to left, top, right, and bottom. Leave the opposite edge's unit as auto: for example, a fixed-size Jump button with right = 36 pixels and bottom = 40 pixels stays inside the lower-right edge at every aspect ratio. When width is auto and both left and right are set, the element stretches between those edges; height behaves the same way with top and bottom.
Keep UiCanvas.respectSafeArea enabled for player-facing UI. Native players then lay out the canvas inside platform safe-area insets, including iPad and iPhone screen edges and system UI.
The web and Mac inspectors provide a Responsive menu on every UiLayout. Use a corner preset to keep a fixed-size control attached to a safe-area edge, Stretch inside safe area for panels, or Scale bounds with screen to convert existing pixel bounds to percentages of the nearest canvas in one step. Layout remains retained: these choices do not add per-frame layout work.
Players do not add a platform-owned D-pad or Jump button. A game opts into the controls it needs by authoring ordinary UiInteraction actions. These reserved actions feed the same normalized input frame as keyboard and gamepad input:
| Action | \nGameplay input | \n
|---|---|
input.move.left / input.move.right | \nHorizontal movement axis | \n
input.move.up / input.move.down | \nVertical movement axis | \n
input.move.stick | \nRadial analogue movement from the interaction's center | \n
input.look.stick | \nRadial analogue camera look from the interaction's center | \n
input.jump | \nOne jump press when the control is first pressed | \n
input.primary / input.secondary | \nHeld and edge-triggered primary/secondary actions | \n
Controls support simultaneous pointers, so a player can hold a direction and press Jump or another action at the same time. The authored UI is rendered and hit-tested by the same retained runtime on web, macOS, iPadOS, Windows, and Linux. \u00000\u0000 contains a reusable D-pad and Jump arrangement; games can copy, restyle, remove, or replace any of its controls without changing a player app.
\nAnalogue stick interactions use the shorter layout dimension as their radial range, apply a small rescaled center deadzone, preserve partial magnitude, and keep pointer capture outside the visible base. A visual child of the stick is moved with the captured pointer, which provides a native retained-UI thumb indicator without Lua updates. input.look.stick uses the same 150-degree-per- second maximum look rate as a hardware right stick.
For touch-only controls, set UiCanvas.requireDirectTouch and UiCanvas.hideWhenGamepadConnected. The canvas then appears only on devices with a direct touch screen, disappears while a hardware game controller is connected, and returns when the controller disconnects. A Mac trackpad does not count as direct touch, so desktop players keep their keyboard controls.
Import a .ttf or .otf file into the project on web or Mac, then choose it from UiText.fontAssetPath. Warp registers it as a font asset and cooks it on the authoring side into an immutable signed-distance-field atlas, glyph metrics, Unicode lookup, and sparse kerning table. Players never parse a font program and never link OpenUSD or a font rasterizer.
The lite character set includes ASCII, Latin-1, common punctuation, and any extra ranges added by the cooker. Missing glyphs use the font's ? glyph. Complex shaping, bidirectional layout, color emoji, and variable-font axes are intentionally outside this first version.
When no custom font is assigned, Warp uses its built-in clean sans-serif SDF font. Native players package the approximately 72 KB compressed cooked atlas. The browser keeps it outside Wasm and the initial scene payload, then streams it from an immutable content-hashed URL only when the first visible label needs it. The decoded atlas is uploaded once and shared across every default label. The old pixel font is retained only as a temporary or emergency fallback while the streamed default is unavailable.
\nworld:events("ui.action")event.target is the stable UI entity and event.value is the authored action string.world:ui_set_text(entity, text)UiText.text. Declare UiText in schema.writes.world:ui_set_visible(entity, visible)UiLayout.visible and invalidates layout. Declare UiLayout in schema.writes.world:ui_set_enabled(entity, enabled)UiInteraction. Declare UiInteraction in schema.writes.world:ui_focus(entity)UiInteraction in schema.writes.Layout is retained and recomputed only after a component change, Lua UI mutation, framebuffer-size change, or safe-area change. Draw commands and hit-test order are cached. Texture payloads use the existing asynchronous decode, GPU upload, content-addressed residency, and warm-cache path. Interaction state updates only the affected draw commands instead of rebuilding the tree.
\nCustom fonts and the built-in default preserve the same contract. An unused font performs no runtime decode, upload, pipeline creation, or layout. The first visible label lazily creates its atlas and the single shared SDF pipeline. Glyph vertices are retained by a signature of the text, font, size, bounds, alignment, and color, so static labels do no layout or vertex upload per frame. Atlas residency is shared by content hash across project and workspace switches and bounded by an LRU; the cooker never repacks atlases at runtime.
\nThis first version deliberately omits scroll views, text input, localization shaping, accessibility adapters, animation timelines, and a general styling system. Those can extend the same cooked component model without replacing game UI with an editor/debug immediate-mode layer.
", "icon": "viewport", "order": 4, "searchText": "Game UI Warp UI Lite is a small retained-mode UI built into the cooked ECS runtime. Authoring uses ordinary OpenUSD component data, but players receive only compact, versioned component payloads. OpenUSD is never linked into or loaded by the runtime. What ships in the lite version Component Purpose --- --- UiCanvas Reference resolution, scale matching, visibility, and draw order UiLayout Row/column flow, alignment, edge-anchored absolute positioning, pixels/percent/auto sizing, padding, margin, gaps, clipping, and flex growth UiVisual Background, opacity, border, and rounded corners UiImage Cooked texture image with contain, cover, or stretch fitting UiText Text, size, color, alignment, and basic wrapping intent UiInteraction Native hover, press, focus, pointer capture, and a semantic action string The layout, rendering, image residency, clipping, hit testing, pointer capture, and interaction tinting happen in C++. Lua does not run per widget or per pixel. Create a simple button 1. Add an entity with UiCanvas . Its children form that canvas's UI tree. 2. Add UiLayout , UiVisual , UiText , and UiInteraction to a child entity. 3. Set its UiInteraction.action to a stable semantic name such as menu.play . 4. Handle that action in a Lua system. The editor's component menu and inspector expose all of these components on web and Mac. Changes use the normal authoring transaction and appear in connected players as component-level live patches. return { schema = { reads = {}, writes = { \"UiText\", \"UiLayout\", \"UiInteraction\" }, }, update = function(world, dt) for event in world:events(\"ui.action\") do if event.value == \"menu.play\" then world:ui set text(event.target, \"Starting...\") world:ui set enabled(event.target, false) end end end, } Open examples/ui/LiteMenu.usda for a ready-made responsive panel and button. examples/lua/ui menu.lua shows the matching action handler. Responsive edge layout Absolute UI can anchor to left , top , right , and bottom . Leave the opposite edge's unit as auto : for example, a fixed-size Jump button with right = 36 pixels and bottom = 40 pixels stays inside the lower-right edge at every aspect ratio. When width is auto and both left and right are set, the element stretches between those edges; height behaves the same way with top and bottom. Keep UiCanvas.respectSafeArea enabled for player-facing UI. Native players then lay out the canvas inside platform safe-area insets, including iPad and iPhone screen edges and system UI. The web and Mac inspectors provide a Responsive menu on every UiLayout . Use a corner preset to keep a fixed-size control attached to a safe-area edge, Stretch inside safe area for panels, or Scale bounds with screen to convert existing pixel bounds to percentages of the nearest canvas in one step. Layout remains retained: these choices do not add per-frame layout work. Authored gameplay controls Players do not add a platform-owned D-pad or Jump button. A game opts into the controls it needs by authoring ordinary UiInteraction actions. These reserved actions feed the same normalized input frame as keyboard and gamepad input: Action Gameplay input --- --- input.move.left / input.move.right Horizontal movement axis input.move.up / input.move.down Vertical movement axis input.move.stick Radial analogue movement from the interaction's center input.look.stick Radial analogue camera look from the interaction's center input.jump One jump press when the control is first pressed input.primary / input.secondary Held and edge-triggered primary/secondary actions Controls support simultaneous pointers, so a player can hold a direction and press Jump or another action at the same time. The authored UI is rendered and hit-tested by the same retained runtime on web, macOS, iPadOS, Windows, and Linux. examples/ui/TouchControls.usda contains a reusable D-pad and Jump arrangement; games can copy, restyle, remove, or replace any of its controls without changing a player app. Analogue stick interactions use the shorter layout dimension as their radial range, apply a small rescaled center deadzone, preserve partial magnitude, and keep pointer capture outside the visible base. A visual child of the stick is moved with the captured pointer, which provides a native retained-UI thumb indicator without Lua updates. input.look.stick uses the same 150-degree-per- second maximum look rate as a hardware right stick. For touch-only controls, set UiCanvas.requireDirectTouch and UiCanvas.hideWhenGamepadConnected . The canvas then appears only on devices with a direct touch screen, disappears while a hardware game controller is connected, and returns when the controller disconnects. A Mac trackpad does not count as direct touch, so desktop players keep their keyboard controls. Custom fonts Import a .ttf or .otf file into the project on web or Mac, then choose it from UiText.fontAssetPath . Warp registers it as a font asset and cooks it on the authoring side into an immutable signed-distance-field atlas, glyph metrics, Unicode lookup, and sparse kerning table. Players never parse a font program and never link OpenUSD or a font rasterizer. The lite character set includes ASCII, Latin-1, common punctuation, and any extra ranges added by the cooker. Missing glyphs use the font's ? glyph. Complex shaping, bidirectional layout, color emoji, and variable-font axes are intentionally outside this first version. When no custom font is assigned, Warp uses its built-in clean sans-serif SDF font. Native players package the approximately 72 KB compressed cooked atlas. The browser keeps it outside Wasm and the initial scene payload, then streams it from an immutable content-hashed URL only when the first visible label needs it. The decoded atlas is uploaded once and shared across every default label. The old pixel font is retained only as a temporary or emergency fallback while the streamed default is unavailable. Lua API world:events(\"ui.action\") : Iterates UI actions on the next script update. event.target is the stable UI entity and event.value is the authored action string. world:ui set text(entity, text) : Replaces UiText.text . Declare UiText in schema.writes . world:ui set visible(entity, visible) : Changes UiLayout.visible and invalidates layout. Declare UiLayout in schema.writes . world:ui set enabled(entity, enabled) : Enables or disables hit testing for UiInteraction . Declare UiInteraction in schema.writes . world:ui focus(entity) : Moves native UI focus to a focusable interaction. Declare UiInteraction in schema.writes . Performance model Layout is retained and recomputed only after a component change, Lua UI mutation, framebuffer-size change, or safe-area change. Draw commands and hit-test order are cached. Texture payloads use the existing asynchronous decode, GPU upload, content-addressed residency, and warm-cache path. Interaction state updates only the affected draw commands instead of rebuilding the tree. Custom fonts and the built-in default preserve the same contract. An unused font performs no runtime decode, upload, pipeline creation, or layout. The first visible label lazily creates its atlas and the single shared SDF pipeline. Glyph vertices are retained by a signature of the text, font, size, bounds, alignment, and color, so static labels do no layout or vertex upload per frame. Atlas residency is shared by content hash across project and workspace switches and bounded by an LRU; the cooker never repacks atlases at runtime. This first version deliberately omits scroll views, text input, localization shaping, accessibility adapters, animation timelines, and a general styling system. Those can extend the same cooked component model without replacing game UI with an editor/debug immediate-mode layer.", "slug": "game-ui", "source": "docs/GAME_UI.md", "sourceHash": "2032d5a76bea5d962242a0ec28174d9615a49cecf60361f2dfea04af99380b46", "summary": "Build responsive, cooked game interfaces with native layout, visuals, images, text, interactions, and Lua action orchestration.", "tags": [ "ui", "layout", "buttons", "text", "images", "lua" ], "title": "Game UI" }, { "audience": "Teams and agents", "featured": true, "group": "collaborate", "headings": [ { "id": "the-safe-authoring-model", "level": 2, "title": "The safe authoring model" }, { "id": "lore-as-a-remote-filesystem", "level": 3, "title": "Lore as a remote filesystem" }, { "id": "game-generation", "level": 2, "title": "Game generation" }, { "id": "prompt-to-game-quality-harness", "level": 3, "title": "Prompt-to-game quality harness" }, { "id": "mcp-workflow-self-test", "level": 3, "title": "MCP workflow self-test" }, { "id": "open-in-codex-and-claude-code", "level": 2, "title": "Open in Codex and Claude Code" }, { "id": "local-editor-automation", "level": 2, "title": "Local editor automation" }, { "id": "fail-closed-generated-data", "level": 2, "title": "Fail-closed generated data" }, { "id": "script-authoring", "level": 2, "title": "Script authoring" }, { "id": "runtime-introspection", "level": 2, "title": "Runtime introspection" }, { "id": "deterministic-scenarios", "level": 2, "title": "Deterministic scenarios" }, { "id": "deep-reproducibility-links", "level": 2, "title": "Deep reproducibility links" }, { "id": "agent-readable-documentation", "level": 2, "title": "Agent-readable documentation" } ], "html": "Warp treats agents as collaborators operating on live, structured project state. An agent should not need a screenshot-only description, a private filesystem path, or a manually reconstructed scene. It can receive the exact project, workspace, scene, layer, selection, revision, and—when needed—runtime tick.
\nThe hosted Warp project is the source of truth. Remote agents connect through Warp's authenticated MCP surface.
\nThe MCP catalog is task-oriented rather than compatibility-oriented. The normal path is warp_workspace once, one batched warp_inspect, one checked warp_change, and warp_verify. Structural mutation schemas are inline, while exact component/property contracts are requested only when needed through warp_inspect.schemas and remain fail-closed at the mutation boundary. A fresh agent does not spend turns discovering internal command names or guessing nested arguments. warp_inspect can return focused Lore workspace files, stage, asset, script, schema, Lua API, runtime, diagnosis, and diff evidence together; warp_change covers hierarchy, references, payloads, components, USD properties, layers, assets, and scripts and validates the result automatically.
The expected flow is efficient and iterative:
\nwarp_workspace.warp_inspect call.warp_change. Warp automatically creates a separate agent workspace on the first write and returns its link. Treat the returned workspace id as the change's durable destination for all later edits. An explicit warp_workspace selection always opens exactly the named workspace; use changeMode: "continue" only when deliberately resuming an existing child workspace.warp_verify with focused readback and a real input-driven playtest. Input actions advance their requested frame count while held.warp_observe for rendered evidence, then submit the final change for human review when requested.Agents cannot approve or merge their own changes. This keeps automation fast without making it invisible or irreversible.
\nAgents do not need a second project database or a complete project dump in their prompt. warp_inspect.files exposes the selected Lore workspace like a bounded remote filesystem:
list discovers project-relative files and directories, optionally with a glob;stat reads metadata for exact files;read reads exact text ranges using offset and maxBytes;search finds bounded text matches across the workspace.Every response identifies the exact Lore workspace and head. Server paths, Lore internals, derived data, cooked data, and content-addressed payload bytes are not exposed. For example:
\n{"files":{"action":"search","path":"Scripts","glob":"**/*.lua","query":"on_collision","limit":20}}This is the remote equivalent of using find, rg, and ranged file reads in a local checkout. It reads the authored Lore state directly and therefore has no separate index to become stale. Composed scene questions remain distinct: warp_inspect.stage asks OpenUSD to compose the selected scene and returns a focused semantic projection of that live result.
An agent can turn a project brief into a new hosted Warp project through the same authenticated MCP connection. This is generation of editable project data, not export of an opaque game binary.
\nThe default workflow targets a playable vertical slice, not the smallest scene that boots:
\nwarp_create_project, then select its returned scope with warp_workspace.warp_inspect request for the relevant stage, exact component schemas, assets, scripts, Lua topics, and runtime state.warp_change operations. The same call can add hierarchy, components, OpenUSD references or payloads, layers, assets, and readable Lua.warp_change, or run it with the final warp_verify. Fix failed evidence rather than assuming that a plausible scene is playable.warp_observe for correlated authored, runtime, and rendered evidence. Refine until the result works visually and behaviorally.warp_apply_game_spec compiles named entities into ordinary OpenUSD prims, inspector-visible Warp components, project assets, and readable Lua modules. The result appears in the hierarchy and Assets pane and can be selected, moved, duplicated, reparented, restyled, rescripted, layered, reviewed, or edited by another person or agent. WarpGameSpec is an input recipe and audit artifact; it never replaces the authored OpenUSD scene as the source of truth.
The repository's internal bulk-generation contract lives at docs/schemas/warp-game-spec-v1.schema.json. Its specific game fixture exists only to regression-test the generic compiler and is never returned as agent guidance or used as an authoring template. Remote agents do not need that compatibility surface: they use the same typed warp_change operations as ordinary edits and the exact scenario schema exposed by warp_verify.
The quality preflight is expressed through focused warp_inspect evidence followed by warp_verify. It has no pre-authored mechanics, project-specific entity assumptions, or genre templates. A playable result requires:
Use draft only for intentionally minimal experiments. The polished target additionally requires intentional presentation, typed runtime inspection evidence, reusable architecture where meaningful repetition exists, and final rendered evidence. A playtest without a scenario is marked structuralOnly; it proves that cooking succeeds and entities exist, not that the requested behavior works.
For any repeated authored hierarchy, use warp_change.operations.repeatedSubtrees. Each entry contains one arbitrary typed compact-entity subtree and any number of named transform placements. Warp stores the definition once in a private USD namespace and authors internal OpenUSD references at the requested scene paths; the private definition never appears as a runtime entity or hierarchy row. instanceable is optional and defaults to false so descendants remain editable. This contract is general rather than tied to any particular asset or game concept. Use runtime world:spawn only for copies whose lifecycle begins during play.
For repeated art already stored in a project USD asset, keep runtime roots, physics, and scripts local while placing shared visuals with project-relative referenceURI values and an optional exact referencePrimPath. When iterating on shared art, begin the upload with replaceExisting: true; Warp preserves the stable sanitized filename instead of silently creating a numbered replacement, so all references continue to point at one source of truth.
The visual player pass still matters. Headless tests cannot identify camera jitter, z-fighting, overlapping ground surfaces, illegible type, poor composition, or weak feedback. Use warp_observe with includeFrame: true. It waits for correlated authored/runtime evidence and returns the actual Sokol player canvas as an MCP image/png content block when a player is connected. Inspect the image and its revision, tick, dimensions, and asset-readiness metadata; correct visible problems and observe again. A successful generation remains ready-for-visual-review until this pass is healthy, after which it can be submitted with warp_submit_for_review.
A single frame proves rendered composition, not motion over time. Use deterministic playtests and typed runtime inspection for behavior, and take frames before and after important states when motion or feedback must be checked. An asset wait timeout is reported explicitly in capture metadata instead of being mistaken for a fully loaded frame. Camera smoothing should be deterministic and frame-rate independent, and adjacent surfaces should share deliberate topology rather than overlap coplanar meshes.
\ntools/self_test_warp_mcp.py drives a running Warp server through the whole ordinary agent workflow over the real /mcp HTTP endpoint: mint an agent session, open an explicit scope, switch scenes, read the composed asset catalog, upload a sound, create a scene inside the isolated agent workspace, apply prim/component operations including an asset reference, read the stage back, write and attach a Lua script, validate, run a headless playtest, and read the change diff. Every mutation stays inside a dedicated scratch project (McpSelfTest by default) and an isolated Lore agent workspace, so it is safe to run against a production server.
# Against a local server without auth:\ntools/self_test_warp_mcp.py --server http://127.0.0.1:8765\n\n# Against the hosted server (guest or user credentials mint the agent session):\ntools/self_test_warp_mcp.py --server https://warp.billrey.net \\\n --login-email "$WARP_AUTH_GUEST_EMAIL" --login-password "$WARP_AUTH_GUEST_PASSWORD"Run it after every server deploy. It exits non-zero when any ordinary operation regresses — including the historical failure classes it encodes as explicit regression checks: a scene created in an agent workspace must remain visible and editable through warp_change, and project assets inherited through the Lore parent chain must stay visible through warp_inspect.assets from every scene. The offline contract checks in tools/check_warp_agent_contracts.py (which also run the --self-test-mcp-* suites built into the server binary) complement it and need no running server.
Every project-scoped MCP response includes resultLocation with the effective projectId, workspaceId, sceneId, and a directly usable editorUrl. This is the authoritative destination after Warp rewrites a base-workspace request into an isolated Lore change workspace. Agents must name that workspace and include the link when reporting authored work; they must never infer the destination from an earlier prompt or silently describe a different workspace.
Choose Open in Codex or Open in Claude Code from either editor. The action installs or updates the official Warp plugin, completes OAuth, verifies the trusted connection, then opens the selected agent surface with project context available through normal agent tools.
\nThe connection is configuration, not prompt text. You should not have to paste server tokens, project paths, or setup instructions into every task.
\nWarp has one endpoint: https://warp.billrey.net/mcp. Claude Code and Codex install it only through the official Warp plugin. Claude, Claude Desktop, and Cowork use the native Warp Connector backed by the same endpoint. Warp never advertises or silently creates a direct CLI registration.
The installation surfaces are deliberately distinct: /connect/claude-code installs the Claude Code plugin, /connect/codex installs the Codex plugin, and /connect/claude opens the native Connector path. These are human setup pages, never MCP server addresses.
An already-running agent task has a fixed tool list and cannot discover an MCP server added halfway through that task. Open in Codex and Open in Claude Code avoid making the user recover from that client limitation: Warp installs and authenticates out of process, then opens a fresh task with the tools already loaded. When setup is run manually from Terminal or from inside an existing agent conversation, open one new task after the command succeeds. No app restart, configuration editing, or repeated /mcp retry is required. Never hand-edit .mcp.json or add the endpoint with an MCP CLI command. Plugin setup preserves unrelated MCP entries and only migrates a stale entry after it has verified that the entry belongs to Warp.
Codex setup also stores default_tools_approval_mode = "approve" on the permanent warp server entry. This is required for codex exec and other non-interactive sessions: otherwise Codex cannot surface an MCP write approval and reports the automatic rejection as if the user cancelled it. The trust is narrowly attached to the immutable Warp connection URL. Warp still creates all agent mutations in a separate Lore child workspace, retains revision history, and does not expose an agent tool that can approve or merge its own review. This allows ordinary authoring without weakening the shell or filesystem sandbox and without using --dangerously-bypass-approvals-and-sandbox.
Claude Code shows its normal first-use tool approval in interactive sessions. For a non-interactive claude -p acceptance run, scope the allow rule to the connected Warp plugin with --allowedTools 'mcp__plugin_warp_warp__*'. That wildcard keeps local shell and file tools unavailable while allowing the complete Warp toolset to evolve without a brittle hand-maintained list of MCP method names.
After authentication, call warp_workspace. With no ids it returns the accessible project catalog. With exact project, workspace, and scene ids it selects the scope and returns readiness in the same call. Its setup block reports whether project binding, the composed OpenUSD stage, authoring backend, Lua contract, and Lore review isolation are ready.
Scenes are first-class OpenUSD documents in a Lore workspace. Each workspace entry in the warp_workspace catalog includes every composed scene visible there, including scenes created only in a Lore child workspace. Every scene record returns exact sceneId, referenceURI, payloadURI, and luaSceneId values. Create or duplicate one with idempotent warp_create_scene, then select the returned exact scope with warp_workspace. warp_create_scene.contents can instead create a complete USDA document; Warp validates it before advancing the Lore workspace head. Use a returned referenceURI or payloadURI in a warp_change prim operation to compose one workspace-visible document into another. These are stable project ids, never server filesystem paths. In compact agent sessions, request scenes: {} through warp_inspect to get the complete scene catalog for the selected workspace without depending on the bounded project overview. The compatibility warp_list_scenes tool returns the same workspace-native scene identities.
Ordinary hierarchy and composition work uses the fail-closed primOps and layerOps variants on warp_change.operations. primOps supports add, delete, duplicate, reparent, references, and payloads; reference and payload targets must be project-relative ids returned by Warp. layerOps supports add, remove, reorder, mute, active target, clear, merge down, and complete USDA import. Import is the native OpenUSD escape hatch for variants, inherits, specializes, relationships, and other declarative composition while still being parsed and project-scope validated by OpenUSD.
Project assets are discoverable through warp_inspect.assets. This queries the composed Warp project asset catalog for the exact project/workspace. The catalog follows Lore inheritance and is available from every scene; it is not the same thing as the raw authored-file access in warp_inspect.files. The result covers meshes, textures, sounds, animations, scripts, materials, and fonts and returns stable asset ids, /World/FurryAssets/... paths, short names, and exact component/Lua reference forms. A scene component such as AudioSource or MeshAsset is a usage of an asset, not proof that the asset exists. Agents must query this catalog before guessing a reference or uploading, and must not re-upload an asset merely because no scene object currently uses it.
The finish phase of warp_upload_asset returns the stable Warp asset identity immediately while preview generation and cooking continue in the background. The asset is immediately discoverable through warp_inspect.assets by that id or path. Asset payloads remain content-addressed and on-demand; neither catalog inspection nor scene authoring reads raw server files into the agent context.
The same resumable upload path accepts a complete ZIP project tree for rich OpenUSD imports. Set projectTreeRoot to a portable destination under Assets/, entryUsd to the archive-relative composition entry point, and optionally entryPrimPath, parentPath, and primName. Warp validates every archive path, rejects traversal and symlink entries, installs the tree atomically in the isolated Lore workspace, and retains all authored sublayers, references, payloads, materials, textures, and relative paths. It returns the portable entry sourceURI; when parentPath is supplied it also authors the open composition reference. Ordinary single assets and composition trees use this one upload mechanism rather than separate overlapping import systems.
warp_inspect.stage returns compact composed prim summaries by default. They retain paths, component values, and short scalar attributes while omitting mesh arrays and verbose provenance that would crowd out the actual authoring task. An exact path returns that prim alone; request includeDescendants: true only when the whole subtree is relevant. Use includeDetails only for focused follow-up inspection. Broad /World queries are deliberately capped and return a query hint so the agent continues with focused subsets instead of spilling a scene dump into a local file or exhausting its model context.
Before authoring an unfamiliar component, include it in warp_inspect.schemas. It reads the same closed-world component rule table used at Warp's mutation boundary and returns exact property names, scalar/vector channels, vector arities, ranges, and enum values. When those components already occur in the selected stage, it also includes the editor metadata and a bounded set of example paths. This is a discovery surface over the enforced contract, not a second permissive schema.
Codex app, Codex CLI, the Codex IDE extension, and supported ChatGPT desktop workflows can use the same remote MCP configuration. Hosted ChatGPT workspaces use the Warp plugin backed by that same MCP server rather than reading local desktop configuration.
\nWhen a local editor is running, it writes the active authoring session to .derived/furry_ai_session.json. The repository wrapper discovers the active scene, address, author, workspace, and server:
./tools/furry_ai context\n./tools/furry_ai validateApply ordinary entity and component edits as structured JSON:
\ncat <<'JSON' | ./tools/furry_ai apply\n{\n "componentOps": [\n {\n "op": "set",\n "entity": "/World/Player",\n "component": "Transform",\n "data": {\n "translation": [0, 2, 0]\n }\n }\n ],\n "notes": "Raise the player spawn point"\n}\nJSON\n\n./tools/furry_ai validateStructured authoring preserves destination scope, live updates, revision checks, undo/history, and actionable diagnostics. Directly editing USD text bypasses those guarantees and is not the normal agent path.
\nThe hosted MCP surface uses the same component operation contract. For example, this sets a child attachment one metre above its parent in local space:
\n{\n "componentOps": [{\n "kind": "set",\n "entityPath": "/World/Parent/Child",\n "componentType": "Transform",\n "propertyName": "translation",\n "values": [0, 1, 0]\n }]\n}Use componentOps for inspector-visible data. Reserve usdPropertyOps for native OpenUSD properties that do not belong to a Warp component schema.
WarpGameSpec is a closed-world authoring contract, not a bag of suggestive JSON fields. The published schema declares the supported entity fields, component names, component-specific property names and value shapes, asset operations, and action-specific playtest fields. The server repeats the semantic checks at the mutation boundary and rejects the entire specification before producing any authoring operations when it finds:
Diagnostics include the exact JSON path, such as spec.scene.entities[2].components[0].properties[1].values. Schema validation is useful for editor completion and early feedback, but it is never trusted as the mutation guard: warp_change, project generation, and warp_verify playtests all pass through the server-side semantic validator. Invalid input cannot partially create layers, prims, assets, or scripts.
Use warp_inspect.schemas for exact component contracts and the inline warp_verify.scenario schema for exact playtest actions. This keeps an agent from relying on plausible names that the running engine does not implement.
Create and attach Lua modules through the same structured change path. Lua should make coarse gameplay decisions; native engine systems own dense queries, continuous motion, physics, animation, audio, rendering, streaming, timers, and lifetime.
\nFor remote MCP work, prefer one complete lifecycle operation: include a warp_change.operations.scriptWrites entry with module, contents, and targetEntities. Warp validates the source, registers the script asset, and attaches Script.module to the targets before reporting success. An attach-only scriptWrites entry omits source and supplies module plus targetEntities; the server verifies and re-registers the existing asset without rewriting it. furry.behavior automatically declares the internal Script read that its module-selection wrapper needs, so agents only declare the components their own behavior reads or writes.
cat <<'JSON' | ./tools/furry_ai write-script\n{\n "scriptWrites": [\n {\n "module": "scripts.OpenDoor",\n "targetEntities": ["/World/Door"],\n "contents": "return furry.behavior(\\"scripts.OpenDoor\\", { writes = { \\"RuntimeTransform\\" } }, function(world, entity, dt, script) world:tween_transform(entity, { position = { 0, 3, 0 }, duration = 0.4, easing = \\"smooth\\" }) end)\\n"\n }\n ]\n}\nJSONRead Lua gameplay scripting for the verified runtime API.
\nAuthoring context explains what the scene should be. Runtime inspection explains what the game is doing now.
\nAgents and test runners can:
\nwarp_profile_runtime, receiving compact frame percentiles and hotspots plus a Perfetto-compatible artifact;warp_diagnose;warp_observe;./tools/furry_ai runtime-list\n./tools/furry_ai runtime-query --runtime PLAYER_ID --input query.json\n./tools/furry_ai runtime-pause --runtime PLAYER_ID\n./tools/furry_ai runtime-step --runtime PLAYER_ID --input '{"steps":1}'\n./tools/furry_ai runtime-capture --runtime PLAYER_ID --output failure.warpcap\n./tools/furry_ai runtime-restore --runtime PLAYER_ID --capsule failure.warpcapState Capsules are versioned and project-scoped. Normal capsules reference immutable cooked assets by content hash rather than copying large payloads. Restore is transactional and fails closed on incompatible or malformed state.
\nFor the normal remote-agent loop, prefer warp_observe over manually joining several unrelated responses. One call returns focused composed prims and validation at an authored revision, matching live runtime state and tick when a player is connected, and an optional real Sokol frame. The consistency block states whether every requested source reached targetRevision; a concurrent edit that advances the scope high-water mark makes the evidence explicitly not ready instead of producing a misleading mixed snapshot.
Every observation has a content-stable evidenceId. Pass it back as compareToEvidenceId after a mutation to receive bounded semantic changes for authored prim/component/property fields and runtime entity/component fields, plus revision and tick deltas. Evidence is retained in memory for one hour, bounded to 128 records, and comparison is allowed only for the same authenticated profile, project, workspace, and scene. The focused stage and runtime filters must also match; otherwise Warp refuses the semantic comparison instead of misreporting omitted records as deletions.
Headless scenarios run the native ECS, Lua, and physics systems without rendering. They can drive ticks and input, pause or step, assert entity/component state, and emit JSON plus JUnit reports.
\nbuild/full-demo/furry_runtime_headless \\\n --snapshot .derived/cooked/scene.bin \\\n --scenario examples/runtime/basic_state.warptest.json \\\n --report .derived/test-results/basic-state.json \\\n --junit .derived/test-results/basic-state.xml \\\n --failure-capsule .derived/test-results/basic-state.warpcapA failed scenario can save the exact restorable runtime state. That turns “it failed once on an iPad” into a deterministic artifact an agent can inspect locally.
\nAn inspect scenario action is deliberately non-assertive: it returns the matching hierarchy, authored components, runtime components, Lua state, and physics values at that tick. This supports discovery and self-correction when an agent does not yet know the right expected value. After inspecting, the agent applies a minimal authored correction and reruns warp_verify until it reports healthy state.
warp_inspect.diagnose is compact by default: it returns validation, authored-stage counts, runtime health, issues, and next actions without copying the complete composed stage into the model context. Pass a focused path/prefix/search (or explicitly request stage details) only when the diagnosis needs prim-level evidence, and otherwise use warp_inspect.stage for the implicated objects.
A strong issue or review link should carry as much stable context as necessary:
\n/p/PROJECT/state/CAPSULE?s=Scenes%2FMain.usda&w=playtest&o=%2FWorld%2FPlayerOpening the link loads the project destination, waits for a matching runtime, restores the capsule, selects the object, and exposes Runtime Debugger. Read Deep links and Runtime introspection for the wire and compatibility contracts.
\nThe public documentation is generated from versioned Markdown and a strict catalog. Automation can consume:
\n/docs/manifest.json for structured article metadata, rendered content, headings, source hashes, and API verification;/docs/llms.txt for a compact documentation map;/docs/llms-full.txt for the complete source corpus.The generator compares the documented Lua surface with the World methods exported by LuaScriptSystem.cpp. A missing method makes documentation validation fail instead of silently publishing a stale reference.
Warp links identify projects with a stable opaque ID stored in the project package's project.json. The ID moves with the package, so routing does not depend on the server's filesystem layout.
Canonical links use:
\nhttps://warp.example.com/p/7Kq2mP9vDx4NcR8B\nhttps://warp.example.com/p/7Kq2mP9vDx4NcR8B?s=Scenes/Level2.usda&w=playtest&o=/World/Player\nhttps://warp.example.com/p/7Kq2mP9vDx4NcR8B/r/review-id\nwarp-player://connect?p=7Kq2mP9vDx4NcR8B&server=https%3A%2F%2Fwarp.example.com&w=playtestThe compact keys are:
\np: project IDs: project-relative scenew: workspaceo: selected object pathThe project manifest's main scene and the main workspace are implicit, so canonical links omit s and w for that default scope. A link to Main is therefore normally just /p/<project-id>, with o added only when it needs to select a specific object.
The origin names the deployment, while everything after it is portable. Moving a project package to another server preserves its ID and therefore the route; keeping the public hostname or redirecting the old hostname preserves existing absolute web URLs.
\nExisting links using projectRoot, absolute scene, workspace, ws, path, or select remain readable. Once loaded, the web editor replaces them in browser history with the canonical compact route. Native players resolve portable app links through the server's authenticated /api/deep-link endpoint, and only send credentials scoped to that server.
warp-player:// targets the installed player explicitly. Existing warp:// and furry:// links remain readable for compatibility.
off is the production default. No history is captured.observe enables live queries and on-demand capture without retaining history.record retains an exact, bounded, every-tick history. Asset payloads are content-addressed and retained once rather than copied into every frame. The default memory budget is 128 MiB.State frames contain the authored entity/component snapshot plus native runtime components, Lua-owned world/entity values, Lua timers and random states, current input, physics body transforms and velocities, simulation clocks, pause state, world settings, and referenced cooked assets. Capsules include a format version, engine build, platform, UTC creation time, project/workspace/scene identity, revision, and tick. Normal captures contain content-addressed references to immutable cooked assets instead of recopying their bytes; restoring first loads the project and resolves matching hashes from its payload/cache layer. The C++ API can still request an embedded-asset capsule for deliberately self-contained export.
\nRaw Lua VM memory, graphics-driver objects, sockets, audio device buffers, and other process-local handles are deliberately excluded. Their durable native state is captured and the subsystem rebuilds those handles on restore.
\nThe web editor's Runtime Debugger button discovers runtimes connected to the current project, scene, and workspace. It can inspect a path prefix, pause/resume, single-step, enable bounded recording, and capture a capsule. Capture returns a shareable link such as:
\nhttps://warp.billrey.net/p/PROJECT/state/sha256%3A...?...&s=Scenes%2FMain.usda&w=featureOpening that link loads the correct scope, waits for the retained web viewport to register, restores the capsule directly into that local viewport, pauses it, and selects the inspected entity. The experimental Runtime Debugger stays closed unless the user opens it from the menu. The macOS editor exposes the same debugging operations in its Debug menu; query JSON and captured deep links are copied to the clipboard.
\nThe transport uses the player's existing outbound authenticated gRPC stream. Players do not open inbound ports. Read-only queries and capsule capture/fetch require the project viewer role. Remotely controlling another runtime requires editor access; opening a QA link restores only into the local player and does not use that mutation endpoint.
\nWeb, Mac, iPad/iPhone, and Windows players expose Deep State Link and Mark Issue from their … or File menu. Both actions capture a State Capsule only when invoked. Deep State Link puts the canonical URL on the clipboard. Mark Issue hands that same portable URL to the platform share sheet, or copies it when no share sheet is available, so it can be pasted into Jira, GitHub, Slack, or another system.
Players also expose Copy Project Link plus one Open Link field. The project link identifies the current project, scene, and non-main workspace without capturing runtime state. The same Open Link field accepts those normal project/workspace URLs and Deep State Links; opening a Deep State Link additionally restores and pauses the captured runtime capsule. In a browser, the address bar provides the equivalent open-link flow.
Warp deliberately does not create an issue, comment, ticket, replay window, or tracker-specific record. The content-addressed capsule and its URL are the portable repro artifact.
\nOpening the URL resolves the project/workspace/scene, fetches the immutable capsule, restores it transactionally into the local player that opened it, pauses at the captured tick, and restores the captured runtime camera plus any inspect/selection context carried by the link. It never authors the workspace and cannot change another running player.
\nStart the normal editor so .derived/furry_ai_session.json exists, then use the shared wrapper:
./tools/furry_ai runtime-list\n./tools/furry_ai runtime-schema --runtime PLAYER_ID\n./tools/furry_ai runtime-query --runtime PLAYER_ID --input query.json\n./tools/furry_ai runtime-pause --runtime PLAYER_ID\n./tools/furry_ai runtime-step --runtime PLAYER_ID --input '{"steps":1}'\n./tools/furry_ai runtime-record --runtime PLAYER_ID\n./tools/furry_ai runtime-at-tick --runtime PLAYER_ID --input '{"tick":240}'\n./tools/furry_ai runtime-capture --runtime PLAYER_ID --output failure.warpcap\n./tools/furry_ai runtime-restore --runtime PLAYER_ID --capsule failure.warpcap\n./tools/furry_ai runtime-resume --runtime PLAYER_ID\n./tools/furry_ai runtime-off --runtime PLAYER_IDruntime-query accepts pathPrefix, string entityIds, components, includeDisabled, and maxEntities. Results contain stable entity and parent IDs plus typed, versioned runtime component values. If only one matching runtime is connected, --runtime may be omitted.
On capture the CLI writes a local .warpcap, stores the same bytes in the project's content-addressed mirror, and prints the content key, URL, and canonical deep link. Restore only accepts the explicit capsule file supplied by the caller and expects the matching project content to be loaded.
Run the same native ECS, Lua, and physics systems without rendering:
\nbuild/full-demo/furry_runtime_headless \\\n --snapshot .derived/cooked/scene.bin \\\n --scenario examples/runtime/basic_state.warptest.json \\\n --report .derived/test-results/basic-state.json \\\n --junit .derived/test-results/basic-state.xml \\\n --failure-capsule .derived/test-results/basic-state.warpcapActions are tick/wait, input, pause, resume, step, inspect, and assert. An inspect action returns a typed observation at that exact point in the scenario, filtered by path and component names. Every assertion uses action: "assert"; aliases such as assertState and assertTransform are rejected. Assertions can check entity existence, enabled state, translation, scale, required runtime components, revision, exact tick, exact typed Lua world state with stateKey plus stateEquals, or a numeric lower bound with stateNumberAtLeast. A failed assertion emits JSON/JUnit diagnostics and an exact restorable failure capsule.
Hosted playtests use an action-discriminated, fail-closed contract. Each action accepts only the fields that its runtime implementation consumes; unknown actions and ignored-looking extra fields are rejected. Assertions must contain at least one predicate, entity predicates require a path, vectors have exact arities, and numeric limits are checked before the runtime starts. This keeps a plausible-looking scenario from being reported as meaningful evidence when the runtime would have ignored part of it.
\n{\n "action": "inspect",\n "label": "player-after-acceleration",\n "path": "/World/Player",\n "components": ["RuntimeTransform", "RigidBody"],\n "includeDisabled": true,\n "maxEntities": 16\n}Scenario JSON reports include an observations array. Each observation contains the action index, label, revision, tick, input, Lua state, matching hierarchy, authored components, derived runtime components, and selected physics bodies. This lets an agent inspect evidence before and after an interaction rather than guessing which assertion to write first.
The hosted MCP bridge exposes the same state without SSH:
\nwarp_inspect_project validates and filters the composed editable OpenUSD stage;warp_list_assets queries the composed Lore-backed project asset catalog and returns stable, copy-safe references for every supported asset kind from every scene without exposing raw project files;warp_list_runtimes discovers players attached to the exact project, workspace, and scene;warp_runtime_schema describes typed inspectable runtime components;warp_query_runtime returns live ECS, Lua, physics, input, tick, and revision state;warp_profile_runtime controls one bounded, portable performance capture and returns a compact summary plus a content-addressed trace;warp_diagnose combines authored validation with live runtime evidence and actionable issues;warp_describe_schema exposes the exact fail-closed authored component/property contract;warp_observe captures one revision-correlated authored/runtime/render evidence bundle and compares it with a prior evidence id;warp_run_playtest accepts inspect actions for deterministic headless evidence when no player is connected.warp_capture_player_frame returns the actual canvas of a connected web Sokol player as an MCP PNG image, scoped to the exact project, workspace, scene, and minimum revision.Agents should normally repeat observe -> edit -> observe with compareToEvidenceId -> playtest until consistency.ready is true and the semantic delta matches the requested change. warp_observe records authored revision, runtime revision/tick, optional rendered-frame revision, and the ending scope high-water mark. If another edit lands during capture, the evidence remains inspectable but is marked not ready rather than silently joining mismatched states. Focused query and diagnose tools remain available for follow-up detail. Inspection is read-only and never publishes editor selection or scene mutations.
Warp emits semantic frame, simulation, Lua, physics, rendering, GPU, asset, live-update, network, audio, and runtime events into industry-standard profiler paths. The native recorder is dormant until armed. A disabled event costs one relaxed atomic check; Apple signposts and Windows ETW use their platform enabled checks, so there is no background trace serialization, polling, or file I/O.
\nFor human profiling on Mac, open Apple Instruments, select the running Warp Player process, choose the standard Game Performance, Time Profiler, Metal System Trace, Allocations, or another template, and record normally. Attach Xcode's Metal debugger to Warp Player when a GPU frame capture is needed. Warp does not duplicate those controls inside the player. Portable captures are reserved for MCP and automation, use Chrome Trace Event JSON, and open directly in Perfetto. Sokol render passes carry GPU debug-group names, so Metal and PIX captures identify scene, shadow, selection, ambient-occlusion, and display work instead of anonymous command buffers.
\nRemote agents use exactly one MCP tool, warp_profile_runtime, against an explicitly selected runtime:
action: "capabilities" reports the runtime's native and portable backends.action: "start" arms a bounded capture; optional categories and maxEvents keep evidence focused.action: "mark" adds a revision/tick-correlated point before or after a suspected interaction.action: "stop" returns frame average/p95/p99/max, over-budget counts, top CPU hotspots, dropped-event count, and a content-addressed Perfetto trace URL.Profiling never authors or merges project data and never creates an agent workspace. Every event carries the current project, workspace, scene, runtime, authored revision, simulation tick, and frame where applicable, allowing profiler evidence to line up with warp_observe, State Capsules, and review history.
Mac release packaging also emits a sibling *-symbols.zip containing UUID-matched dSYMs and a UUIDs.txt manifest. Retain this artifact with each shipped build so Instruments recordings and crash reports remain symbolizable after a newer player is released.
Evidence ids are content-stable within the exact authenticated project scope. The server retains at most 128 records for one hour and rejects comparisons across profiles, projects, workspaces, or scenes. Semantic comparison is bounded and keyed by prim path or stable runtime entity identity, so an agent receives changed component/property fields instead of a second complete scene dump. The normalized path/component/runtime filters must match the baseline; different filters produce an explicit non-comparable result rather than false additions or deletions.
\nUse warp_open_player to obtain the current agent-workspace player link, then call warp_capture_player_frame while that web Sokol player is connected. Frame capture is revision-scoped: by default it rejects stale rendered state, waits up to five seconds for streamed mesh payloads, settles two additional frames, and returns both an MCP image/png block and structured metadata. The metadata includes runtime identity, project/workspace/scene, revision, tick, renderer, dimensions, byte length, and whether assets were ready or the wait timed out. The same PNG is stored in the project's content-addressed store and returned with its immutable content key and URL.
This is visual evidence from the real Sokol render target, not a reconstruction from scene data or renderer statistics. It currently requires a connected web Sokol player; if none is available, the tool returns an actionable error instead of claiming visual success. One frame is not a substitute for deterministic scenarios or runtime inspection, so behavior and motion should use typed evidence and multiple captures where appropriate.
\nCapsule decoding is fail-closed on unknown format versions, malformed/trailing bytes, or unknown serialized Lua values. Restore is transactional from the caller's perspective: errors are returned as actionable messages and never reported as success. The renderer rejects a capsule from another project or workspace. Scene routing is enforced by runtime discovery and command targeting, while the capsule's scene metadata remains diagnostic so the same project state can move between native and web path conventions.
\nAll entity references use stable 64-bit IDs. IDs are represented as JSON strings so browser clients do not lose precision. Runtime component payloads carry independent versions to permit future component migrations without changing the whole capsule format.
\nQueries, QA links, State Capsules, rendered frame captures, and portable performance traces are on-demand. The player QA controls add no frame-loop polling, serialization, copying, traversal, history, locking, or bookkeeping while idle. A rendered capture waits and encodes PNG data only for the targeted QA request. Runtime recording is explicitly opt-in and bounded by bytes; performance tracing is explicitly opt-in and bounded by event count. Recorded asset payloads are deduplicated by stable asset ID and content hash; later frames copy metadata only. When the budget is exceeded, the oldest complete frames and unreferenced payloads are evicted together, so every retained tick remains independently restorable.
\nFor production, leave observation off. For interactive debugging, use observe and capture only when needed. Enable record for short repro windows, automated tests, or a failure trigger, then return to off.
Editors and players use warp_client_core for the behavior that must remain identical across platforms. The core owns canonical project/scene/workspace/ layer targets, deep-link parsing, catalog normalization, switch generations, write barriers, and stale-result rejection. main is normalized as an ordinary workspace rather than handled as a separate client mode.
Platform shells remain responsible for presentation and operating-system effects. SwiftUI, UIKit, AppKit, the browser DOM, and Windows controls render the shared state using their native interaction, accessibility, menu, and animation conventions. Their adapters perform URLSession/fetch/WinHTTP calls, secure token storage, system URL delivery, and dialogs.
\nDestination switching is the deliberate exception to otherwise native-only UI composition. WarpAppleClientUI provides one adaptive SwiftUI project/workspace picker and compact workspace menu for the Mac editor, Mac player, and iPad/iPhone player. The players reach it through a stable C ABI; the editor imports the same Swift package directly. Platform adapters only provide the catalog items and receive the selected stable ID, so presentation never adds a resolution request or bypasses the shared fast-switch coordinator.
destination_picker_copy in warp_client_core is the cross-platform content contract. It owns titles, descriptions, action labels, loading/empty/error wording, and the common current-selection convention. The web editor consumes its generated JSON manifest, Windows consumes it directly, and the Apple SwiftUI caller receives the same fields. Web and Windows retain native layout and controls, but use the same order and concepts: searchable destination list, visible current state, one primary Open action, optional client-specific secondary actions, and creation as a separate capability. A future interactive Linux shell must consume this contract rather than inventing another picker; the current Linux runtime is headless and has no project/workspace UI surface.
The C++ players link the core directly. The Mac editor uses the stable C bridge in WarpClientStateBridge, while the web editor loads the small WebAssembly bridge built as warp_client_core_web. New project, workspace, link, or session behavior belongs in the shared core first; platform code should only translate native events into core inputs and core outcomes into native UI.
The shared coordinator is a synchronous ordering primitive, not a loading layer. Known workspace targets reuse the live authoring endpoint directly and must not add a resolution request. Project and workspace presentation keeps the current viewport and content-addressed payload caches alive while authoritative state catches up; only missing or changed payloads are fetched.
\nThis contract applies to the web editor and player/runtime, the SwiftUI Mac editor and its native viewport, the Mac player/runtime, the iPad/iPhone player, and the Windows player. Native project/workspace pickers reuse destinations already authorized by their catalog response; arbitrary cross-server links still resolve once for correctness. A repeated active-scope request is a no-op unless it explicitly supplies a different network route.
\nWindows and Linux authenticate with Warp in the user's system browser; the player does not embed Chromium or Electron. DesktopBrowserAuth opens a loopback-only callback before launching the browser, attaches a cryptographically random state nonce, and accepts a session only when the callback path and nonce both match. The blocking socket wait runs on a worker thread in the Windows player and has no render-loop cost.
The Windows player stores the resulting token in Windows Credential Manager. The Linux/headless entry point exposes furry_runtime_headless --login [--server URL]; it launches xdg-open, waits up to five minutes, then atomically stores the session in an owner-only file below $XDG_STATE_HOME/warp-headless (or ~/.local/state/warp-headless). --login --no-browser prints the URL for environments where the browser launcher is unavailable.
Warp is a C++20/OpenUSD live authoring engine. It keeps authoring data, cooked runtime data, and live player state deliberately separate so the Mac editor, web editor, browser player, native viewport, and automation tools can all operate on the same project without turning the runtime into an OpenUSD editor.
\nAt a high level:
\nOpenUSD project package\n -> Authoring server and stage inspector\n -> Cooked scene snapshots, patches, and asset descriptors\n -> EnTT runtime world\n -> Sokol native/web renderer and play modeThe current stack includes:
\ndocs/DERIVED_ARTIFACTS.md). Never add a parallel cache, fingerprint scheme, or cooking path for a new derivation kind, and never derive artifact identity from timestamps, checkout paths, workspace names, or client-supplied parameters.A Warp project is a package rooted at a .furryproject directory. Important paths include:
Project.furryproject/\n project.json\n Scenes/\n Main.usda\n Layers/\n Example.usda\n Scripts/\n PlayerMovement.lua\n Content/\n sha256/\n ab/cd/<digest>.blob\n ab/cd/<digest>.json\n Workspaces/\n workspaces.json\n .derived/project.json records project-level settings such as the content store backend. Source scene data lives under Scenes/. User-created USD sublayers are created under Scenes/Layers/. Script source lives under Scripts/. Content-addressed blobs live under Content/ for local storage, or in Lore storage for Lore-backed projects.
Workspaces/workspaces.json stores Warp workspace metadata such as names, parent workspace IDs, base scene paths, archive markers, and author metadata. The durable branch/content backend may be Lore, but Warp keeps enough local metadata to make the editor UI fast and robust.
OpenUSD is the editable authority. It is used for:
\nFurry should prefer USD-native relationships and metadata over custom string databases. Asset/material bindings should be represented as relationship targets where possible, and legacy custom string forms are read for compatibility.
\nThe hidden Furry asset registry should not appear as ordinary authoring content in scene hierarchy UIs. It is implementation data, not user scene structure.
\nLayer support is built on native USD composition:
\nLayerInfo.Scenes/Layers/<Name>.usda.Prim edits, component edits, and USD property edits route through the active UsdEditTarget for that client. Web and Mac clients may have different active edit targets at the same time. Toggling or reordering layers must go through USD composition, not a custom override system.
Cooked data is the runtime-facing representation of OpenUSD-authored scenes. It contains compact entity, component, asset, material, animation, and script payloads keyed by stable IDs.
\nThe main cooked shapes are:
\nCookedSceneSnapshot: full runtime state for a scene/session.LiveEditPatch: incremental cooked replacements/deletions plus revision metadata.CookedAssetBlob: stable asset descriptor with kind, stable asset ID, source URI, content hash, byte sizes, cook status, content key/URL, and optional inline payload.The runtime does not need to know whether cooked records came from first load, a live edit, a script replacement, a layer recomposition, or an uploaded asset finishing its cook.
\nRuntime state is an EnTT registry plus runtime systems:
\nRuntimeWorld owns entity/component state, simulation state, script system, physics system, and stable ID mappings.EntityFactory converts cooked component payloads into runtime ECS components.LiveEditApplier applies snapshot and patch semantics.LuaScriptSystem runs behavior modules with a restricted API and diagnostics.PhysicsSystem integrates Jolt when enabled.Authored Transform values are always parent-local: translation is measured in metres, rotation is stored in the component's documented angle convention, and scale is multiplicative. The runtime keeps a parent-first hierarchy order and rebuilds that order only when entities are added, removed, or reparented.
Each simulation frame captures local transforms into retained storage, lets scripts and Jolt update their authorities, and performs one linear hierarchy composition pass. A dynamic rigid body owns its final world pose; ordinary children then compose their retained local pose from that result. Rendering, runtime queries, cameras, and playtests consume the resulting world transform directly and must not walk the parent chain a second time.
\nThis contract is shared by native Metal, WebGPU, iPadOS, Windows, and headless playtests because it lives in RuntimeWorld, below every renderer and client.
The runtime is intentionally not a USD host. It consumes snapshots and patches, stores assets by stable asset ID/content hash, and runs the game loop.
\nThe OpenUSD authoring side is split into a stage store and an authoring server:
\nUsdStageStore opens composed stages, reads hierarchy/detail/layer data, applies USD operations, cooks affected source entities/assets, and resolves source files.AuthoringServer accepts operation diffs, manages revision history, undo/redo, active edit targets, layer operations, script asset replacement, and cooked patch generation.furry_usd_inspector exposes composed stage/project data and cooked mesh/sound blob helpers for editor/server processes.furry_edit_client and furry_tool_client are CLI/client helpers for structured edits.The authoring server applies operations to USD first, then exports affected cooked records. It is the boundary that preserves undo/history, revision checks, live diagnostics, and consistent authoring semantics.
\nNative/editor communication uses protobuf/gRPC when FURRY_ENABLE_GRPC=ON.
Important streams and calls include:
\nStreamUpdates: sends snapshots, patches, asset changes, authoring previews, and reset/open-scene events to runtimes.SubmitUsdDiff: submits prim, component, USD property, asset, script, and layer operation diffs.OpenScene: switches the active scene/workspace for a client/session.StreamToolState and SubmitToolEvent: synchronize selection/tool state across clients.SubmitAuthoringPreview: sends transient preview updates for drag/slider interactions.The browser editor uses HTTP APIs plus web player glue for hosted operation. The live Sokol web player consumes binary snapshots/patches and fetches mesh/sound content on demand.
\nThe web editor is served by furry_web_editor_server. It owns the browser UI for:
The web editor keeps a local presentation model in JavaScript. Selection and inspector changes are local and immediate; expensive stage/project refreshes happen separately.
\nThe macOS editor is SwiftUI. It uses the same authoring and live update semantics, but should behave like the web editor:
\nThe Mac editor should not put network refresh, USD scans, asset lookup scans, or broad project recompute in the click/selection path.
\nRemote script editing is exposed through server endpoints such as:
\nGET /api/scriptsGET /api/script?module=scripts.NamePUT /api/script?module=scripts.NamePOST /api/vscode-sessionScripts are addressed by flat module names like scripts.PlayerMovement, mapped to Scripts/PlayerMovement.lua. Server-side validation rejects paths, traversal, nested modules for v1, and non-script assets.
CLI/agent workflows should prefer structured authoring tools such as ./tools/furry_ai for scene/component/script edits when an editor session is active. That preserves live updates, revision checks, undo/history, and diagnostics.
Rendering is provided by SokolRenderer.
Native:
\nfurry_runtime_sokol and WarpPlayerMac for native runtime/player builds.furry_runtime_viewport plus furry_viewport_client for the Mac editor viewport process.Web:
\nThe renderer owns camera controls, transform gizmos, object markers, retained mesh buffers, loading stand-ins, selection/drop overlays, shadow targets, and memory/performance diagnostics.
\nLua scripts are ECS system/behavior modules, not general plugins. They run in a sandboxed Lua state with an instruction budget and explicit component-access schemas. Native EnTT queries and schedules reject irrelevant systems before Lua is entered; structural operations commit after module iteration. Dense iteration, hierarchy resolution, continuous motion, physics, rendering, streaming, audio, and animation stay in C++. See docs/SCRIPTING.md.
Jolt Physics is integrated through PhysicsSystem and updates runtime transforms in play mode. Runtime refresh paths should update only changed transform data when possible, instead of forcing broad render-item rebuilds each frame.
Audio assets are cooked to a stable runtime format. Native and web both use decoded clip data, but web playback uses a WebAudio callback path to avoid crackle/slowdown from render-loop underruns.
\nAssets follow the same source/cooked/runtime boundary:
\nContentStore and served by content/blob endpoints.Hosted projects should avoid pushing large binary bytes through live-edit control streams. Web snapshots/patches should carry descriptors and content URLs for meshes/sounds when possible. After decode, web runtimes should release duplicate compressed payloads from WASM-side storage.
\nThe local content store is digest-addressed:
\nProject.furryproject/\n Content/\n sha256/\n ab/\n cd/\n abcdef....blob\n abcdef....jsonBlobs are immutable. Project asset records reference hashes; deleting an asset removes the reference, not necessarily the blob. Garbage collection can remove unreferenced blobs later.
\nHosted content endpoints should support immutable cache headers, ETag, and range requests for large data. Current endpoints also expose cooked mesh/sound blob helpers for web clients.
Lore is an optional durable backend for content and workspace history. It sits below Warp's authoring semantics rather than replacing them.
\nLocalContentStore writes SHA-256 blobs into the project package. LoreContentStore is compiled when CMake is configured with FURRY_ENABLE_LORE=ON and FURRY_LORE_ROOT points at an extracted liblore release.
Warp projects can declare:
\n{\n "contentStore": "lore",\n "loreRepository": "."\n}At runtime, Lore-backed deployments use environment such as:
\nFURRY_CONTENT_STORE_BACKEND=lore\nFURRY_LORE_WORKSPACE=/path/to/lore/repository-or-storage-workspace\nWARP_LORE_REMOTE_URL=https://optional-lore-service.example\n# Compatibility alias: FURRY_LORE_REMOTE_URLFurry talks to Lore native storage APIs for content-addressed storage and branch-style workspaces. Local workspace metadata is still important: it carries Furry names, parent workspace IDs, base scenes, archive markers, and UI-facing metadata. Local archive markers intentionally hide workspaces immediately even if remote Lore archive propagation is slow.
\nProject workspaces are branch-style editing contexts. The main workspace is the default. Additional workspaces can be created from a parent, opened independently, reviewed, merged, and archived.
\nKey rules:
\nmain cannot be archived.CMake options gate heavier integrations:
\nFURRY_BUILD_AUTHORINGFURRY_ENABLE_GRPCFURRY_ENABLE_SOKOLFURRY_ENABLE_LUAFURRY_ENABLE_JOLTFURRY_ENABLE_LOREFURRY_ENABLE_USD_LAYERSFURRY_BUILD_IOS_PLAYERCommon bundles:
\nfurry_core: cooked formats, content store, project/workspace metadata, export pipeline.furry_runtime: runtime world, Lua, physics, headless systems.furry_authoring: OpenUSD stage store and authoring server.furry_transport_*: protobuf/gRPC transport.furry_sokol_renderer: shared native/web renderer.furry_web_editor_server: hosted/local web editor, HTTP APIs, content endpoints.furry_web_sokol_viewer: Emscripten/WebGPU viewer/player bundle.furry_runtime_viewport and furry_viewport_client: Mac editor viewport runtime.Typical prim/component edit:
\nUsdStageStore applies the operation to OpenUSD.Typical asset upload/import:
\nsrc/client/WarpConnectionState.c; clients must not display raw response bodies, HTTP diagnostics, or gRPC diagnostics.\nThe shared states cover:
\nlogin_required / session_expired: sign in again.project_access_denied: request access or choose another project.project_not_found: choose another project.network_unavailable: retry without discarding local state.server_error: retry; no mutation is assumed to have succeeded.invalid_link: ask for a new project link.The Mac and iPad players parse HTTP responses through src/runtime/NativeWarpClient.mm. The Mac editor imports the same C state table through WarpClientStateBridge. gRPC stream failures are converted to the same codes by LiveUpdateClient.
When adding a connection error:
\ncode.WarpConnectionState.c.WarpConnectionStateTests.cpp.Warp has one CMake dependency entry point: cmake/FurryDependencies.cmake. The project is deliberately split between a USD-heavy authoring side and a small cooked-runtime side:
FetchContent..derived/.For the normal local Mac authoring stack:
\n./tools/run_usd_editor.shBy default that launches the hosted/remote authoring workflow. To build and run the local authoring server instead:
\n./tools/run_usd_editor.sh --localFor a simple build and test pass of the default OpenUSD authoring pipeline:
\n./tools/build_and_test.shIf CMake is not on PATH, bootstrap a local copy:
./tools/bootstrap_cmake.shThe main build switches are defined in CMakeLists.txt:
| Option | \nDefault | \nPurpose | \n
|---|---|---|
FURRY_FETCH_DEPS | \nON | \nFetch pinned source dependencies with FetchContent. | \n
FURRY_BUILD_TESTS | \nON | \nBuild and register unit tests. | \n
FURRY_BUILD_AUTHORING | \nON | \nBuild OpenUSD authoring libraries/tools. Turn this off for runtime-only targets. | \n
FURRY_BUILD_EXAMPLES | \nON | \nBuild runnable sample/player targets when their dependencies are enabled. | \n
FURRY_BUILD_IOS_PLAYER | \nOFF | \nBuild the iPadOS player target. | \n
FURRY_ENABLE_GRPC | \nOFF | \nEnable protobuf/gRPC transport and generated protocol sources. | \n
FURRY_ENABLE_JOLT | \nOFF | \nEnable Jolt physics. | \n
FURRY_ENABLE_LUA | \nOFF | \nEnable Lua script execution. | \n
FURRY_ENABLE_LORE | \nOFF | \nEnable Epic Lore native content-store integration. | \n
FURRY_ENABLE_USD_LAYERS | \nOFF | \nEnable USD layer editing and per-author edit targets. | \n
FURRY_ENABLE_SOKOL | \nOFF | \nEnable Sokol renderer/player targets. | \n
The common presets are:
\ncmake --preset dev\ncmake --build --preset dev\nctest --preset dev\n\ncmake --preset with-lua\ncmake --preset with-jolt\ncmake --preset with-sokol\ncmake --preset with-grpc\ncmake --preset full-demofull-demo enables gRPC, Jolt, Lua, and Sokol. It is the preset used by the local editor scripts and the live viewport stack.
| Dependency | \nRoute | \nUsed By | \nNotes | \n
|---|---|---|---|
| OpenUSD | \nLocal SDK prefix from tools/bootstrap_openusd.sh | \nAuthoring server, USD inspector, project mutation tools | \nEnabled when FURRY_BUILD_AUTHORING=ON; runtime targets must not link it. | \n
| EnTT | \nFetchContent, pinned to v3.15.0 | \nCore/runtime ECS-style storage | \nEnabled through FURRY_FETCH_DEPS. | \n
| zlib | \nSystem library, Emscripten port, or find_package(ZLIB) | \nCooked asset compression | \nLinked through furry_external_zlib. | \n
| miniaudio | \nVendored header under third_party/miniaudio | \nWAV, FLAC, and MP3 source import plus platform audio device I/O | \nNo network fetch; public domain or MIT No Attribution. Runtime assets are not stored in a miniaudio-specific format. | \n
| stb_vorbis | \nFetchContent, pinned to f0569113c93ad095470c54bf34a17b36646bbbb5 | \nOgg Vorbis source import | \nAuthoring-only; public domain or MIT. Imported bytes are recooked to Ogg Opus. | \n
| libogg 1.3.5 | \nFetchContent, pinned to v1.3.5 | \nCanonical Ogg Opus container writing, indexing, and bounded page decode | \nBSD 3-Clause. | \n
| libopus 1.5.2 | \nFetchContent, pinned to v1.5.2 | \nCanonical 48 kHz Opus encode/decode | \nBSD 3-Clause. | \n
| ufbx | \nVendored source under third_party/ufbx | \nAuthoring/import path | \nUsed by furry_authoring; no runtime OpenUSD dependency. | \n
| Lua 5.4.7 | \nFetchContent URL | \nRuntime script system | \nEnabled with FURRY_ENABLE_LUA=ON. | \n
| Jolt Physics 5.3.0 | \nFetchContent Git pin | \nRuntime physics | \nEnabled with FURRY_ENABLE_JOLT=ON; used by native, web player, and iPad builds when enabled. | \n
| Sokol | \nFetchContent Git pin | \nWebGPU/Metal/OpenGL renderer frontends | \nEnabled with FURRY_ENABLE_SOKOL=ON. | \n
| protobuf/gRPC | \nInstalled CMake packages from Homebrew/bootstrap scripts | \nLive authoring transport, clients, viewport services, iPad transport | \nEnabled with FURRY_ENABLE_GRPC=ON. | \n
| Remedy usdFBX | \nOptional OpenUSD plugin under .derived/usdfbx | \nUSD composition/import of FBX source files | \nRequires Autodesk FBX SDK. Loaded with PXR_PLUGINPATH_NAME; never linked by runtime targets. | \n
| Epic Lore/liblore | \nOptional extracted SDK | \nHosted/native content store backend | \nEnabled with FURRY_ENABLE_LORE=ON and FURRY_LORE_ROOT. | \n
| Emscripten + emdawnwebgpu | \nExternal toolchain | \nWeb Sokol viewer/player | \nRequired for tools/build_web_sokol_viewer.sh. | \n
| Xcode/iOS SDK | \nExternal Apple toolchain | \nMac editor/player and iPad player | \niPad builds also need signing for device deployment. | \n
| VS Code + Node/npm | \nExternal tools | \nRemote Lua script-editing extension | \nPackaging uses npx @vscode/vsce; install uses the code CLI. | \n
OpenUSD is an authoring SDK. Build it into Warp's derived tree:
\nOPENUSD_PREFIX="$(./tools/bootstrap_openusd.sh)"\ncmake --preset dev -DCMAKE_PREFIX_PATH="$OPENUSD_PREFIX"\ncmake --build --preset dev\nctest --preset devtools/bootstrap_openusd.sh currently defaults to OPENUSD_VERSION=v26.05. It builds a small USD distribution with no imaging, Python, tools, examples, tutorials, tests, or MaterialX. On first run it can take tens of minutes and several GB under .derived/openusd/.
After .derived/openusd/install exists, CMake auto-discovers it for authoring builds.
Desktop gRPC uses Homebrew packages:
\nGRPC_PREFIX_PATH="$(./tools/bootstrap_grpc.sh)"\ncmake --preset with-grpc -DCMAKE_PREFIX_PATH="$GRPC_PREFIX_PATH"\ncmake --build --preset with-grpctools/bootstrap_grpc.sh installs or finds Homebrew protobuf and grpc, then prints a semicolon-separated prefix path. When enabled, cmake/FurryProto.cmake generates C++ sources from proto/furry_runtime.proto.
The live editor stack combines gRPC and OpenUSD:
\nGRPC_PREFIX_PATH="$(./tools/bootstrap_grpc.sh)"\nOPENUSD_PREFIX="$(./tools/bootstrap_openusd.sh)"\ncmake --preset full-demo -DCMAKE_PREFIX_PATH="$GRPC_PREFIX_PATH;$OPENUSD_PREFIX"\ncmake --build --preset full-demoWeb targets are runtime-only Emscripten builds with Sokol's WebGPU backend. They do not build authoring tools and they do not link OpenUSD.
\nBuild both web bundles:
\n./tools/build_web_sokol_viewer.shThat script produces:
\nbuild/web-sokol-viewer/furry_web_sokol_viewer.htmlbuild/web-sokol-player/furry_web_sokol_viewer.htmlRequirements:
\nemcmake on PATHemdawnwebgpu port availableUseful overrides:
\nFURRY_WEB_SOKOL_BUILD_TYPE=Debug ./tools/build_web_sokol_viewer.sh\n\nFURRY_WEB_SOKOL_BUILD_DIR=build/web-custom \\\nFURRY_WEB_ENABLE_JOLT=ON \\\nFURRY_WEB_ENABLE_LUA=ON \\\n ./tools/build_web_sokol_viewer.shThe Mac editor is a SwiftUI package under apps/usd_editor. The launcher builds the C++ tools first, then starts Swift with the correct paths:
./tools/run_usd_editor.shFor the fastest edit-build-test loop, rebuild only the native clients. This is incremental, does not clean or reconfigure an existing build, and does not build or start any local server:
\n./tools/build_mac_clients.shUse --launch to open both rebuilt apps, --editor-only or --player-only to build one client, and --clean only when an explicit clean rebuild is needed.
Hosted mode connects to the remote authoring and web services by default and launches both the native Mac editor and the native Metal/Sokol Mac player against the same hosted scene and workspace:
\n./tools/run_hosted_usd_editor.shSet FURRY_USE_LOCAL_WEB_EDITOR=1 when local web assets are specifically needed. That opt-in also adds furry_web_editor_server to the targeted build.
Common environment variables:
\n| Variable | \nPurpose | \n
|---|---|
WARP_HOST / FURRY_HOST | \nHost for the remote editor service, defaulting to warp.billrey.net. | \n
WARP_ADDRESS / FURRY_ADDRESS | \ngRPC address, default grpcs://$HOST:443. | \n
WARP_PROJECT_SERVER_URL / FURRY_PROJECT_SERVER_URL | \nHTTP project/web service base URL. | \n
WARP_WEB_EDITOR_URL / FURRY_WEB_EDITOR_URL | \nURL passed to the Mac editor for opening web views. | \n
FURRY_USE_LOCAL_WEB_EDITOR | \n1 to build and serve local web assets, 0 to use the remote web editor URL (default). | \n
FURRY_SCENE | \nExplicit scene path to open. | \n
WARP_WORKSPACE / FURRY_WORKSPACE | \nExplicit hosted workspace for both the editor and player. | \n
FURRY_CLIENT_ID | \nAuthor/client id for live edits and active layer state. | \n
WARP_LAUNCH_MAC_PLAYER / FURRY_LAUNCH_MAC_PLAYER | \n1 to launch the native Mac player (default), 0 for editor-only startup. | \n
WARP_PLAYER_CLIENT_ID / FURRY_PLAYER_CLIENT_ID | \nClient id used by the spawned native Mac player. | \n
FURRY_LORE_ROOT | \nLocation of an extracted Lore/liblore SDK. | \n
On Apple platforms, native Sokol uses Metal and links the needed Apple frameworks from CMake.
\nThe direct-download Mac editor package is produced with:
\n./tools/package_mac_editor.shThis builds the hosted/cloud editor bundle, copies the Swift editor plus native helper tools into Warp Editor.app, vendors non-system dylibs into Contents/Frameworks, signs the bundle, and writes a DMG under dist/mac-editor/.
For local smoke testing without a Developer ID certificate, the script falls back to ad-hoc signing:
\n./tools/package_mac_editor.sh --no-notarizeFor public distribution, install a Developer ID Application certificate and create or refresh the notarytool Keychain profile with the repository helper. It validates the credentials before saving them and prompts securely for the app-specific password, so the password does not enter shell history:
\n./tools/setup_mac_notarization.sh --apple-id YOU@example.comFor an App Store Connect API key, which is better suited to durable automated releases:
\n./tools/setup_mac_notarization.sh \\\n --key /secure/path/AuthKey_KEYID.p8 \\\n --key-id KEYID \\\n --issuer ISSUER_UUIDThe equivalent manual Apple ID command is:
\nxcrun notarytool store-credentials warp-notary \\\n --apple-id you@example.com \\\n --team-id TEAMIDThen build the signed, notarized DMG:
\nWARP_MAC_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \\\nWARP_NOTARY_KEYCHAIN_PROFILE=warp-notary \\\n./tools/package_mac_editor.sh --notarizeThe generated DMG contains the app and an Applications symlink for drag-install. Public packaging first notarizes and staples the app, then embeds that exact app in the signed DMG and notarizes and staples the DMG. Submission results and full Apple notary logs are retained under dist/mac-editor/notary-logs/ or dist/mac-player/notary-logs/. The release fails if either ticket, Gatekeeper assessment, or the app mounted from the final DMG does not validate.
The iPad player is a runtime-only Xcode build. Build for device:
\n./tools/build_ios_player.shBuild for simulator:
\nFURRY_IOS_VARIANT=simulator ./tools/build_ios_player.shThe iOS build uses:
\ntools/bootstrap_grpc_ios.sh for iOS gRPC librariesprotoc and grpc_cpp_plugin built from the matching pinned sourceFURRY_IOS_DEVELOPMENT_TEAM for device signing, or an Apple Development identity discoverable through KeychainThe generated Xcode project is written under build/ios-player-device/ or build/ios-player-simulator/.
FBX is authoring/source data, not runtime data. Furry can use two paths:
\nufbx for direct import/cooking in the authoring code.usdFBX as an OpenUSD file-format plugin so USD layers can reference .fbx files and compose them through USD.Build the usdFBX plugin after OpenUSD is available:
\nOPENUSD_PREFIX="$(./tools/bootstrap_openusd.sh)"\nADSK_FBX_LOCATION="/Applications/Autodesk/FBX SDK/2020.3.7" \\\n ./tools/bootstrap_usdfbx.sh "$OPENUSD_PREFIX"The script installs plugin resources under:
\n.derived/usdfbx/install/usdFbx/resourcesUse it by setting PXR_PLUGINPATH_NAME, or let tools/run_usd_editor.sh --local do it automatically:
export PXR_PLUGINPATH_NAME="$PWD/.derived/usdfbx/install/usdFbx/resources${PXR_PLUGINPATH_NAME:+:$PXR_PLUGINPATH_NAME}"The runtime never links usdFBX, the Autodesk FBX SDK, or OpenUSD.
\nLore is optional. If FURRY_LORE_ROOT or .derived/lore-sdk-inspect contains lore.h plus liblore.dylib or liblore.so, the editor launchers pass:
-DFURRY_ENABLE_LORE=ON -DFURRY_LORE_ROOT=<path>The scripts also extend DYLD_LIBRARY_PATH/LD_LIBRARY_PATH so the native tools can load the library. Builds without Lore still use the local content store path.
The remote script editing workflow is implemented as a small VS Code extension under tools/vscode-furry-scripts.
Install it locally:
\n./tools/install_vscode_furry_scripts.shPackage a reusable .vsix without installing:
./tools/package_vscode_furry_scripts.shRequirements:
\ncode CLI on PATH for installnpx --yes @vscode/vsce packageFor extension development, install a live symlink:
\n./tools/install_vscode_furry_scripts.sh --dev-linkCMakeLists.txt if the dependency is optional.cmake/FurryDependencies.cmake.FetchContent for small source dependencies and an installed prefix or bootstrap script for heavy SDKs.find_package(pxr) fails: run ./tools/bootstrap_openusd.sh, or pass its printed prefix through -DCMAKE_PREFIX_PATH.emcmake: install and activate Emscripten before running tools/build_web_sokol_viewer.sh../tools/bootstrap_grpc.sh and pass the printed prefixes to CMAKE_PREFIX_PATH.ADSK_FBX_LOCATION.PXR_PLUGINPATH_NAME includes .derived/usdfbx/install/usdFbx/resources.FURRY_IOS_DEVELOPMENT_TEAM=<TEAMID> or sign into Xcode with an Apple Development account.