How ptrefall/fluid-hierarchical-task-network works
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