World System¶

A world file defines the spatial context in which a robot operates: named locations (Points of Interest), optional zone boundaries, and simulation environment settings. The world is one of three inputs the toolchain uses — alongside the RDF and task files.

World YAML format¶

name: maze_10x10
description: >
  A 10m x 10m room with internal maze walls.
  Good for testing navigation in confined spaces.

pois:
  dock:
    x: 0.0
    y: 0.0
    type: constant
    description: Home/charging station
  survey-1:
    x: 2.0
    y: 1.5
    type: static
    description: First survey point (near maze entrance)
  survey-2:
    x: 3.0
    y: -1.5
    type: static
    description: Second survey point
  survey-3:
    x: 1.0
    y: -3.0
    type: static
    description: Third survey point (far end of maze)

sim:
  environment: maze_10x10     # Gz Sim world file to load
  spawn:
    x: 0.0
    y: 0.0
    yaw: 0.0

Top-level fields¶

Field	Type	Required	Description
`name`	string	yes	World identifier
`description`	string	no	Human-readable description
`pois`	dict[string, POI]	no	Named Points of Interest
`zones`	dict	no	Zone boundaries (parsed, not enforced in v0.1.0)
`sim`	SimEnvironment	no	Simulation configuration

POI fields¶

Field	Type	Required	Default	Description
`x`	float	yes	—	X coordinate in the map frame (meters)
`y`	float	yes	—	Y coordinate in the map frame (meters)
`type`	string	no	`static`	POI type: `constant`, `static`, or `dynamic`
`description`	string	no	`""`	Human-readable label

SimEnvironment fields¶

Field	Type	Required	Description
`environment`	string	yes	Gz Sim world name to load
`spawn.x`	float	no	Robot spawn X (default: 0.0)
`spawn.y`	float	no	Robot spawn Y (default: 0.0)
`spawn.yaw`	float	no	Robot spawn yaw in radians (default: 0.0)

POI types¶

POIs have three types that reflect how they change over time:

Type	Meaning	Example
`constant`	Fixed forever — hard-coded from the world file	Dock/charging station, door frames
`static`	Defined in the world file but can be updated at runtime	Survey waypoints, named rooms
`dynamic`	Created at runtime (e.g. via `defined world mark`)	Anomaly locations, transient goals

The type is informational in v0.1.0 — it is stored in the blackboard but does not affect task compilation or execution differently. It is intended to support capability gating and spatial queries in future milestones.

How POIs are resolved at compile time¶

When you reference $world.pois.<name> in a task file, the compiler resolves it against the world state before rendering the BT XML.

Task step:

- verb: go_to
  params:
    target: $world.pois.survey-1

The compiler looks up survey-1 in the world model and substitutes its x and y into the verb parameters. If the POI does not exist, compilation fails with a clear error.

To use a world file during compilation:

defined compile tasks/patrol_pois.task.yaml \
    --rdf robot.rdf.yaml \
    --world worlds/maze.yaml \
    -o patrol.bt.xml

Managing POIs via CLI¶

You can manage the world state directly without editing YAML files.

Add a POI at known coordinates¶

defined world add dock 0.0 0.0 --type constant
defined world add survey-1 2.0 1.5 --type static
defined world add survey-1 2.0 1.5 --type static --radius 0.75

List all defined POIs¶

defined world list

Output:

          Points of Interest
┌──────────┬───────┬────────┬──────────┬────────┐
│ Name     │     X │      Y │ Type     │ Radius │
├──────────┼───────┼────────┼──────────┼────────┤
│ dock     │ 0.000 │  0.000 │ constant │    0.5 │
│ survey-1 │ 2.000 │  1.500 │ static   │    0.5 │
│ survey-2 │ 3.000 │ -1.500 │ static   │    0.5 │
└──────────┴───────┴────────┴──────────┴────────┘

Mark the robot's current position as a POI¶

Requires a running rosbridge server (--host, --port default to localhost:9090):

defined world mark survey-4
defined world mark survey-4 --type static --radius 0.5 --host localhost --port 9090

Watch for map clicks and save as POIs¶

Opens an interactive prompt that saves each map click as a named POI:

defined world watch
defined world watch --type static --radius 0.5

Press Ctrl+C to stop watching.

State persistence¶

POIs added via the CLI are persisted in ~/.defined/state.yaml. The world state survives across sessions — you do not need to re-add POIs each time you run the CLI.

World YAMLs loaded at startup via --world (or the manifest world: field) are merged into the existing state, not replaced. Existing POIs with the same name are overwritten by the world file values.

Example: loading a world on startup¶

With a manifest file (robot.manifest.yaml):

rdf: robot.rdf.yaml
world: worlds/open_room.yaml

When you run defined, the world is loaded automatically and its POIs seeded into the blackboard before any task starts.