The World Builder
Screen reference: add objects to the live scene, place them, and save and load worlds.
The World Builder edits the live sim scene on your instance and saves it as a world of your project. Open it from World Builder in the sidebar or the Build World tile on the home screen. It is not available in operator mode.
For the concepts (instances, tables, the two world formats) read Building a world first.
The screen has two tabs: Create in Sim and Saved Worlds.
Create in Sim
Three columns: objects on the left, the 3D view in the middle, the transform panel on the right.
Add Objects
| Control | What it does |
|---|---|
| Object picker (Select object...) | Lists the object types of the mesh-database catalog your organization can see. |
| Tagged unit | Appears only when the chosen type has two or more tagged units. Records which physical copy this instance is (see Localizing an object). |
| Add to Scene | Adds an instance of the type at x = 0.4, y = -0.3, z = 0.05 m. If your project has no copy of the type, its URDF, object model and tag files are first copied into objects/<type>/ and committed as Materialize object <type>. |
After an add, the picker clears. Errors appear in a red box under the panel. On a deployed box an Add + Localize button sits next to Add to Scene.
Scene Objects (N)
The instances in the scene, by display name, with index: N when an index is set. The table named table is not listed. Click a row to select the object in the 3D view and in the transform panel; clicking an object in the 3D view highlights its row.
The row menu (⋮) offers:
- Edit name / index: a Name field and an Index (optional) field. Duplicate names are allowed; numeric indexes are stored as integers; an empty index removes it.
- Remove from scene: removes the instance and its entry in
live_state.yaml. The table namedtablecannot be removed, and neither can an object that an arm holds or that has something seated on it. - Re-localize (hand-guided): deployed boxes only.
World Editor
| Control | What it does |
|---|---|
| Hide Gizmos / Show Gizmos | Shows or hides the drag handles on objects and arm targets, and the ground grid. |
| 3D view | The sim viewport. See The 3D viewport. |
| Save World | Opens the save dialog. |
| Reset | Removes every object from the scene except the tables, immediately and without confirmation. |
Reset does not unload the world you loaded. Clicking Update in the save dialog afterwards rewrites that world with the emptied scene. Use Save as new or reload the world instead.
Object Transform
Transform Controls edits the pose of one object:
- Pick it in Select Object, or click its row in Scene Objects.
- Load Current Pose fills the fields with its current pose.
- Edit X, Y, Z (metres) and Roll, Pitch, Yaw (radians). The pose is that of the object's
objectanchor in the world frame. - Update Transform moves the object.
Placement does not check for collisions. Moving an object that sits on a holder takes it off the holder and puts it on the world.
Advanced
The Advanced switch above the transform panel shows more panels:
- Left Arm / Right Arm, one per arm of your setup: Plan to Target and Move to Target for the arm's target gizmo in the 3D view; after planning, Preview Trajectory, Execute Plan and Cancel Plan. Gripper Opening (m) sets the gripper. Advanced Controls sets the target gizmo from a TCP pose
[x, y, z, roll, pitch, yaw](Apply TCP) or from joint angles (Apply Joints); these move the target, not the arm. - Object Controls → Object Attachment: Attach the selected object to an arm's TCP, or Detach it.
- World Controller → Camera Controls for each wrist camera, and Dev Tools: the TCP pose and joint angles of each arm (Refresh, or Auto to poll every second).
These act on the sim arms.
Saved Worlds
The worlds in your project's worlds/ folder, sorted by folder name in reverse alphabetical order. Refresh re-reads the list. Each card shows:
- the world's name (the folder name when the world has none),
- its description, or No description,
- N objects, counting tables,
- the creation time,
- Created manually or From execution,
- Load into Editor, which loads the world into the sim and switches to Create in Sim.
A starting layout (world_state.json without the saved-world format) loads read-only; save it as a new world to keep changes.
Load errors and objects left out because their type was not found are not shown on this screen. zeon up --world <id> and zeon brief report them; see Building a world.
There is no delete or rename here. To delete a world, delete its folder in your working tree and sync.
The save dialog
| Element | Behaviour |
|---|---|
| World Name | Prefilled with the loaded world's name. Its sanitized form names a new folder. |
| Description (Optional) | Stored in the world's metadata. Not prefilled. |
| Later | Closes the dialog. |
| Save as new | Saves to a new folder. An existing folder name gets a timestamp appended; the loaded world is left untouched. |
| Update <name> | Rewrites the loaded world in place, keeping its name and creation time. The description entered replaces the stored one, so an empty field clears it. Disabled when no world is loaded. |
Both saves commit the world folder to the cloud project as Save world <id>. On success the dialog closes. Messages you may see:
| Message | Meaning |
|---|---|
Project changed during save, refresh and retry. | Someone pushed to the project first. Nothing was committed. |
'<id>' is an old (v1) world and is read-only; save it as a new world | Update on a starting layout. |
World '<id>' was loaded without N object(s) whose type did not load here: ... | Update would delete those objects from the saved world. Restore their types and reload, or save as new. |
World saved locally but not committed to sync. Reopen the project to retry. | The folder was written on your instance but not committed. |
Save as new copies the loaded world's live_state.yaml into the new folder, and the success message then says that tip counts and calibration were carried over.
Inside the 3D view
The viewport has its own floating panel, collapsed by default, and direct manipulation:
- Click an object to select it and show its gizmo, then drag to move it.
- Double-click an object for a menu: Snap to table, Snap to right angle, Duplicate, Reset to home, Undo, Redo, and the toggles Auto-drop on release, Grid snap on release (with Grid step (m)) and Planar lock.
- Select an articulated object to get Articulation: <name> in the panel: a slider per joint, and Preset with Apply preset when the object has presets. This is where you set a lid or drawer before saving.
The panel's Scene Editor → Object Library can also add objects, but it does not copy the type into your project. Use Add to Scene in the left column so the world and the project stay consistent.
Related
Updated 9 days ago