# ptrefall/fluid-hierarchical-task-network architecture

> Architecture diagram of the GitHub repository ptrefall/fluid-hierarchical-task-network, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ptrefall/fluid-hierarchical-task-network
- Repository: https://github.com/ptrefall/fluid-hierarchical-task-network

## Overview

##### Project type and purpose
- This is a C# library (Fluid-HTN) providing a Hierarchical Task Network (HTN) planner for AI, designed around the Builder pattern.
- It’s not a full‑stack application but an open‑source tool oriented toward game or simulation AI (with Unity integration) and heavy on extensibility (custom conditions, operators, effects, selectors).

##### File structure
- Top‑level:
- Fluid‑HTN/ – core source code
– BaseDomainBuilder.cs, DomainBuilder.cs, Domain.cs
– Conditions/, Effects/, Operators/, Factory/, Planners/, Tasks/, Contexts/, Debug/
- Fluid‑HTN.UnitTests/ – 148 xUnit tests validating every component
- .github/, .travis.yml, README.md, LICENSE – project metadata and CI
- Key patterns:
- Builder (DomainBuilder → Domain)
- Composite (ITask → CompoundTask/PrimitiveTask hierarchy)
- Strategy (IOperator implementations)
- Factory (IFactory for pooling)
- Observer (PlannerState callbacks)

##### README for additional insights
- Core components: DomainBuilder, Planner, Context, Compound vs. Primitive Tasks, Conditions, Effects, Operators.
- Extensibility: custom domain builders, sub‑domains, slots, custom conditions/effects/operators, Unity package.

##### Main components and their interactions
A. DomainBuilder (design time)
– Fluent API defines compound/primitive tasks, conditions, effects, operators → produces a Domain object.
B. Domain (immutable plan definition)
– Contains a task tree (Composite of ITask nodes).
C. Planner (runtime engine)
– Tick(domain, context) → decomposes root compound task into a plan (Queue<ITask>) using forward decomposition.
– Maintains PlannerState, triggers callbacks (OnNewPlan, OnNewTask, OnApplyEffect, etc.).
D. Context (IContext/BaseContext)
– Holds world‑state array (blackboard), debug flags, Factory, PlannerState, decomposition logs.
– Exposes WorldState manipulation (e.g. HasState, SetState).
E. Tasks & Sub‑components
– CompoundTasks: Selector, Sequence, custom selectors (RandomSelect).
– PrimitiveTasks: wrap an IOperator + Conditions + Effects.
– Conditions (ICondition) validate state during decomposition or execution.
– Effects (IEffect) predict (PlanOnly), apply at runtime (PlanAndExecute), or permanently update state.
– Operators (IOperator) implement Execute/Continue/Stop logic each tick.
F. Factory (IFactory / DefaultFactory)
– Abstract creation/freeing of arrays and collections for pooling support.
G. Debug & Logging
– DecompositionLog entries record success/failure of each step; MTRDebug tracks traversal records.
H. Unit Tests
– Validate each component in isolation (Conditions, Operators, DomainBuilder, Planner behavior).

##### Architectural patterns and principles
- Separation of concerns: building (DomainBuilder) vs. planning (Planner) vs. execution/context (Context & Operator)
- Composite pattern for HTN task hierarchy
- Builder pattern for fluent domain definition
- Strategy pattern for pluggable Operators/Conditions/Effects
- Factory pattern for memory management and pooling
- Observer/callback hooks in PlannerState for instrumentation

