Worlds and objects

Two nouns do most of the work in this section, and they are not the same thing.

An object is a kind of physical thing: a plate, a tip box, a holder. It describes shape and structure, not position. Objects live in a shared mesh database, and you pull the ones you need into your project. Each one lands at objects/<name>/ as two files: <name>.urdf for the kinematic and visual structure, and <name>.object_model.yaml for the parts, articulations, and anchors layered on top of it.

A world is a scene. It records which objects are on the bench and where each one sits. A world lives at worlds/<name>/world_state.json, and its objects block is the placement list: an entry per object instance, with a pose. Pulling an object into your project does not put it in a world. Those are two separate steps, and confusing them is the usual reason a workflow cannot find something it expects.

A workflow runs against a world. The world supplies the objects the skills reach for. So the order of work is fixed:

Get the object into your project.
Place it in a world.
Point a workflow at that world.

🧭
One object definition, many placements. Bring tip_box into your project once, then place three instances of it in a world at three different poses. The definition under objects/ is shared; the poses live in the world.

Anchors tie this to skills

An object carries named frames called anchors. Every object model declares at least one, object, which is the object's own reference frame. Real objects add more: a well, a slot, a grip point.

This matters because a skill targets an anchor by name, not by coordinate. A skill says "move to the grip anchor on this object" and the runtime resolves that name against whatever pose the object has in the current world. Change the placement in the world and the skill still works, because the coordinate was never written into the skill. That is the whole reason worlds and skills stay decoupled.

Read Anchors before you author a skill that touches an object.

Where to start

Building a world

Create a world, add objects to the scene, and set their poses.

Adding an object

Bring an object from the mesh database into your project.

The mesh database

What the shared library holds and how to search it.

File formats

When you need to read or hand-edit what these steps produce:

File	Covers
`worlds/<name>/world_state.json`	Scene config, the object placement list, metadata.
`objects/<name>/<name>.object_model.yaml`	Parts, articulations, and anchor definitions.

If a workflow run fails because a skill could not resolve an object, the fault is almost always in the world rather than the skill. Open the world first and check the object is actually placed in it.