The world state file

A world is a folder at worlds/<id>/. The required file is world_state.json; worlds built from a camera scan carry sidecar files beside it.

You author worlds in the World Builder, not by hand. This page is for reading the file and understanding what the fields mean.

Minimal example

A fresh world from zeon new world my_world:

{
  "version": "2.0",
  "config": {
    "tensor_device": "cuda",
    "enable_blox": false,
    "create_workspace_boundaries": false
  },
  "objects": {},
  "metadata": {
    "name": "my_world",
    "description": "",
    "source": "manual"
  }
}

Top-level fields

config

Set by the World Builder. You rarely edit these by hand.

objects

A map of the objects placed in the scene. Each key is the instance name. Objects the World Builder places are keyed <type>_<uuid>, so the same object type can appear several times in one scene. Fixtures added by hand tend to keep plain names like table.

A placed project object. The pose values are shortened for readability. Real files carry full double precision, and the instance key carries a full UUID:

"fixture_plate_9e3b532c-…": {
  "geometry": {
    "type": "articulated",
    "yaml_path": "objects/fixture_plate/fixture_plate.object_model.yaml"
  },
  "mount": {
    "type": "FixedMount",
    "world_P_body_fixed": {
      "xyz": [0.605, 0.403, 0.0],
      "wxyz": [1.0, 0.0, 0.0, 0.0],
      "stamp_s": null
    }
  },
  "enabled": true,
  "filter_from_depth": true,
  "collide_in_planner": true,
  "attachment_spec": {
    "fit_type": "voxel_volume_sample_surface",
    "surface_sphere_radius": 0.001,
    "voxelize_method": "ray"
  },
  "metadata": {
    "name": "fixture_plate",
    "location": "fixture_plate",
    "type": "fixture_plate"
  },
  "joint_config": {}
}

Object fields

Every field above except joint_config is read by direct key access. Omitting one is a load error, not a defaulted value.

geometry

Two shapes appear, distinguished by the type tag:

A project object, from your objects/ folder or the mesh database:

{ "type": "articulated", "yaml_path": "objects/fixture_plate/fixture_plate.object_model.yaml" }

The yaml_path points at the object's object_model.yaml. It is stored in this portable, project-relative form on purpose; the absolute path is worked out at load time and never written back to the file, so a world stays valid on another machine. Older worlds instead have an absolute container path baked in, like /app/storage/mesh_database/<name>/<name>.object_model.yaml. Both resolve.

A primitive, a synthetic shape used for tables, filters, and workspace walls:

{ "type": "Cuboid", "name": "x_min", "pose": { "xyz": [-1.36, -0.36, 0.35], "wxyz": [1, 0, 0, 0], "stamp_s": null }, "dims": [0.02, 2.9, 1.7] }

The registered primitive types are Cuboid, Sphere, Cylinder, Capsule, Mesh, and VoxelGrid. An unrecognized type is a load error.

mount

FixedMount is the only mount type a saved world may contain. Any other value raises an error on load. It carries world_P_body_fixed with three keys: xyz (metres), wxyz (quaternion, scalar first), and stamp_s (null in every saved world).

Workspace boundaries

When create_workspace_boundaries is on, the World Builder adds six primitives named x_min, x_max, y_min, y_max, z_min, and z_max, invisible cuboids at the AABB faces. Those six names are reserved and special-cased by the loader, which can skip them on request. Don't edit them by hand; they're regenerated when the AABB changes.

metadata

source is shown in the world list as Created manually or From execution.

Sidecar files

A world built from a camera scan carries binary sidecars beside world_state.json:

One more sidecar appears on any world, scanned or not:

Commit all of them like any other file. Don't edit the binaries: they are written by the platform and have no hand-editable form.

live_state.yaml is the exception: it is meant to be hand-edited during calibration. A YAML typo there fails with a clear error naming the file rather than an opaque parser error inside a skill.

When the file is wrong

Malformed JSON does not surface as a clean "this world is broken" message. The world list swallows the parse error and still shows the world, labelled with a title-cased version of the folder name (my_world appears as "My World") and an object count of 0. The raw folder name survives as the world's id. The failure surfaces when you load it: the path resolver logs a warning and hands the file to the loader, which fails on the same malformed JSON.

A referenced object that doesn't exist is more forgiving: the path resolver catches per-object failures and logs a warning, so one missing mesh doesn't fail the whole world load. The world opens without that object.

See also