##### Detail is key
- Class/group is represented at least once (e.g. Conditions folder → ICondition implementations)
- Call out extension points explicitly (e.g. “Custom IOperator” under Operators)
- Interactions between Planner and PlannerState callbacks to illustrate observability hooks
- Two-phase effect application (planning vs. execution) in the Effects component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Design-Time Layer (Green)
    subgraph "Design-Time" 
        direction TB
        DB["DomainBuilder"]:::design
        BDB["BaseDomainBuilder"]:::design
        IDom["IDomain"]:::design
        Dom["Domain"]:::design
        DB -->|"extends"| BDB
        DB -->|"builds"| Dom
        Dom -->|"implements"| IDom
    end

    %% Runtime Core Layer (Blue)
    subgraph "Runtime Core"
        direction TB
        Pl["Planner"]:::runtime
        IPS["IPlannerState"]:::runtime
        DPS["DefaultPlannerState"]:::runtime
        ICtx["IContext"]:::runtime
        BCtx["BaseContext"]:::runtime
        IT["ITask"]:::runtime
        CT["CompoundTask"]:::runtime
        ICT["ICompoundTask"]:::runtime
        Sel["Selector"]:::runtime
        Seq["Sequence"]:::runtime
        TR["TaskRoot"]:::runtime
        PT["PrimitiveTask"]:::runtime
        IPT["IPrimitiveTask"]:::runtime
        Slot["Slot"]:::runtime
        Cond["ICondition"]:::runtime
        FuncC["FuncCondition"]:::runtime
        Eff["IEffect"]:::runtime
        ActEff["ActionEffect"]:::runtime
        ET["EffectType"]:::runtime
        Op["IOperator"]:::runtime
        FuncO["FuncOperator"]:::runtime
        World["WorldState[]"]:::data
        LogQ["DecompositionLog Queue"]:::data

        ICtx -->|"extends"| BCtx
        BCtx -->|"holds"| World
        BCtx -->|"holds"| LogQ
        Pl -->|"uses"| ICtx
        Pl -->|"uses"| Dom
        Pl -->|"uses"| IT
        Pl -->|"state"| IPS
        IPS -->|"default"| DPS
        IT -->|"composite"| CT
        CT -->|"implements"| ICT
        CT -->|"includes"| Sel & Seq & TR
        PT -->|"implements"| IPT
        PT -->|"wraps"| Op & Cond & Eff
        Op -->|"extends"| FuncO
        Cond -->|"extends"| FuncC
        Eff -->|"extends"| ActEff
        Eff -->|"typed by"| ET
        Pl -->|"decomposes"| TR
        Pl -->|"evaluates"| Cond
        Pl -->|"applies effects"| Eff
        Pl -->|"executes"| Op
        Pl -->|"logs to"| LogQ
        Pl -->|"triggers"| IPS
    end

    %% Support Layer (Orange)
    subgraph "Support"
        direction TB
        FactI["IFactory"]:::support
        DefFact["DefaultFactory"]:::support
        LogE["DecompositionLogEntry"]:::support
        FactI -->|"implements"| DefFact
        LogQ -->|"entries of"| LogE
    end

    %% Integration & Tests Layer (Gray)
    subgraph "Integration & Tests"
        direction TB
        UT["UnitTests"]:::integration
        ASM["Fluid.HTN.asmdef"]:::integration
        CSP["Fluid-HTN.csproj"]:::integration
    end

    %% Interactions
    Dom -->|"used by"| Pl
    BCtx -->|"provides factory"| FactI
    BCtx -->|"collects logs"| LogE
    UT -->|"validates"| Pl & Dom & Cond & Op
    ASM -->|"integrates with"| Dom & Pl
    CSP -->|"project definition"| Dom

    %% Click Events
    click DB "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/DomainBuilder.cs"
    click BDB "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/BaseDomainBuilder.cs"
    click Dom "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Domain.cs"
    click IDom "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/IDomain.cs"
    click Pl "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Planners/Planner.cs"
    click IPS "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Planners/IPlannerState.cs"
    click DPS "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Planners/DefaultPlannerState.cs"
    click ICtx "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Contexts/IContext.cs"
    click BCtx "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Contexts/BaseContext.cs"
    click IT "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/ITask.cs"
    click CT "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/CompoundTasks/CompoundTask.cs"
    click ICT "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/CompoundTasks/ICompoundTask.cs"
    click Sel "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/CompoundTasks/Selector.cs"
    click Seq "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/CompoundTasks/Sequence.cs"
    click TR "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/CompoundTasks/TaskRoot.cs"
    click PT "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/PrimitiveTasks/PrimitiveTask.cs"
    click IPT "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/PrimitiveTasks/IPrimitiveTask.cs"
    click Slot "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Tasks/OtherTasks/Slot.cs"
    click Cond "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Conditions/ICondition.cs"
    click FuncC "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Conditions/FuncCondition.cs"
    click Eff "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Effects/IEffect.cs"
    click ActEff "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Effects/ActionEffect.cs"
    click ET "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Effects/EffectType.cs"
    click Op "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Operators/IOperator.cs"
    click FuncO "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Operators/FuncOperator.cs"
    click FactI "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Factory/IFactory.cs"
    click DefFact "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Factory/DefaultFactory.cs"
    click LogE "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Debug/DecompositionLogEntry.cs"
    click UT "https://github.com/ptrefall/fluid-hierarchical-task-network/tree/master/Fluid-HTN.UnitTests/"
    click ASM "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Fluid.HTN.asmdef"
    click CSP "https://github.com/ptrefall/fluid-hierarchical-task-network/blob/master/Fluid-HTN/Fluid-HTN.csproj"

    %% Styles
    classDef design fill:#e0f2f1,stroke:#00695c,color:#004d40
    classDef runtime fill:#e3f2fd,stroke:#1e88e5,color:#0d47a1
    classDef support fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef integration fill:#f5f5f5,stroke:#9e9e9e,color:#424242
    classDef data fill:#eeeeee,stroke:#757575,color:#212121
    class DB,BDB,Dom,IDom design
    class Pl,IPS,DPS,ICtx,BCtx,IT,CT,ICT,Sel,Seq,TR,PT,IPT,Slot,Cond,FuncC,Eff,ActEff,ET,Op,FuncO runtime
    class FactI,DefFact,LogE support
    class UT,ASM,CSP integration
    class World,LogQ data
```
