storybook/docs/tutorial/04-making-characters-act.md

Making Characters Act

In the previous chapter, you created behavior trees with selectors and sequences. Now you will add conditions, action parameters, and decorators to create dynamic, responsive behaviors.

Conditions: if and when

Conditions let behavior trees react to the world. Use if or when to test a condition before proceeding:

behavior Martha_React {
    choose response {
        then bake_path {
            if(inventory_sufficient)
            StartBaking
        }

        then restock_path {
            if(inventory_low)
            OrderSupplies
        }

        CleanWorkstation
    }
}

if(inventory_sufficient) succeeds when inventory is sufficient, and fails otherwise. If it fails, the entire bake_path sequence fails, and the tree moves on to the next option.

if and when are interchangeable -- use whichever reads more naturally:

// "if" for state checks
if(health < 20)

// "when" for event-like conditions
when(alarm_triggered)

Condition Expressions

Conditions support comparisons and logical operators:

// Comparisons
if(health < 20)
if(distance > 100)
if(name == "Martha")
if(status is Curious)        // 'is' is syntactic sugar for ==

// Logical operators
if(hungry and tired)
if(rich or lucky)
if(not is_dangerous)

// Combined
if(health < 50 and not has_potion)
if((age > 18 and age < 65) or is_veteran)

Action Parameters

Actions can take named parameters using parenthesis syntax:

behavior Martha_BakeSpecial {
    then baking {
        MixDough(recipe: "sourdough", quantity: 10)
        KneadDough(duration: 15m)
        BakeLoaves(temperature: 230, duration: 35m)
    }
}

Parameters are fields inside ( ) after the action name. They let you customize behavior without defining separate actions for each variation.

Decorators

Decorators wrap a single child node and modify its behavior. They are your tools for timing, repetition, and conditional execution.

repeat -- Looping

// Infinite repeat (checks oven forever)
repeat {
    CheckOvenTemperature
}

// Repeat exactly 3 times
repeat(3) {
    KneadDough
}

// Repeat between 2 and 5 times (random)
repeat(2..5) {
    FoldDough
}

invert -- Flip Results

Inverts success/failure. Useful for "if NOT" conditions:

behavior SafeBake {
    choose options {
        then bake_safely {
            invert { OvenOverheating }   // Succeeds if oven is NOT overheating
            ContinueBaking
        }

        StopAndInspect
    }
}

retry -- Try Again on Failure

Retries the child up to N times if it fails:

retry(3) {
    LightOven    // Try up to 3 times before giving up
}

timeout -- Time Limits

Fails the child if it does not complete within the duration:

timeout(10s) {
    WaitForDoughToRise    // Must finish within 10 seconds
}

cooldown -- Rate Limiting

Prevents the child from running again within the cooldown period:

cooldown(30s) {
    CheckOvenTemperature    // Can only check once every 30 seconds
}

if as Decorator (Guard)

The if decorator only runs the child when a condition is true:

if(has_special_orders) {
    PrepareSpecialBatch    // Only prepare when there are orders
}

This is different from if as a condition node. As a decorator, if wraps a child and gates its execution. As a condition node, if is a simple pass/fail check inline in a sequence.

succeed_always and fail_always

Force a result regardless of the child:

// Try bonus task, but don't fail the routine if it fails
succeed_always {
    ExperimentWithNewRecipe
}

// Temporarily disable a feature
fail_always {
    UntestedBakingMethod
}

Combining Decorators

Decorators can nest for complex control:

behavior ResilientAction {
    // Only run if oven is ready, with 20s timeout, retrying up to 3 times
    if(oven_ready) {
        timeout(20s) {
            retry(3) {
                BakeDelicateItem
            }
        }
    }
}

Execution flows outside-in: first the if checks the oven, then the timeout starts, then the retry begins.

Subtree References

The include keyword references another behavior tree, enabling reuse:

behavior SourdoughRecipe {
    then sourdough {
        MixDough(recipe: "sourdough", quantity: 10)
        KneadDough(duration: 15m)
        FirstRise(duration: 2h)
        ShapeLoaves
    }
}

behavior Martha_DailyRoutine {
    choose daily_priority {
        then special_orders {
            if(has_special_orders)
            include SpecialOrderBehavior
        }

        include SourdoughRecipe    // Reuse sourdough behavior
    }
}

Subtrees help you avoid duplicating behavior logic. You can also reference behaviors from other modules using qualified paths:

include behaviors::baking::sourdough
include behaviors::service::greet_customer

Behavior Linking with Priorities

Characters can link to multiple behaviors with priorities and conditions:

character Martha: Human {
    uses behaviors: [
        {
            tree: BakerRoutine
            priority: normal
        },
        {
            tree: HandleEmergency
            when: emergency_detected
            priority: high
        },
        {
            tree: HandleHealthInspection
            when: inspector_present
            priority: critical
        }
    ]
}

The runtime evaluates behaviors by priority (critical > high > normal > low). Higher-priority behaviors preempt lower-priority ones when their conditions are met.

A Complete Example

Here is a complete behavior tree for handling the morning rush:

behavior MorningRush_Routine {
    ---description
    The bakery's morning rush routine: serve customers, restock,
    and keep the ovens running.
    ---

    repeat {
        then rush_cycle {
            // Serve any waiting customers
            choose service_mode {
                then serve_regular {
                    if(customer_waiting)
                    GreetCustomer
                    TakeOrder
                    PackageItems
                    CollectPayment
                }

                then restock {
                    if(display_low)
                    FetchFromKitchen
                    ArrangeOnShelves
                }
            }

            // Check ovens between customers
            timeout(5s) {
                CheckAllOvens
            }

            PrepareNextBatch
        }
    }
}

This tree repeats forever: serve a customer or restock the display, check the ovens, and prepare the next batch.

Next Steps

You now know the full toolkit for behavior trees. In Advanced Behaviors, you will learn patterns for building complex AI systems with nested trees, state-based switching, and modular design.

---

Reference: See Decorators Reference for all decorator types and Expression Language for complete condition syntax.