> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment editor
> Create and customize 3D environments for your robotics simulations and testing scenarios
## What is the environment editor?
The environment editor is a 3D design tool for setting up digital twins and static objects in an environment. You can arrange robots, cameras, sensors, areas, waypoints, and scene geometry before using them in simulation or workflows.
Robot, sensors, objects, and whole facilities
One click export to MuJoCo. Simulate camera streams and sensor data.
Stream real data from your cameras and robots, visualize them in the
environment
***
## Key Features
The Environment Editor provides a comprehensive set of tools for creating and managing your simulation environments.
Intuitive visual editor with snap-to-grid functionality
Work with your team in real time
Exact coordinate control for professional layouts
Top-down, perspective, and orthographic views
Undo/redo and environment versioning
Real-time physics simulation while editing
***
## Working across tabs and with teammates
In **Simulate** and **Live**, choose **Monitor** or **Control** directly beneath the main mode buttons. Open the workbench’s **Activity** tab to follow workflow runs and their steps without sending commands.
File, Edit, View, and other tools appear directly on wider screens and move into **Menu** on compact screens. Mode labels and workbench shortcuts stay visible on wider screens. Below 1024px, the side panels start closed; choose **Panels → Scene tree** or **Inspector** to open one at a time. Widening the window restores your desktop layout. Compact screens move **Share**, **Environment settings**, and **Order hardware** into **Menu → File**. Double-click a side-panel divider or the workbench's top divider to hide that panel; reopen it from the matching left, right, or bottom panel button (or **Panels** on compact screens). Dragging the same divider still resizes it. Click the scene search prompt anywhere to search scene objects and the catalog, including in Simulate or Live. Adding results to the scene still requires Edit mode and permission. Hover a disabled add action to see whether to switch to Edit or request permission. Other compact search controls open from their search icon; **Escape** collapses it without clearing the query; the visible query chip reopens it, and **Clear search** removes the filter. The clear X appears only with text; the scene’s + remains available while searching. Wider workflow panels show short status labels beside their icons. Scene rows keep a stable height, with secondary details on hover or focus and hidden, locked, or failed states kept visible.
The **Environment assistant** keeps its conversation when you switch between
**Edit** and **Monitor** in Simulation or Live within the same page session.
Small labels show where each request happened; replies keep their original label
even if you switch views while waiting. Earlier messages remain visible.
The selected right-hand tab stays open across mode switches. Select a scene
object to inspect it, or open **Agent** to return to the conversation.
Returning to **Edit** restores the selected twin’s editable details without
another click. If **Agent** is open, it stays open.
Unsent environment assistant drafts, tagged objects and reference images stay
available when you visit Control and return. Restoring a draft never sends it;
the control agent still has a separate composer.
Monitor keeps action cards read-only. Switching to Monitor requests a stop to
unfinished assistant editing, but does not stop running robots or training jobs.
Conversation history is not yet restored across page reloads or separate browser tabs.
**Replay** appears when saved simulation runs or recorded streams are available. It stays reachable while availability is loading or unknown, and remains visible while Replay is the selected mode. Empty environments hide it after the availability check; new recordings restore it automatically.
**Simulate** shows no dot without a running or initializing simulation, and a green dot when the simulation is ready. Enabling Playground physics alone does not mark a simulation as running. **Live** shows no dot without paired hardware, a gray dot for paired hardware that is disconnected, and a blue dot while hardware is connected. While simulation provisions or loads its physics scene, a spinner replaces its dot and reports **Simulation booting**, even if Playground physics is also enabled. A chevron on the selected mode indicates its status card; click to open it, or hover to preview it. With the mode selected, **Enter** opens and focuses its controls; **Escape** returns focus to the mode button. Without paired hardware, the Live card shows onboarding instead of an empty Edges status. Switch to **Edit**, choose **Add from Catalog** to add a robot or sensor, pair it with an edge device, then return to **Live**. **Ask assistant how to connect** opens the assistant and sends a setup question covering these steps. Boot indicators keep spinning while the status card is open. Idle recording controls are hidden by default. An active recording keeps **Recording · Stop & save** visible across modes, even when recording controls are hidden. In Simulate, choose **View → Show recording** to show or hide a separate recording bar on the right. It moves below the mode toolbar when space is limited, keeping the modes centered and unobstructed. Mode labels collapse to accessible icons when the space between the side panels is limited, and return when there is room. Click inside the card to keep it open while choosing an engine or adjusting settings; click outside or press Escape to close it.
The people icon beside the mode buttons shows open sessions, including your own other tabs. Hover or focus it to see who is editing, viewing, or using Simulation, Live, or Replay. Closed sessions disappear after a short timeout if they cannot disconnect cleanly.
Saved scene-order and group changes update other connected editors. Opening a mode does not lock the scene. If two people change the same hierarchy concurrently, the editor restores the latest saved version instead of silently overwriting someone else's work.
In a narrow workflow workbench, **Switch** opens the workflow list and **Show node library** opens the node picker. Both leave room for the canvas and restore the full sidebars when there is enough space.
## Adding Primitives
Moving or rotating a primitive keeps its template dimensions unchanged. Use **Scale** or the **Template** fields to resize it.
### Procedural walls and staircases
Select a procedural object to edit its **Template** section in the right inspector. Numeric values commit when you press Enter or leave the field, so you can type a complete decimal without resizing the scene at each keystroke. **Apply a layout preset** provides starting configurations from the catalog.
* **Wall Loop:** set room width/depth, wall height and thickness. Width/depth measure between wall centerlines; clear interior dimensions subtract one wall thickness. Flush corners preserve the existing outer footprint. Choose an **Open side** for a three-sided alcove, or a **Doorway side**, clear width/height and signed offset for a real opening in both rendering and physics. A doorway must fit between the corners and below the wall top, and cannot occupy the omitted side.
* **Wall Path:** edit numbered X/Y points in meters, inspect the footprint preview, then click **Apply footprint**. Enable **Close loop** for irregular rooms, or leave it off for L/U-shaped partitions. Right-angle joints are flush; angled joints use simple overlapping boxes, not CAD miters. Paths support up to 64 points.
* **Staircase:** choose a step count, riser height, tread depth, width and optional top landing. Examples include low training steps, indoor stairs and broad outdoor steps. Stairs ascend local +X; rotate the object to change direction. The terrain remains fixed in MuJoCo, with matching visible and collision steps.
Parameter edits preserve the ground anchor. Use position/rotation to place these structures; use their parameters to change dimensions. Terrain creation alone does not train or validate a robot policy.
### Catalog primitives
The **Add** menu (or the **+** button in the editor toolbar) includes a **Primitives** section. Primitives are curated public catalog assets with a short alias — things like cameras, lidars, and common generic objects — that you can drop into any environment in one click.
* **Where to find them:** open the 3D editor, click **Add → Primitives** (or the catalog icon in the sidebar) to browse the full list.
* **Why use them:** primitives are the fastest way to populate an environment. Because each primitive carries a short alias (e.g. `camera`, `lidar`), you can also instantiate them programmatically without knowing the full `vendor/slug` registry ID:
```python theme={null}
from cyberwave import Cyberwave
cw = Cyberwave()
# Browse available primitives and their aliases
for p in cw.assets.list_primitives():
print(p.registry_id_alias, "->", p.registry_id)
# Instantiate by alias — no catalog search needed
camera = cw.twin("camera")
lidar = cw.twin("lidar")
```
***
## Deleting scene objects
Delete the selected object with **Delete** or **Backspace**, from the trash
button in the right inspector, from **More actions → Delete** in the scene list,
or by right-clicking it in the 3D view. Selecting several objects and pressing
**Delete** removes them together after one confirmation.
**Ctrl/Cmd + Z** undoes the last delete in the same page session; a reload
clears the history. Deleting a procedural object is undoable from every entry
point — the shortcut, the inspector's trash button, the scene list and the
right-click menu — as is any multi-object delete. Restored twins and procedural
objects come back as new objects, so they do not return to the group they were
in; restored areas and waypoints do.
***
## Edge Core connection status (Live mode)
When you are in **Live** mode, the right-hand panel shows an Edge Core status indicator:
* **Green dot**: expected Edge Core instances are currently connected.
* **Gray dot**: one or more expected Edge Core instances are not currently connected.
Hover the dot to see:
* how many Edge Core instances are currently connected, and
* how many are expected for the environment.
Expected cores are derived from the unique edge fingerprints configured on twins in that environment.
***
## Twin presence indicator (Live mode)
In **Live** mode, every twin that has been paired to an edge device renders a small status dot overlaid on its kind icon. The dot consumes the same `edge_health` heartbeat that powers the Edge Devices status panel.
### States
| Color | Meaning |
| - | - |
| Green | Connected — heartbeat fresh and all streams healthy |
| Yellow | Degraded — heartbeat fresh but at least one stream unhealthy |
| Red | Disconnected — no recent heartbeat (tooltip shows last-seen age) |
| Gray | Checking — waiting for the first heartbeat after the panel mounts |
### Where you see it
* **Twin editor panel** (top-right, next to the twin name): a slightly larger dot for the focused twin.
* **Scene objects panel** (left list, on each twin row): a small corner dot on the kind icon.
The dot is hidden in Editor and Simulate modes, on splat twins, and on twins that have never been paired to an edge device — there is nothing to present for those.
Hover (or focus via keyboard) the dot for the tooltip: `Connected`, `Degraded — 1/2 streams healthy`, `Disconnected — last seen 12s ago`, or `Checking edge connection...`.
***
## Center the view on a twin
**Double-click a twin's row** in the scene objects panel to bring it into the middle of the view.
* **Single-click still just selects.** The camera only moves on a double-click, so you can click down a list of twins to read their properties without the viewport jumping around.
* **Your zoom is kept.** The view slides over to the twin at the distance and angle you were already working at, rather than zooming to fit it. Use **View → Center** when you do want the camera refitted.
* **Map mode pans the map** to the twin's location instead, at the current zoom.
* Double-clicking a twin's **name** still renames it — double-click anywhere else on the row to center.
Available to anyone who can see the environment, including read-only viewers.
***
## Twin joint edits in edit mode
In **Edit** mode, changing a twin joint updates the scene immediately, publishes the edit over MQTT for local feedback, and persists the joint pose on the twin so it survives refresh and reload.
***
## Twin position quick actions
In the environment editor transform panel, **Center** moves the selected twin or procedural object to the world origin. **Below**, **Above**, **Left**, and **Right** ask the Environment Editor to place it relative to the nearest suitable object or support using `cw_transform_environment_object`; floor/support placement uses `snap_to_support=true`.
***
## Semantic properties and route policy
Areas, procedural primitives, and twins can carry semantic properties on their
environment instance. Editing them does not change the source catalog asset.
* **Description for agents** adds bounded scene context. It helps assistants
understand intent but is not a deterministic safety rule.
* **Semantic tags** add structured meaning. `access:no-go` or
`access:restricted` on an area or primitive makes its geometry a planning
obstacle.
* Add one or more `asset:vendor/model` tags to scope that access policy to
matching assets. Without an `asset:*` tag, it applies to every asset.
* Semantic tags on a twin are descriptive. Put spatial access policy on an area
or primitive so the planner has geometry to constrain.
The editor preserves an unsaved draft if the API rejects a save and offers an
explicit retry. The Environment Agent and MCP tools update the same
`metadata.semantic_description` and `metadata.semantic_tags` fields with
revision checks, so natural-language and manual edits remain consistent.
See [Inspect areas with Move Twin](/feature-reference/workflows/inspect-area)
for examples, planner behavior, sensor FOV, and runtime safety boundaries.
***
## Twin override export controls
In the twin editor, **Twin overrides** lets you set per-twin appearance color, opacity, fixed-base behavior, and a total exported MuJoCo mass in kilograms. Cyberwave converts the total mass into proportional per-link scaling during MuJoCo export, and the editor shows an **Export warning** badge when the asset snapshot has incomplete inertial data that makes the export best-effort.
***
## Reorder root twins in Scene Objects
In **Edit** mode, the Scene Objects left pane supports drag-and-drop reordering for root twins using a grip handle. Child twins stay attached to their parent group and move with the parent when reordered.
* Reordering is available only when edit controls are enabled and search is not active.
* Order is saved to environment settings as `twin_order`, so it persists across reloads.
* Live stream cards in the right pane now follow the same persisted twin order.
***
## Simulate tab playground physics
In **Simulate → Playground**, Cyberwave now applies lightweight frontend physics with gravity and basic rigid collisions. URDF twins use their `` geometry as collision sources when available, and a fallback collider is used when collision metadata is missing.
***
## Start the agent from the Edit menu
In the 3D editor, open **Edit → Editor Agent** to launch the Environment Agent. It can inspect the current environment and call Cyberwave MCP tools for supported edits.
* The agent automatically provisions a workspace-scoped API key for the session so you can start chatting immediately.
* The agent displays a **Used tools** line for each response so you can verify which MCP tools were invoked.
***
## Workflow executions in an environment
In the environment editor, open **Executions → Workflow Executions** to review recent workflow runs bound to the current environment.
* The list stays compact by default and shows workflow name, status, and run time.
* Select a run to inspect trigger data, errors, and metadata.
* **Node Executions** stay collapsed behind **Show more** so the default view stays lightweight.
***
## Sensor coverage previews
In **Edit** and **Live** modes, the viewer draws each sensor's coverage envelope, matched to how that sensor actually sees the world:
| Sensor | Preview |
| - | - |
| RGB / depth cameras | Pinhole frustum from the camera's field of view and image aspect ratio |
| 2D lidar / laser scanners | Flat scan fan across the horizontal sweep |
| 3D / 4D lidar | Swept volume rounded at the sensor's full range, bounded above and below by its vertical spread |
| Radar | Cone |
Ranged sensors take their reach from `max_range`, and sweeps up to a full 360° are supported. A lidar with less than 180° of vertical spread does not cover straight up or straight down, so its envelope is closed off at the top and bottom rather than drawn as a full sphere. Sensors with no spatial coverage — IMU, GPS, compass, microphones — draw nothing. Each preview uses its sensor type's color; RGB and depth cameras are colored differently so overlapping cones on the same mount stay distinguishable.
Very long ranges are shortened so they don't swamp the scene. When that happens, the twin's sensor settings show **Preview extent** with both the drawn distance and the sensor's full range, so you can tell a truncated preview from a short-range sensor. Set a preview length override on the sensor to draw its full reach.
Control them from **View → Show sensor previews**, then **Sensor preview types** to toggle camera frustums, laser scan fans, lidar sweep volumes, and radar cones independently. The same submenu has **Only the selected twin**, which limits previews to the twin you have selected — deselect to see every twin's previews again. Per-sensor color and preview length can be overridden in the twin's sensor settings.
***
## Live point cloud alignment
In **Live** mode, depth-camera point clouds now keep the viewer's existing camera-local basis (`X` lateral, `Z` depth) while still honoring the sensor pose and offset, so RealSense clouds stay vertically aligned in front of the sensor after refresh and axis migrations.
***
## Clone an environment
Use **File → Make a copy** to duplicate the current environment.
* The copy includes the environment and all of its twins.
* The copy is created in the same workspace and project as the original, regardless of which workspace you were last browsing.
* If the environment was shared with you and you are not a member of its workspace, the copy is created in your own workspace instead, outside any project.
* Historical telemetry/session data is not copied.
* Lineage references are stored in metadata for future tracking:
* environment settings include `cloned_from_environment_uuid`
* each twin metadata includes `cloned_from_twin_uuid`
***
## Ready to Build?
Start creating immersive environments for your robots and unlock the full potential of simulation-based development.
Start building your environment now
Control environments programmatically
Learn about digital twins
Control physical robots in real time from the environment
Automate robot operations with visual workflows
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.