worlds/<id>/world_state.json

The two world formats: the hand-written starting layout and the saved world.

Every world is a folder worlds/<id>/ with a world_state.json in it. The folder name is the world id. The file comes in two formats, and which one a folder holds decides how it behaves:

FormatHow to recognise itWritten byBehaviour
Starting layout"version": "3.0", no format keyYou, zeon new world, the starter projectLoaded read-only. Changes made in the app are saved as a new world.
Saved world"format": "zeon_world_state/2"The World Builder's Save WorldLoaded from the world.world file beside it. Can be updated in place.

A folder may hold one world.

Starting layout

This is the format to write by hand. zeon new world my_world writes one with a front and a back table (excerpt; ... marks omitted content):

{
  "version": "3.0",
  "config": { ... },
  "objects": {
    "table": {
      "geometry": {"type": "Cuboid", "name": "table", "dims": [0.76, 1.52, 0.05], "color": [0.6, 0.4, 0.2]},
      "mount": {
        "type": "FixedMount",
        "world_P_body_fixed": {"xyz": [0.26, 0.0, -0.025], "wxyz": [1.0, 0.0, 0.0, 0.0], "stamp_s": null}
      },
      "metadata": {"name": "table", "role": "table"}
    },
    "table_back": { ... }
  },
  "metadata": {"name": "my_world", "description": "", "source": "manual"}
}

An object entry from the starter's shaker_deck world:

"wellplate_shaker": {
  "geometry": {
    "type": "articulated",
    "yaml_path": "objects/wellplate_shaker/wellplate_shaker.object_model.yaml"
  },
  "mount": {
    "type": "FixedMount",
    "world_P_body_fixed": {"xyz": [-0.54, 0.02, 0.0], "wxyz": [0.707106781, 0.0, 0.0, 0.707106781], "stamp_s": null}
  },
  "metadata": {"name": "wellplate_shaker", "type": "wellplate_shaker"},
  "joint_config": {"lid_joint": 0.0}
}

What the loader reads

The key of each entry under objects is the instance id. For each entry the loader reads:

FieldDescription
mount.typeMust be FixedMount. An entry with any other mount is skipped.
mount.world_P_body_fixedThe pose of the object's object anchor in the world: xyz in metres, wxyz a quaternion with the scalar first. This is the only pose that is read.
geometry.typearticulated (an object type) or Cuboid (a box). Any other type is skipped.
metadata.typeThe object type for an articulated entry. When it is absent, the type is taken from geometry.yaml_path (objects/<type>/...).
geometry.dims, geometry.colorFor a Cuboid: size in metres and RGB colour (0 to 1). The box is centred on the mount pose.
joint_config{joint_name: value} for an articulated object.
metadataKept on the instance: name (the display name skills can resolve), index, tag_collection, role.

Everything else is not used to build the world: the config block, geometry.pose, attachment_spec, stamp_s. When geometry.pose and mount.world_P_body_fixed disagree, the mount wins. Change the mount when you move an object by hand.

Ids x_min, x_max, y_min, y_max, z_min, z_max, left_base_filter and right_base_filter are skipped; older worlds used them for workspace walls.

Tables

A Cuboid entry is a table when its metadata.role is "table", or, without a role, when its id is table or starts with table_. A world owns its tables: the setup adds none. A world that defines no table loads with a warning and gives motion no work surface under the arms. Other Cuboid entries are plain box obstacles.

Object types

An articulated entry resolves its type from the project's objects/<type>/ first, then from the mesh-database catalog your organization can see. An entry whose type resolves nowhere is left out of the loaded world and reported as missing; the rest of the world still loads. See Building a world.

Saved world

When you save a world in the World Builder, its folder holds:

worlds/bench_layout/
├── world_state.json          # manifest (zeon_world_state/2)
├── world.world               # the saved scene (zeon_world/2)
├── world.world.engine.json   # per-instance type, metadata and seat
└── live_state.yaml           # optional, see live_state.yaml

world.world and world.world.engine.json are written by the platform. Do not edit them by hand. On load, every object is rebuilt from its type name, so the files carry no mesh paths. world_state.json is derived from them on every save and is not read back into the world; the app lists worlds from it.

{
  "format": "zeon_world_state/2",
  "world": "world.world",
  "cell": "...",
  "metadata": {
    "name": "Bench layout",
    "description": "",
    "created_at": "2026-11-08T10:15:02.118734",
    "source": "manual"
  },
  "objects": {
    "wellplate_96_flatbottom_2f6c0f3e-...": {
      "type": "wellplate_96_flatbottom",
      "name": "wellplate",
      "index": null,
      "tag_collection": null,
      "parent": "wellplate_stand_1/top_center",
      "seat": {"holder": "wellplate_stand_1", "anchor": "top_center", "style": "aligned"}
    }
  }
}
FieldDescription
formatzeon_world_state/2.
worldThe .world file of this folder.
cellThe setup the world was saved on.
metadata.nameThe name typed in the save dialog. The list of saved worlds shows it.
metadata.descriptionThe description from the save dialog.
metadata.created_at, metadata.updated_atLocal timestamps. updated_at appears after an in-place update.
metadata.sourcemanual for a world saved by name.
objects.<id>.typeThe object type (primitive for a box such as a table).
objects.<id>.name, index, tag_collectionThe instance's display name, index and tagged unit.
objects.<id>.parentWhat the object hangs on: world, or <holder id>/<anchor> when it is seated.
objects.<id>.seat{holder, anchor, style} when the object is seated on a holder's anchor, else null.

See also


Did this page help you?