storybook/docs/tutorial/05-advanced-behaviors.md

Advanced Behaviors

You have learned the fundamentals of behavior trees. This chapter covers advanced patterns: complex decision hierarchies, modular design with subtrees, and state-driven behavior.

Deep Decision Trees

Real characters need layered decision-making. Nest selectors and sequences to create rich AI:

behavior Baker_DailyAI {
    choose daily_activity {
        // Morning: Prepare the bakery
        then morning_prep {
            if(time_is_morning)
            then prep_sequence {
                LightOven
                PrepareDough
                StartFirstBatch
            }
        }

        // Day: Serve customers
        then day_service {
            if(time_is_daytime)
            choose service_mode {
                then serve_customer {
                    if(customer_waiting)
                    GreetCustomer
                    TakeOrder
                    PackageItems
                    CollectPayment
                }

                then restock {
                    if(display_low)
                    FetchFromKitchen
                }

                CleanCounter
            }
        }

        // Evening: Close up
        then evening_close {
            if(time_is_evening)
            then close_sequence {
                TurnOffOvens
                CleanKitchen
                CountRegister
                LockUp
            }
        }
    }
}

Each level of nesting refines the decision. The outer choose selects the time of day; inner nodes handle the specifics.

Modular Subtrees

Large behavior trees become unwieldy. Break them into focused subtrees and compose with include:

// Focused subtree: just baking
behavior Baking_Sourdough {
    then sourdough_sequence {
        MixDough
        KneadDough
        FirstRise
        ShapeLoaves
    }
}

// Focused subtree: just customer service
behavior Service_ServeCustomer {
    then service_sequence {
        GreetCustomer
        TakeOrder
        PackageItems
        CollectPayment
    }
}

// Composition: combine subtrees
behavior Martha_FullDay {
    choose activity {
        then morning_baking {
            if(time_is_morning)
            include Baking_Sourdough
            include Baking_Pastries
        }

        then afternoon_sales {
            if(time_is_afternoon)
            include Service_ServeCustomer
        }

        CleanWorkstation
    }
}

Benefits of modular subtrees:

• Each subtree is testable in isolation
• Multiple characters can share subtrees
• Changes propagate automatically

Conditional Behavior Selection

Use conditions to switch between behavioral modes:

behavior SmartBaker {
    choose strategy {
        // Busy mode when there are many customers
        then busy_mode {
            if(customer_count > 5 and inventory_sufficient)
            choose rush_tactics {
                ServeFastOrder
                QuickRestock
                ExpressBake
            }
        }

        // Careful mode when supplies are low
        then careful_mode {
            if(inventory_low or special_ingredients_missing)
            choose conservation_tactics {
                ReducePortions
                SubstituteIngredients
                OrderEmergencySupply
            }
        }

        // Normal mode otherwise
        then normal_mode {
            if(customer_count <= 5 and inventory_sufficient)
            StandardRoutine
        }
    }
}

Decorator Combinations

Combine decorators to build sophisticated control patterns:

behavior Baker_SpecialRecipe {
    // Only when inventory is sufficient
    if(has_special_ingredients) {
        // Limited to once per hour
        cooldown(1h) {
            // Must complete within 30 minutes
            timeout(30m) {
                // Try up to 3 times
                retry(3) {
                    then bake_special {
                        PrepareSpecialDough
                        BakeAtPreciseTemperature
                    }
                }
            }
        }
    }
}

Prose Documentation

Add narrative context to complex behaviors with prose blocks:

behavior Elena_TrainingSession {
    ---description
    Elena practicing a new recipe under Martha's guidance.
    Uses retry decorator for persistence and if for
    checking readiness.
    ---

    choose training_strategy {
        then practice_supervised {
            if(martha_available)
            retry(3) {
                then attempt_recipe {
                    ReviewRecipeSteps
                    MeasureIngredients
                    MixAndKnead
                    CheckWithMartha
                }
            }
        }

        then practice_solo {
            if(not martha_available)
            then solo_attempt {
                ReviewRecipeNotes
                AttemptRecipeFromMemory
                TasteTestResult
            }
        }
    }
}

Design Tips

Prefer shallow trees: Break deep nesting into subtrees with include.

Name every composite node: Labels make trees self-documenting.

Use decorators for control flow: Timing, repetition, and gating belong in decorators, not in action logic.

Keep actions atomic: Each action should do one thing. Complex operations are sequences of simple actions.

Next Steps

Characters do not exist in isolation. In Character Relationships, you will model how characters connect to each other -- friendships, rivalries, parent-child bonds, and more.

---

Reference: See Behavior Trees Reference and Decorators Reference for complete syntax.