BehaviorTree.CPP 내장 데코레이터 목록 (Built-in Decorator List of BehaviorTree.CPP)

BehaviorTree.CPP 내장 데코레이터 목록 (Built-in Decorator List of BehaviorTree.CPP)

1. 개요

BehaviorTree.CPP는 행동 트리 설계에 필요한 다양한 데코레이터를 기본으로 제공한다. 본 절에서는 BehaviorTree.CPP 4.x에서 제공하는 모든 내장 데코레이터의 종합 목록과 각각의 특성을 정리한다.

2. 상태 변환 데코레이터

XML 이름	C++ 클래스	동작	매개변수
`Inverter`	`InverterNode`	SUCCESS↔FAILURE 반전	없음
`ForceSuccess`	`ForceSuccessNode`	항상 SUCCESS 반환	없음
`ForceFailure`	`ForceFailureNode`	항상 FAILURE 반환	없음

3. 실행 제어 데코레이터

XML 이름	C++ 클래스	동작	매개변수
`Repeat`	`RepeatNode`	지정 횟수 반복	`num_cycles` (int, -1=무한)
`RetryNode`	`RetryNode`	FAILURE 시 재시도	`num_attempts` (int)
`RunOnce`	`RunOnce`	최초 1회만 실행	`then_skip` (bool)
`KeepRunningUntilFailure`	`KeepRunningUntilFailure`	FAILURE까지 반복	없음

4. 시간 제어 데코레이터

XML 이름	C++ 클래스	동작	매개변수
`Timeout`	`TimeoutNode`	실행 시간 제한	`msec` (unsigned)
`Delay`	`DelayNode`	실행 전 지연	`delay_msec` (unsigned)

5. 조건부 실행 데코레이터

XML 이름	C++ 클래스	동작	매개변수
`SkipUnlessUpdated`	`SkipUnlessUpdated`	블랙보드 변경 시에만 실행	없음
`Precondition`	`PreconditionNode`	스크립트 조건 검사	`if`, `else`

6. 스크립트 기반 데코레이터 (속성)

BehaviorTree.CPP 4.x에서 모든 노드에 적용 가능한 스크립트 속성이다.

속성 이름	적용 시점	조건 참일 때	조건 거짓일 때
`_skipIf`	tick 전	SKIPPED	자식 tick
`_failureIf`	tick 전	FAILURE	자식 tick
`_successIf`	tick 전	SUCCESS	자식 tick
`_while`	tick 전	자식 tick	SKIPPED
`_onSuccess`	tick 후	스크립트 실행	-
`_onFailure`	tick 후	-	스크립트 실행
`_onHalted`	halt 시	스크립트 실행	-

7. 기타 제어 노드 (데코레이터 유사)

다음 노드들은 엄밀한 의미에서 데코레이터(단일 자식)가 아니나, 조건부 실행 메커니즘을 제공한다.

XML 이름	자식 수	동작
`WhileDoElse`	3	조건에 따라 Do 또는 Else 실행
`IfThenElse`	2~3	조건에 따라 분기
`Switch`	N	값에 따라 분기

8. 버전별 차이

기능	3.x	4.x
기본 데코레이터	Inverter, ForceSuccess, ForceFailure, Repeat, Retry, Timeout	동일 + RunOnce, Delay, KeepRunningUntilFailure
스크립트 속성	미지원	`_skipIf`, `_failureIf`, `_while` 등
SKIPPED 상태	미지원	지원
SkipUnlessUpdated	미지원	지원

9. 참고 문헌

BehaviorTree.CPP 공식 문서. https://www.behaviortree.dev/
BehaviorTree.CPP GitHub. https://github.com/BehaviorTree/BehaviorTree.CPP

버전	날짜	변경 사항
v0.1	2026-04-05	초안 작성