<!-- source: https://docs.dreamlake.ai/scenes @ 0.1.192 b2f973b1 -->
{/* FigEnv* come from the site-wide mdxComponents map in site.config.ts —
    no import needed. */}

# 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](/workspaces.md).

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](#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](/scene-generation/quickstart.md). The chat panel
ships with the web app — it appears once an app deployment that includes
scene chat reaches your server:

1. 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.
2. 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`.
3. On the first successful push the draft becomes the **saved preview** —
   the interactive viewer on the pushed version, chat still beside it.
4. **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.
5. 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.
6. 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](/scene-generation/quickstart.md)).

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](/scene-generation/quickstart.md).

**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

```bash
dl scene push ./cassie
```

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](#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:

```txt
✓ pushed you/cassie v2 — 20 files (1 uploaded 12.4 KB, 19 reused)
```

## 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 its `ctrl`; 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](#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:

```text
taku-robot/
  showcase.xml              # default MJCF, pose and stage
  viewer.render.json        # sibling of the selected entry
  robot-display.xml         # articulated robot included by showcase.xml
  robot.urdf                # independent robot-only entry
  meshes/                   # geometry and embedded GLB materials
  presentation/studio.hdr   # bundled environment
  README.md                 # entry points, dependencies and provenance
```

```bash
dl scene push ./taku-robot --namespace my-team --name taku-robot \
  --entry showcase.xml --type mujoco
```

### Profile example

```json
{
  "schema": 1,
  "quality": "raster",
  "environment": { "file": "presentation/studio.hdr", "intensity": 0.65, "rotation": 0 },
  "tone": { "map": "AgX", "exposure": 1 },
  "background": "#e7e8ea",
  "materials": {
    "shell": { "roughness": 0.38, "metalness": 0, "ior": 1.46, "color": [0.8, 0.77, 0.7] }
  },
  "ao": { "radius": 0.15, "intensity": 0.65 },
  "shadow": { "intensity": 2, "azimuth": -50, "elevation": 55, "softness": 3 },
  "camera": { "position": [2.6, -3.3, 1.9], "target": [0, 0, 0.85], "fov": 32 }
}
```

- The `.hdr` path 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 or `environment`.
- Material keys match **MJCF material names**. Roughness is 0.02–1, metalness
  0–1 and IOR 1–2.5. Optional `color` is 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

```bash
dl scene pull taku-robot@2 --namespace my-team -o ./taku-robot
```

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](#drive-it)), not half a
second of free fall.

The camera angle is chosen from the scene itself, in priority order:

1. **A camera named `thumbnail`** — add one to your MJCF and the cover (and
   the viewer's opening shot) is exactly that camera:

   ```xml
   <worldbody>
     <camera name="thumbnail" pos="1.6 -1.8 1.4" xyaxes="0.75 0.66 0 -0.28 0.32 0.9"/>
     …
   </worldbody>
   ```

2. **The first `<camera>` in the model** (including `<include>`d files) —
   scenes authored with a hero camera need no rename.
3. **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 in
   `simulate`:

   ```xml
   <statistic center="0 0 0.7" extent="1.2"/>
   <visual>
     <global azimuth="120" elevation="-20"/>
   </visual>
   ```

4. **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.png`** stores 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

```bash
dl scene pull cassie          # latest → ./cassie/
dl scene pull cassie@1 -o v1  # any version
```

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.

<span id="env-layers" />

## 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.

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen" },
    { "tag": "Attach", "src": "you/sharpa-right", "key": "right",
      "at": "world", "pos": [0.45, -0.12, 0.30], "joint": "free-anchored" },
    { "tag": "Update", "key": "obj/mug", "pos": [0.30, 0.10, 0.02] },
    { "tag": "Remove", "key": "body:fixture/plant" }
  ]
}
```

```bash
dl scene compose          # materialize ./dreamlake.layers.json locally
dl scene push <out-dir>   # push artifact + pinned stack as one version
```

| 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.

> **Note:** 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](/scenes/layers.md).

## 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)

```bash
dl scene delete cassie              # soft delete (restorable)
dl scene restore cassie             # bring it back
dl scene delete cassie --permanent  # erase storage — no undo
```

## Let Claude do it

Install the [scenes skill](https://github.com/dreamlake-ai/dreamlake-skills),
point at a repo, and say *"push the MuJoCo scenes in here to DreamLake"*:

```bash
dl init                           # once: pick your agent and scope
dl skill install dreamlake-scenes
```

`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](https://github.com/dreamlake-ai/dreamlake-skills/releases/latest)
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](/sources.md).

    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](/api/external-mounts/).

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](/dev/notes/project-note-transfer/) 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.
