Scenes
A scene is a simulation environment — a directory holding one MJCF scene or one URDF robot, plus its assets — that you push from the terminal and open as a live, interactive 3D page in the dashboard.
Browsing in the app
/<namespace>/profile?tab=scenes and /<namespace>/scenes reuse the same
Scenes catalog. Your own namespace and organizations you belong to show
resources and actions allowed by your permissions. Signed-out visitors and
signed-in visitors to other namespaces see public resources only, without
creation or modification controls. Profile uses an avatar rail; the application
uses resource navigation for the namespace in the URL.
Your own Scenes catalog also includes recent scenes from your organizations. Public scenes and valid Scene share-token links open without sign-in.
The application sidebar shows the resource owner's avatar and links, including for anonymous public readers. Your signed-in identity and personal/organization switcher are separate from that owner. See Profiles and workspaces.
The detail header returns anonymous readers to /<namespace>/profile?tab=scenes
and signed-in readers to /<namespace>/scenes. Details opened inside a project
retain their return-to-project action. There is no extra sign-in navigation bar.
In the development UI, project and bindr grids reuse a scene's saved thumbnail. Scenes without a saved thumbnail keep their type icon until a member opens the viewer to capture one or supplies a cover (see Thumbnails).
Generate with chat
Members can also create and edit scenes from the browser, by prompting an embedded agent that runs the scene-generation skill. The chat panel ships with the web app — it appears once an app deployment that includes scene chat reaches your server:
- In your namespace's Scenes catalog, click + new scene — in the page
header next to the Scenes/Libraries switch, and offered again by
the empty catalog's placeholder. One click opens a fresh draft with an
auto-minted name (
env_xxxxxx) — no dialog, nothing to type first, and nothing exists on the server until the agent's first successful push. - The draft opens straight into the intro composer — describe the
scene there; the agent sources assets, measures, composes, validates,
and publishes with
dl scene push. - On the first successful push the draft becomes the saved preview — the interactive viewer on the pushed version, chat still beside it.
- Follow-up prompts create new versions of the same scene. The viewer tracks the latest; picking an older version in the header pins it, and a "vN available" button jumps back to latest.
- Editing an existing scene works the same: open its page as a member and prompt the chat panel next to the viewer. Read-only viewers, share links, and anonymous visitors never see the chat.
- To grow a new scene out of an existing one, start from the catalog, not from the source scene's page — the chat edits the scene whose page it sits on. Click + new scene for a fresh draft, then ask it to start from the source scene at a pinned version; the source scene keeps its own versions, untouched (details in the Quickstart).
The scene chat opens in Auto permission mode, so one prompt can carry
through the whole workflow — the agent runs the scene tools and
dl scene push without per-command approval. The composer's
permission control still works as usual: switch to Ask permissions or
Plan mode for a read-only conversation (the agent inspects and answers
but does not generate or push), and switch back to Auto when you want it
to build. A read-only choice is respected for as long as you keep it — the
page sets the mode only once, on open, and never overrides your selection.
Scene membership still governs what a push may touch: the mode routes what
the agent may run, not what your account may write.
The install-and-use guide for the same workflow from a local agent — ordinary create / edit / reuse prompts included — is the Scene Generation Quickstart.
Troubleshooting the preview when running the app from source. If the
viewer panel shows an error fallback instead of the scene and the console
logs R3F: Hooks can only be used within the Canvas component!, that is a
dev-server fault, fixed in the app source on 2026-09-29: the dev server
could load two copies of the 3D renderer and which copy a session got
depended on load order — so the crash appears and disappears between
checkouts, and its absence on one run proves nothing. If you see it, your
source checkout predates the fix: update to a checkout that carries it and
restart the dev server. In that source's dependency graph the production build
resolves a single renderer copy, which bounds the fault to the dev server
— an inference about the current source only, not an audit of anything
previously deployed. Count the scene as loaded only when its actual
geometry is visible and the simulation controls respond; that console
error is failure evidence, and a page shell or a bare <canvas> is not
success — the canvas can mount and then unmount again while the model
loads.
Push one
The entry file is auto-detected — the one root-level *.xml/*.mjcf
containing <mujoco>, or (with no MJCF around) the one root-level *.urdf
containing <robot>, which also sets the scene's type to urdf. Relative
<include>, <mesh file="…"> and package:// references keep working
exactly as they do on disk. The CLI prints an open link.
| Flag | What it does |
|---|---|
--entry scene.mjcf | Pick the entry when there are several candidates |
--type isaaclab | Simulator family — stored and pullable; mujoco and urdf have viewers |
--visibility public | Anyone can open the viewer, no login |
--name, --title | Identity (defaults to the directory name) |
--thumbnail cover.png | Set the gallery cover yourself (PNG ≤ 512 KiB) — see Thumbnails |
Version it — only changes upload
Push the same scene again and you get v2. Files are content-addressed, so unchanged meshes and textures are never uploaded or stored twice — the CLI tells you exactly what moved:
Drive it
For a mujoco scene the viewer is a real simulation, not a screenshot: the engine runs on load, and the toolbar gives you play / pause / reset / speed.
- Sliders — every actuator (
ctrl, with its real range) and every hinge/slide joint, straight from the model. - t = 0 is your authored initial state — when the model defines a
<keyframe>, the viewer opens at (and reset returns to) keyframe 0, including itsctrl; without one it uses the compiled defaults (qpos0). Keyframe honoring is a source change awaiting the next viewer deployment: the prior source baseline (and its wasm runtime) opens at qpos0 regardless of keyframes, so until the deploy — verify in the app — expect qpos0. - ⌥ / Alt + drag — pull any body with a mass-scaled spring force, like the MuJoCo app's perturbation.
- files — the version's full file listing, entry highlighted.
- The first member visit renders the gallery thumbnail — see Thumbnails for how the angle is chosen and how to control it.
A urdf scene opens as a poseable robot instead — no physics, pure
kinematics: every non-mimic revolute / continuous / prismatic joint gets a
slider with its real limits, dragging a link in the scene rotates its
joint directly (orbit pauses while you hold it), and reset returns the
pose to zero. Meshes referenced as relative paths or package:// URIs
resolve against the pushed directory.
USD preview. A version whose entry
ends in .usd, .usda, .usdc, or .usdz opens in the USD viewer, including
scenes labeled isaaclab. Drag to orbit, scroll to zoom, or use Reset view
to restore the framing. The viewer reads referenced layers and textures on
demand from that version's uploaded files; include those dependencies with
the scene and preserve their relative paths. Dependencies outside the version
are not fetched. Loading failures offer a retry and the file listing, and
unsupported content is reported in the preview.
This is a visual preview; it does not run Isaac/PhysX simulation, cloth solvers, or robot drives. USD previews do not capture gallery covers automatically; supply a thumbnail when pushing. Reload the scene refreshes the version's download URLs as well as restarting the viewer.
Rendering profiles and reusable robots
A MuJoCo Scene can carry a viewer.render.json beside its selected MJCF entry.
The Scene page and library preview read it automatically. It controls bundled
HDR illumination, named PBR materials, tone mapping, exposure, background,
ambient occlusion, shadows and optional camera framing without changing the
simulation model. Scenes without a profile retain their defaults. Scenes with
a profile open paused to show the initial pose; Play starts simulation.
Profiles currently apply to the MuJoCo viewer, not URDF or USD previews. For a polished showcase and a reusable robot, package two explicit entries:
Profile example
- The
.hdrpath is relative to the profile directory and must resolve within the uploaded version. External URLs, absolute paths and..are rejected. Environment intensity is 0–8; rotation is in degrees. - Tone maps:
AgX,ACES,Neutral; exposure: 0.01–8. Background is a six-digit hex colour orenvironment. - Material keys match MJCF material names. Roughness is 0.02–1, metalness
0–1 and IOR 1–2.5. Optional
coloris an sRGB RGB triplet in 0–1; it replaces the material's texture in the preview. Unlisted materials keep their appearance. - Camera position and target use MuJoCo Z-up coordinates; FOV is 5–100°. Omit the camera to use the normal authored MJCF framing.
- AO radius is 0.001–2 world units; intensity is 0–3. Shadow intensity is 0–8, azimuth −360–360°, elevation 1–89° and softness 0–10.
- Scene pages use real-time raster rendering for still views and interaction;
they do not run path tracing. Use
"quality": "raster". Legacy profiles with"quality": "progressive"still load, but Scene pages render them in raster mode. The HDR, PBR materials, tone mapping, AO and shadows still apply.
Viewer lighting controls may override the profile. Invalid profiles, missing HDR files or failed HDR loads show an error and fall back to default lighting. With an active profile, its HDR and key light replace authored MJCF lights in the web preview. Keep MJCF lights as a fallback for local MuJoCo rendering. This is a web presentation contract; other engines need to map its settings and may produce different images.
Download and reuse
The pull downloads the complete pinned version and verifies file hashes. Load
robot.urdf with its referenced meshes to reuse only the robot; preserve relative
paths. Use the showcase and profile as a rendering reference. Document both
entry points and any physics limitations in the README: a good preview does not
certify a manipulation task or calibrated dynamics.
Thumbnails
The scene grid's cover image is rendered in the browser the first time a member opens a new version: a fixed 16:10 PNG with a transparent background, at the scene's initial (t=0) pose — physics is held until the capture, so the cover shows the authored t=0 state (see Drive it), not half a second of free fall.
The camera angle is chosen from the scene itself, in priority order:
-
A camera named
thumbnail— add one to your MJCF and the cover (and the viewer's opening shot) is exactly that camera: -
The first
<camera>in the model (including<include>d files) — scenes authored with a hero camera need no rename. -
The free-camera stance MuJoCo's own viewer would use —
<visual><global azimuth="…" elevation="…"/></visual>plus<statistic center="x y z" extent="…"/>when authored. This is the cheapest lever: two lines, and the cover matches what you see insimulate: -
A geometry fit — bounding sphere of all geoms (ground planes excluded), from a three-quarter angle. URDF robots always use this fit.
Two overrides beat all of the above:
- The camera button in the viewer toolbar (members only, latest version): orbit to any angle and click it — that exact view becomes the cover, and the angle is remembered, so future versions auto-capture from it too.
dl scene push --thumbnail cover.pngstores your own image (≤ 512 KiB PNG) and marks it manual, so the viewer won't overwrite it for that version. Works on a no-change push (thumbnail-only update).
Pull it back
Every file is verified against its content hash on the way down — the directory you get is byte-identical to the one that was pushed.
Scene layers
A scene can also be composed from other scenes. A layer stack
(dreamlake.layers.json) is an ordered list of ops — one flat object
per line, in the vocabulary of vuer's imperative updates — and
materializes into an ordinary mujoco scene. No layer has a special role,
and later ops win; swapping the gripper is editing one line and
re-pushing. The pushed version carries both the flat artifact (what every
viewer and SDK reads) and the pinned stack, so any composed scene can be
reopened, edited, and recomposed later.
| op | what it does |
|---|---|
Merge | union the scene's MJCF into the stack — a same-name collision is an error |
Attach | graft the scene's subtree at a target under the identity root key (right makes right:palm), with a mount pose and joint mode |
Update | inline sparse opinions: key addresses one element, every other prop is an MJCF attribute — nothing else is touched |
Remove | delete the addressed element and its subtree — drop the line and it's back |
Patch | Update-style opinions from a sparse-MJCF file or scene, for big opinion sets |
src is one string: ns/name[@v] is a registry scene (unversioned floats),
a ./-prefixed path is a local directory or file.
Materialization is a real MuJoCo build, so dl scene compose
delegates it to the engine in dreamlake-py — install it with
pip install "dreamlake[compose]" (Python + MuJoCo) on the composing
machine. Push / pull / list need no Python.
Every field, the exact semantics, and six annotated stacks: Scene Layers Reference.
Under the hood
Uploads go straight to storage with short-lived scoped credentials, and reads
are presigned URLs — scene bytes never pass through the API server. The
read side is two plain REST calls (…/versions and …/versions/:v), so any
HTTP client can list and download a scene without special tooling.
Delete it (safely)
Let Claude do it
Install the scenes skill, point at a repo, and say "push the MuJoCo scenes in here to DreamLake":
dl skill update brings in new releases and leaves your local edits
alone. Without the CLI, download skills.tar.gz from the latest
dreamlake-skills release
and copy dreamlake-scenes/ and dreamlake-cli/ into your agent's skills
directory.
The dreamlake-scenes skill does the part that isn't a single command:
extracting a self-contained directory from a scene that references
meshes outside itself (collecting the robot folders, rewriting the relative
paths), verifying the result still compiles before pushing, and running the
pull-back round-trip check after.
Next steps
Recorded teleop episodes don't live here — they play back inside sources, each dataset carrying its own model snapshot, with the scene itself unchanged: visualize a source.
One skill install, then build / edit / reuse scenes with ordinary prompts — locally or from the scene page's chat.
The dreamlake.layers.json contract — merge / attach / override, field
by field, with annotated stacks.
Every flag — names, types, entries, visibility, limits.
The REST endpoints behind push, versions, and presigned reads.
Scenes compatibility and product vocabulary
Scenes are versioned worlds containing geometry, robots, objects, materials and physics properties. A Simulation will pair a scene version with a simulator and task logic (observations, actions, rewards and termination). A Sandbox is an isolated execution workspace; a Run is one execution, and an Episode spans reset to termination. Compute owns machines. Simulation and isolated Sandbox registries are proposals, not existing interfaces; the bounded Compute experiment launcher is not a sandbox lifecycle.
The canonical collection and detail URLs are /<namespace>/scenes and
/<namespace>/scenes/<name>. Old /envs browser URLs redirect, retaining resource,
query and fragment. Libraries remain a Scenes tab; library detail URLs remain
/<namespace>/libraries/<name>.
CLI 0.45.0 introduces dl scene (env remains an alias). REST uses
/namespaces/:slug/scenes and all existing resource/version/upload/restore/delete
suffixes. The /envs API aliases run the same handlers, with identical auth and
storage; writes are not redirected. Catalog responses expose scenes, retaining
envs for older clients. Share tokens and resource identities are unchanged.
Existing envType, EnvEntry, env_* identifiers, ENVS_* configuration,
envs/ object prefixes, the immutable ~/.dreamlake/cache/envs/ cache,
dreamlake.env-layers/v3 and dreamlake.envlayer remain compatible technical
contracts. Login environments (dl auth env), environment variables and
RL environment interfaces retain their technical names.
Project attachment access
Independent resource share links remain available. Explicit Project user/team READ grants add read access to all current and future attached resources; WRITE and ADMIN add supported content editing. They do not grant resource sharing management, deletion, ownership transfer or infrastructure credentials. Public Project visibility alone never exposes private attached resources. Resource-own access and all live Project grants are combined at the canonical resource URL.
Detaching a resource, revoking a Project grant, or leaving its granted team removes only that source of access. A resource attached to several Projects keeps access through the others. No resource share links or acceptance records are created, copied or revoked by Project sharing. Attach requires the target Project's content-create permission and the resource's own sharing-management permission; readable content cannot be redistributed by a reader. A resource owned by another namespace attaches only through its owner's cross-namespace mount grant.
The Project-sharing backend and Web update are released. CLI attachment commands require 0.62.0 or later; Python Project support requires SDK 0.29.0 or later. Check installed client versions separately from server support. Ownership transfer remains separately execution-gated.
Project content writers may obtain temporary upload credentials only when the
backend can restrict them to that resource. Custom S3/MinIO static credentials
and an unscoped STS fallback are never issued through Project-only authority;
these configurations return DELEGATED_UPLOAD_UNSUPPORTED (403) rather than
exposing the server identity. Existing namespace-member upload behavior remains
separate from Project inheritance.
New whole-Project transfers require the
advertised streaming protocol and preserve the eligible existing access and
Project placements. The current streaming inventory admits ordinary Project
files/images/videos, owned Memos and eligible Artifacts, but not Scene/Env
resource references. A Scene/Env mount blocks the entire request with
PROJECT_STREAM_RESOURCE_UNSUPPORTED; it is never silently excluded. Check the
server's preview blockers rather than inferring support from the installed client.
Do not fall back to a fixed manifest, detach resources silently, or copy/delete
them to emulate a move. No standalone Scene/Env ownership transfer is added.
Existing legacy operations retain authorized status, decisions, exact saved-request replay and automatic recovery, including previously created Scene/Env requests. That compatibility does not admit new fixed-manifest Project transfers. Preserve the original request/key after a lost response and never clear a claim or lease manually. Independent Scene sharing and released Project-derived content access remain available.