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

ControlWhat it does
Object picker (Select object...)Lists the object types of the mesh-database catalog your organization can see.
Tagged unitAppears only when the chosen type has two or more tagged units. Records which physical copy this instance is (see Localizing an object).
Add to SceneAdds 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 named table cannot 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

ControlWhat it does
Hide Gizmos / Show GizmosShows or hides the drag handles on objects and arm targets, and the ground grid.
3D viewThe sim viewport. See The 3D viewport.
Save WorldOpens the save dialog.
ResetRemoves 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:

  1. Pick it in Select Object, or click its row in Scene Objects.
  2. Load Current Pose fills the fields with its current pose.
  3. Edit X, Y, Z (metres) and Roll, Pitch, Yaw (radians). The pose is that of the object's object anchor in the world frame.
  4. 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

ElementBehaviour
World NamePrefilled with the loaded world's name. Its sanitized form names a new folder.
Description (Optional)Stored in the world's metadata. Not prefilled.
LaterCloses the dialog.
Save as newSaves 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:

MessageMeaning
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 worldUpdate 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


Did this page help you?