Task File Format

A task file is a YAML document that defines a sequence of verb steps the robot executes in order. The verb compiler reads it alongside an RDF file and produces a BehaviorTree.CPP XML file.

---

Structure

name: PatrolTask                   # Required. Used as the BT tree name.
description: "Optional description"

steps:
  - verb: go_to                    # Required. Must match a verb in the verb library.
    params:
      x: 1.0
      y: 0.0
      theta: 0.0
  - verb: report
    params:
      message: "arrived_at_wp1"
  - verb: wait
    params:
      duration: 2.0

Top-level fields

Field	Type	Required	Description
name	string	yes	Task name. Becomes the BT tree root name in the emitted XML.
description	string	no	Human-readable description. Not used during compilation.
steps	list	yes	Ordered list of verb steps to execute.

Step fields

Field	Type	Required	Description
verb	string	yes	Verb name. Must match a .yaml file in the verb library.
params	dict	no	Parameters passed to the verb's Jinja2 template.

If params is omitted, the verb's default values apply. If a required parameter is missing, compilation fails.

---

Compiling a task

defined compile tasks/patrol.task.yaml \
    --rdf robot.rdf.yaml \
    -o patrol.bt.xml

To use a custom verb directory instead of the built-in library:

defined compile tasks/patrol.task.yaml \
    --rdf robot.rdf.yaml \
    --verbs-dir verbs/ \
    -o patrol.bt.xml

---

POI references

Instead of hardcoding coordinates, you can reference named Points of Interest from the world model using $world.pois.<name>:

name: PatrolPOIs
description: "Patrol named Points of Interest"

steps:
  - verb: go_to
    params:
      target: $world.pois.survey-1
  - verb: report
    params:
      message: "arrived_survey_1"
  - verb: go_to
    params:
      target: $world.pois.dock
  - verb: report
    params:
      message: "patrol_complete"

The $world.pois.<name> reference is resolved at compile time by looking up the POI in the world state. The POI's x and y coordinates are substituted into the verb parameters.

Note

POIs must be defined before compilation — either via a world YAML file or through defined world add. See the World System guide for details.

---

Complete example: patrol with waypoints

name: PatrolTask
description: "Simple patrol between two waypoints"

steps:
  - verb: go_to
    params:
      x: 1.0
      y: 0.0
      theta: 0.0
  - verb: report
    params:
      message: "arrived_at_wp1"
  - verb: wait
    params:
      duration: 2.0
  - verb: go_to
    params:
      x: 0.0
      y: 0.0
      theta: 0.0
  - verb: report
    params:
      message: "patrol_complete"

---

Complete example: explore then return

name: ExploreAndReturn

steps:
  - verb: explore
    params:
      timeout: 120.0
  - verb: report
    params:
      message: "exploration_complete"
  - verb: go_to
    params:
      x: 0.0
      y: 0.0
      theta: 0.0

---

Compilation output

The compiler produces a BehaviorTree.CPP XML file. For the patrol example above:

<root BTCPP_format="4" main_tree_to_execute="PatrolTask">
  <BehaviorTree ID="PatrolTask">
    <Sequence>
      <RetryUntilSuccessful num_attempts="3">
        <Action ID="GoTo" name="go_to_1.0_0.0"
            x="1.0" y="0.0" theta="0.0"
            frame_id="map" server_name="/navigate_to_pose" timeout="60.0" />
      </RetryUntilSuccessful>
      <Action ID="Report" message="arrived_at_wp1" topic="/task_reports" level="info" />
      <Action ID="Wait" duration="2.0" />
      ...
    </Sequence>
  </BehaviorTree>
</root>