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:

```storybook
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`:

```storybook
// 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:

```storybook
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:

```storybook
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:

```storybook
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](./06-relationships.md), you will model how characters connect to each other -- friendships, rivalries, parent-child bonds, and more.

---

**Reference**: See [Behavior Trees Reference](../reference/11-behavior-trees.md) and [Decorators Reference](../reference/12-decorators.md) for complete syntax.