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:
| Format | How to recognise it | Written by | Behaviour |
|---|---|---|---|
| Starting layout | "version": "3.0", no format key | You, zeon new world, the starter project | Loaded 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 World | Loaded 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:
| Field | Description |
|---|---|
mount.type | Must be FixedMount. An entry with any other mount is skipped. |
mount.world_P_body_fixed | The 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.type | articulated (an object type) or Cuboid (a box). Any other type is skipped. |
metadata.type | The object type for an articulated entry. When it is absent, the type is taken from geometry.yaml_path (objects/<type>/...). |
geometry.dims, geometry.color | For 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. |
metadata | Kept 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"}
}
}
}| Field | Description |
|---|---|
format | zeon_world_state/2. |
world | The .world file of this folder. |
cell | The setup the world was saved on. |
metadata.name | The name typed in the save dialog. The list of saved worlds shows it. |
metadata.description | The description from the save dialog. |
metadata.created_at, metadata.updated_at | Local timestamps. updated_at appears after an in-place update. |
metadata.source | manual for a world saved by name. |
objects.<id>.type | The object type (primitive for a box such as a table). |
objects.<id>.name, index, tag_collection | The instance's display name, index and tagged unit. |
objects.<id>.parent | What 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
Updated 9 days ago