커스텀 데코레이터의 포트 정의 (Custom Decorator’s Port Definition)

1. 개요

커스텀 데코레이터의 포트 정의는 데코레이터가 외부로부터 수신하거나 외부로 전달하는 매개변수를 providedPorts() 정적 메서드를 통해 선언하는 것이다. 포트를 통해 XML에서 상수 값 또는 블랙보드 키를 전달받을 수 있으며, 데코레이터의 동작을 매개변수화한다.

2. providedPorts() 메서드

static BT::PortsList providedPorts()
{
    return {
        BT::InputPort<int>("max_count", 3, "최대 실행 횟수"),
        BT::InputPort<double>("timeout_sec", 10.0, "타임아웃 (초)"),
        BT::OutputPort<int>("current_count", "현재 실행 횟수")
    };
}

2.1 포트 유형

2.2 InputPort의 매개변수

BT::InputPort<타입>("포트이름", 기본값, "설명")
BT::InputPort<타입>("포트이름", "설명")  // 기본값 없음 (필수)

3. 포트 값 읽기

tick() 메서드 내에서 getInput() 메서드를 사용하여 포트 값을 읽는다.

BT::NodeStatus tick() override
{
    int max_count;
    double timeout_sec;

    getInput("max_count", max_count);
    getInput("timeout_sec", timeout_sec);

    // max_count와 timeout_sec 사용
}

4. 포트 값 쓰기

OutputPort에 값을 기록하는 경우 setOutput()을 사용한다.

setOutput("current_count", current_count_);

5. XML에서의 포트 지정

5.1 정적 값

<MyDecorator max_count="5" timeout_sec="30.0">
    <Action ID="Task"/>
</MyDecorator>

5.2 블랙보드 키 참조

<MyDecorator max_count="{retry_limit}" timeout_sec="{mission_timeout}">
    <Action ID="Task"/>
</MyDecorator>

6. 설계 시 고려 사항

6.1 기본값 제공

선택적 포트에는 합리적인 기본값을 제공하여, XML에서 생략 가능하도록 한다.

6.2 단위 명시

포트 설명에 물리량의 단위를 명시한다 (예: “타임아웃 (초)”, “거리 (m)”).

6.3 타입 안전성

포트의 타입과 getInput()에서 수신하는 변수의 타입이 일치하여야 한다. 타입 불일치 시 런타임 오류가 발생한다.

7. 참고 문헌

• BehaviorTree.CPP 공식 문서. https://www.behaviortree.dev/