Behavior Tree Reference

Behavior Tree Reference#

Project: game.xml

Robot: RoboCup Soccer Robot

Overview#

The tree is a single root Sequence. On startup a RunOnce sets control_state=3 (auto mode). Three priority blocks are checked top-to-bottom every tick via ReactiveSequence _while. The first block whose condition is true wins; all lower-priority blocks are skipped.

Control States — Priority Order#

State 1 — Manual / Assist Mode (highest priority)#

Active when: control_state==1 or assist_kick or go_manual or assist_chase

Go manual	Any joystick axis >0.1 → direct velocity control. LX/LY = move, RX = rotate.
Assist chase	Hold LB → `SimpleChase` at vx=1.5 with no braking distance.
Assist kick	Hold RB → `Kick` at speed=0.9, minimum 1000ms duration.
Enter	LT+X sets `control_state=1`
Exit	Release all conditions, or press LT+B

Three independent branches: go manual, assist chase, assist kick.

State 2 — Recalibrate / Re-enter Mode#

Active when: control_state==2

If !calibrated	`CamScanField` — rotate head to find landmarks and localize via particle filter.
If calibrated	`CamFindAndTrackBall` — keep eyes on ball ready to resume.
Parallel	`SelfLocateEnterField` runs throughout — walks to re-entry position.
Enter	LT+A sets `control_state=2`
Exit	Operator presses LT+B (no automatic exit)

Localization loop: scan field until calibrated, then track ball.

State 3 — Full Auto Mode (default)#

Active when: control_state==3 && !go_manual — set on startup

Step 1	`AutoGetUpAndLocate` — always runs first. Handles fall recovery.
Step 2	If `gc_is_under_penalty` → stop, scan, wait to re-enter field.
Step 3	Otherwise → game flow by sub-state type (see below).
Enter	Startup (`RunOnce`) or LT+B
Exit	Never — this is the default state

Three-phase mode auto flow: AutoGetUpAndLocate → WaitForPenalty → GameFlow.

Auto Mode — Sub-state Types#

TIMEOUT#

Stop all movement, scan field, track ball. Safe idle until game resumes.

NONE — Normal Play#

Driven by gc_game_state from the game controller:

Game state	Behavior
INITIAL	Scan field to localize, track ball, walk to entry position. Loops until READY signal.
READY	Look forward (`MoveHead pitch=0.35`), walk to kickoff position at vx=0.7, localize.
SET	Track ball with camera, stop all movement, localize. Freeze and wait for kickoff.
PLAY	Run `StrikerPlay` or `GoalKeeperPlay` subtree based on `player_role`.
END	Stop all movement. Match over.

Four-phase normal game flow: INITIAL → READY → SET → PLAY.

FREE_KICK — During PLAY#

Active when gc_game_sub_state_type == 'FREE_KICK' and gc_game_state == 'PLAY'. Driven by gc_game_sub_state:

Phase	Behavior
STOP	Track ball, localize if `ball_location_known`, stop all movement.
GET_READY	Localize, then run role-specific freekick subtree (`StrikerFreekick` or `GoalKeeperFreekick`).
SET	Track ball, localize, stop all movement. Wait for kick signal.

Three-phase free kick flow: STOP → GET_READY → SET.

Startup Sequence#

RunOnce sets control_state = 3.
State 1 and State 2 checks are skipped — conditions false.
State 3 activates → AutoGetUpAndLocate runs.
Not penalized → sub-state NONE → gc_game_state = INITIAL.
CamScanField until localized → CamFindAndTrackBall → SelfLocateEnterField.
Loops in INITIAL until game controller sends READY signal.

Top-level control flow: startup, modes, and sub-state routing.

Example Robot Status#

Field	Value
Team ID / Player ID	29 / Player 1
Number of players	3
Role	Striker (start role: striker)
Control state	Auto (3)
Game sub-state type	NONE
Game state	INITIAL
Kickoff side	NO
Score	0 : 0
Live count / Oppo	0 / 0
Primary striker	YES

Key Design Patterns#

ReactiveSequence with `_while`#

The sequence only runs while its condition is true. The moment the condition becomes false, the sequence exits immediately and the tree falls through to the next sibling. This gives the tree its priority-based, reactive feel — higher-priority states preempt lower ones instantly.

`_autoremap="true"`#

All subtrees share the same blackboard automatically. Any key with the same name in both the parent and subtree is connected without explicit port mapping. Since brain.cpp writes entries like tree->setEntry<string>("player_role", ...), every subtree that declares a port with that name gets the value automatically.

Role separation#

The player_role blackboard key gates which subtree runs at PLAY and GET_READY levels. The value is written by handleCooperation() in brain.cpp based on team negotiation and game state.

Actual soccer logic#

The interesting behavior — chasing, kicking, positioning, defending — lives entirely inside four subtrees:

StrikerPlay
GoalKeeperPlay
StrikerFreekick
GoalKeeperFreekick

Behavior Tree Diagrams#

The following diagrams illustrate each state machine from the behavior tree, as designed in draw.io.

Diagram 1 — Full Auto Mode Overview#