# splintered-reality/py_trees architecture

> Architecture diagram of the GitHub repository splintered-reality/py_trees, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/splintered-reality/py_trees
- Repository: https://github.com/splintered-reality/py_trees

## Overview

PyTrees is a Python behavior-tree library for decision-making engines, including robotics. A developer assembles a tree from behaviors and control-flow nodes, then the tree manager sets it up and ticks its root; statuses and shared blackboard data represent runtime progress and state. Trees may also be declared in XML using ports and remappings, and inspected through terminal or graph displays. The graph reflects README capabilities and sampled wiring; unsampled modules are included only where their role is documented, with uncertain call links omitted.

Main entry points: [`py_trees/behaviour.py`](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/behaviour.py) (Behaviour lifecycle), [`py_trees/trees.py`](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/trees.py) (Tree manager), [`py_trees/composites.py`](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/composites.py) (Control composites), [`py_trees/blackboard.py`](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/blackboard.py) (Blackboard store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tree_runtime["Tree execution"]
  node_tree["Tree manager<br/>[trees.py]"]
  node_behaviour["Behaviour lifecycle<br/>[behaviour.py]"]
  node_composites["Control composites<br/>[composites.py]"]
  node_decorators["Decorators<br/>[decorators.py]"]
  node_behaviours["Built-in behaviours<br/>[behaviours.py]"]
  node_idioms["Tree idioms<br/>[idioms.py]"]
  node_common["Statuses and policies<br/>[common.py]"]
end

subgraph group_state_data["Shared data"]
  node_blackboard[("Blackboard store<br/>[blackboard.py]")]
  node_ports["Ports and remapping<br/>[ports.py]"]
  node_port_utils["Port utilities<br/>[ports_utils.py]"]
end

subgraph group_tree_authoring["Tree authoring"]
  node_xml_parser["XML tree parser"]
end

subgraph group_inspection["Inspection tools"]
  node_visitors["Tree visitors<br/>[visitors.py]"]
  node_display["Tree and state display<br/>[display.py]"]
  node_render_cli["Tree render command<br/>[render.py]"]
  node_logging["Runtime logging<br/>[logging.py]"]
end

node_developer(("Application developer"))
node_result(("Decision outcomes"))

node_developer -->|"assembles and ticks"| node_tree
node_tree -->|"sets up and ticks"| node_behaviour
node_behaviour -->|"extended by"| node_composites
node_behaviour -->|"wrapped by"| node_decorators
node_composites -->|"ticks children"| node_behaviour
node_decorators -->|"ticks child"| node_behaviour
node_behaviours -->|"implements"| node_behaviour
node_idioms -->|"builds patterns"| node_behaviour
node_tree -->|"uses statuses"| node_common
node_composites -->|"uses policies"| node_common
node_behaviour -->|"attaches clients"| node_blackboard
node_behaviours -->|"reads and writes"| node_blackboard
node_ports -->|"maps port data"| node_blackboard
node_xml_parser -->|"constructs nodes"| node_composites
node_xml_parser -->|"configures ports"| node_ports
node_xml_parser -->|"constructs nodes"| node_behaviours
node_port_utils -->|"searches tree"| node_behaviour
node_tree -->|"dispatches visits"| node_visitors
node_display -->|"reads state"| node_blackboard
node_render_cli -->|"renders tree"| node_display
node_tree -->|"produces statuses"| node_result
node_display -->|"presents progress"| node_result
node_behaviour -->|"records events"| node_logging

click node_tree "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/trees.py"
click node_behaviour "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/behaviour.py"
click node_composites "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/composites.py"
click node_decorators "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/decorators.py"
click node_behaviours "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/behaviours.py"
click node_idioms "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/idioms.py"
click node_blackboard "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/blackboard.py"
click node_ports "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/ports.py"
click node_port_utils "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/ports_utils.py"
click node_common "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/common.py"
click node_xml_parser "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/parsers/behaviour_tree_xml.py"
click node_visitors "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/visitors.py"
click node_display "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/display.py"
click node_render_cli "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/programs/render.py"
click node_logging "https://github.com/splintered-reality/py_trees/blob/devel/py_trees/logging.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tree,node_behaviour,node_composites,node_decorators,node_behaviours,node_idioms,node_common toneBlue
class node_blackboard,node_ports,node_port_utils toneAmber
class node_xml_parser toneMint
class node_visitors,node_display,node_render_cli,node_logging toneRose
class node_developer,node_result toneIndigo
```

## Components

### Tree execution

- [Tree manager](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/trees.py): `py_trees/trees.py`
- [Behaviour lifecycle](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/behaviour.py): `py_trees/behaviour.py`
- [Control composites](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/composites.py): `py_trees/composites.py`
- [Decorators](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/decorators.py): `py_trees/decorators.py`
- [Built-in behaviours](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/behaviours.py): `py_trees/behaviours.py`
- [Tree idioms](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/idioms.py): `py_trees/idioms.py`
- [Statuses and policies](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/common.py): `py_trees/common.py`

### Shared data

- [Blackboard store](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/blackboard.py): `py_trees/blackboard.py`
- [Ports and remapping](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/ports.py): `py_trees/ports.py`
- [Port utilities](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/ports_utils.py): `py_trees/ports_utils.py`

### Tree authoring

- [XML tree parser](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/parsers/behaviour_tree_xml.py): `py_trees/parsers/behaviour_tree_xml.py`

### Inspection tools

- [Tree visitors](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/visitors.py): `py_trees/visitors.py`
- [Tree and state display](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/display.py): `py_trees/display.py`
- [Tree render command](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/programs/render.py): `py_trees/programs/render.py`
- [Runtime logging](https://github.com/splintered-reality/py_trees/blob/devel/py_trees/logging.py): `py_trees/logging.py`

### Other components

- **Application developer**
- **Decision outcomes**

## Connections

- Application developer → Tree manager: assembles and ticks
- Tree manager → Behaviour lifecycle: sets up and ticks
- Behaviour lifecycle → Control composites: extended by
- Behaviour lifecycle → Decorators: wrapped by
- Control composites → Behaviour lifecycle: ticks children
- Decorators → Behaviour lifecycle: ticks child
- Built-in behaviours → Behaviour lifecycle: implements
- Tree idioms → Behaviour lifecycle: builds patterns
- Tree manager → Statuses and policies: uses statuses
- Control composites → Statuses and policies: uses policies
- Behaviour lifecycle → Blackboard store: attaches clients
- Built-in behaviours → Blackboard store: reads and writes
- Ports and remapping → Blackboard store: maps port data
- XML tree parser → Control composites: constructs nodes
- XML tree parser → Ports and remapping: configures ports
- XML tree parser → Built-in behaviours: constructs nodes
- Port utilities → Behaviour lifecycle: searches tree
- Tree manager → Tree visitors: dispatches visits
- Tree and state display → Blackboard store: reads state
- Tree render command → Tree and state display: renders tree
- Tree manager → Decision outcomes: produces statuses
- Tree and state display → Decision outcomes: presents progress
- Behaviour lifecycle → Runtime logging: records events