# urosidoki/htn_planner architecture

> Architecture diagram of the GitHub repository urosidoki/htn_planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urosidoki/htn_planner
- Repository: https://github.com/urosidoki/htn_planner

## Overview

HTN Planner translates declarative task domains into native generated planners, which decompose top-level goals against a world state into primitive-task plans. The host engine, not the planner, schedules and executes those actions. The graph also captures the documented authoring/tooling, debugging, integration, and dynamic-domain branches. Connections among unsampled subsystems are included only where the README documents them; implementation details there remain unverified.

Main entry points: [`HTNIntegration/src/Hook/HTNPlannerHook.h`](https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNPlannerHook.h) (Planner hook), [`HTNIntegration/src/Hook/HTNPlanningUnit.h`](https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNPlanningUnit.h) (Planning unit), [`HTNFramework/src/Translator/HTNGeneratedPlanner.h`](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNGeneratedPlanner.h) (Generated planner), [`HTNTranslator/src/main.cpp`](https://github.com/urosidoki/htn_planner/blob/main/HTNTranslator/src/main.cpp) (Translator CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Domain compilation"]
  node_domain["Domain source"]
  node_translator["Translator CLI<br/>[main.cpp]"]
  node_lexer["Domain lexer"]
  node_parser["Syntax parser"]
  node_validator["Domain validation"]
  node_ir["Compiler IR"]
  node_generator["C generator"]
end

subgraph group_runtime["Planning runtime"]
  node_generated["Generated planner"]
  node_worldstate[("World state<br/>[HTNWorldState.cpp]")]
  node_callterms["Call-term bindings"]
  node_registry["Call-term registry"]
  node_symbols["Interned symbols<br/>[HtnSymbol.h]"]
  node_tasks["Task representation<br/>[HTNTask.h]"]
  node_debugger["Execution debugger"]
end

subgraph group_tooling["Authoring and tools"]
  node_editor["Domain editor<br/>[main.cpp]"]
  node_languageserver["Language server"]
  node_vscode["VS Code client<br/>[extension.js]"]
end

subgraph group_integration["Engine integration"]
  node_databasehook["Database hook<br/>[HTNDatabaseHook.h]"]
  node_plannerhook["Planner hook<br/>[HTNPlannerHook.h]"]
  node_planningunit["Planning unit<br/>[HTNPlanningUnit.h]"]
  node_plan["Primitive-task plan"]
  node_bridge["Runtime bridge"]
end

subgraph group_examples["Examples and extensions"]
  node_demo["Visual planner demo<br/>[main.cpp]"]
  node_npc["NPC simulation"]
  node_hotreload["Hot-reload example"]
end

node_author(("Domain author"))
node_engine(("Game engine"))

node_author -->|"writes"| node_domain
node_domain -->|"translated by"| node_translator
node_translator -->|"starts compilation"| node_lexer
node_lexer -->|"tokenizes for"| node_parser
node_parser -->|"validates through"| node_validator
node_validator -->|"lowers into"| node_ir
node_ir -->|"feeds"| node_generator
node_generator -->|"emits C for"| node_generated
node_generated -->|"executes via"| node_plannerhook
node_engine -->|"requests decomposition"| node_planningunit
node_planningunit -->|"delegates planning"| node_plannerhook
node_planningunit -->|"uses database"| node_databasehook
node_databasehook -->|"owns state"| node_worldstate
node_plannerhook -->|"plans against"| node_worldstate
node_plannerhook -->|"dispatches to"| node_generated
node_planningunit -->|"returns plan"| node_plan
node_plan -->|"engine executes"| node_engine
node_engine -->|"binds functions"| node_callterms
node_callterms -->|"registers in"| node_registry
node_plannerhook -->|"uses bindings"| node_registry
node_generated -->|"captures execution"| node_debugger
node_editor -.->|"uses compiler tooling"| node_translator
node_author -->|"authors in"| node_editor
node_vscode -.->|"language tooling"| node_languageserver
node_demo -->|"runs compiled domains"| node_generated
node_demo -->|"renders events"| node_debugger
node_npc -->|"plans through"| node_planningunit
node_hotreload -.->|"loads generated module"| node_bridge

click node_translator "https://github.com/urosidoki/htn_planner/blob/main/HTNTranslator/src/main.cpp"
click node_lexer "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerDomainLexer.cpp"
click node_parser "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerDomainSyntaxParser.cpp"
click node_validator "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerDomainValidator.cpp"
click node_ir "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerIRBuilder.cpp"
click node_generator "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCCodeGenerator.cpp"
click node_generated "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNGeneratedPlanner.h"
click node_worldstate "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/WorldState/HTNWorldState.cpp"
click node_callterms "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HTNCallTermBinding.h"
click node_registry "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HTNCallTermRegistry.h"
click node_symbols "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HtnSymbol.h"
click node_tasks "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HTNTask.h"
click node_debugger "https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNGeneratedDebugger.h"
click node_databasehook "https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNDatabaseHook.h"
click node_plannerhook "https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNPlannerHook.h"
click node_planningunit "https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNPlanningUnit.h"
click node_plan "https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNGeneratedPlanResult.h"
click node_editor "https://github.com/urosidoki/htn_planner/blob/main/HTNEditor/src/main.cpp"
click node_languageserver "https://github.com/urosidoki/htn_planner/tree/main/HTNLanguageServer/src"
click node_vscode "https://github.com/urosidoki/htn_planner/blob/main/HTNVSCode/extension.js"
click node_demo "https://github.com/urosidoki/htn_planner/blob/main/HTNDemo/src/main.cpp"
click node_npc "https://github.com/urosidoki/htn_planner/blob/main/HTNDemo/src/AI/AIHTNDemoWandererAgent.cpp"
click node_hotreload "https://github.com/urosidoki/htn_planner/blob/main/HTNHotReloadDemo/src/HTNHotReloadDemo.cpp"
click node_bridge "https://github.com/urosidoki/htn_planner/blob/main/HTNRuntimeBridge/src/HTNRuntimeBridge.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_domain,node_translator,node_lexer,node_parser,node_validator,node_ir,node_generator toneBlue
class node_generated,node_worldstate,node_callterms,node_registry,node_symbols,node_tasks,node_debugger toneAmber
class node_editor,node_languageserver,node_vscode toneMint
class node_databasehook,node_plannerhook,node_planningunit,node_plan,node_bridge toneRose
class node_demo,node_npc,node_hotreload,node_author,node_engine toneIndigo
```

## Components

### Domain compilation

- **Domain source**
- [Translator CLI](https://github.com/urosidoki/htn_planner/blob/main/HTNTranslator/src/main.cpp): `HTNTranslator/src/main.cpp`
- [Domain lexer](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerDomainLexer.cpp): `HTNFramework/src/Translator/HTNCompilerDomainLexer.cpp`
- [Syntax parser](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerDomainSyntaxParser.cpp): `HTNFramework/src/Translator/HTNCompilerDomainSyntaxParser.cpp`
- [Domain validation](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerDomainValidator.cpp): `HTNFramework/src/Translator/HTNCompilerDomainValidator.cpp`
- [Compiler IR](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCompilerIRBuilder.cpp): `HTNFramework/src/Translator/HTNCompilerIRBuilder.cpp`
- [C generator](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNCCodeGenerator.cpp): `HTNFramework/src/Translator/HTNCCodeGenerator.cpp`

### Planning runtime

- [Generated planner](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNGeneratedPlanner.h): `HTNFramework/src/Translator/HTNGeneratedPlanner.h`
- [World state](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/WorldState/HTNWorldState.cpp): `HTNFramework/src/WorldState/HTNWorldState.cpp`
- [Call-term bindings](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HTNCallTermBinding.h): `HTNFramework/src/Core/HTNCallTermBinding.h`
- [Call-term registry](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HTNCallTermRegistry.h): `HTNFramework/src/Core/HTNCallTermRegistry.h`
- [Interned symbols](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HtnSymbol.h): `HTNFramework/src/Core/HtnSymbol.h`
- [Task representation](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Core/HTNTask.h): `HTNFramework/src/Core/HTNTask.h`
- [Execution debugger](https://github.com/urosidoki/htn_planner/blob/main/HTNFramework/src/Translator/HTNGeneratedDebugger.h): `HTNFramework/src/Translator/HTNGeneratedDebugger.h`

### Authoring and tools

- [Domain editor](https://github.com/urosidoki/htn_planner/blob/main/HTNEditor/src/main.cpp): `HTNEditor/src/main.cpp`
- [Language server](https://github.com/urosidoki/htn_planner/tree/main/HTNLanguageServer/src): `HTNLanguageServer/src`
- [VS Code client](https://github.com/urosidoki/htn_planner/blob/main/HTNVSCode/extension.js): `HTNVSCode/extension.js`

### Engine integration

- [Database hook](https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNDatabaseHook.h): `HTNIntegration/src/Hook/HTNDatabaseHook.h`
- [Planner hook](https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNPlannerHook.h): `HTNIntegration/src/Hook/HTNPlannerHook.h`
- [Planning unit](https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNPlanningUnit.h): `HTNIntegration/src/Hook/HTNPlanningUnit.h`
- [Primitive-task plan](https://github.com/urosidoki/htn_planner/blob/main/HTNIntegration/src/Hook/HTNGeneratedPlanResult.h): `HTNIntegration/src/Hook/HTNGeneratedPlanResult.h`
- [Runtime bridge](https://github.com/urosidoki/htn_planner/blob/main/HTNRuntimeBridge/src/HTNRuntimeBridge.cpp): `HTNRuntimeBridge/src/HTNRuntimeBridge.cpp`

### Examples and extensions

- [Visual planner demo](https://github.com/urosidoki/htn_planner/blob/main/HTNDemo/src/main.cpp): `HTNDemo/src/main.cpp`
- [NPC simulation](https://github.com/urosidoki/htn_planner/blob/main/HTNDemo/src/AI/AIHTNDemoWandererAgent.cpp): `HTNDemo/src/AI/AIHTNDemoWandererAgent.cpp`
- [Hot-reload example](https://github.com/urosidoki/htn_planner/blob/main/HTNHotReloadDemo/src/HTNHotReloadDemo.cpp): `HTNHotReloadDemo/src/HTNHotReloadDemo.cpp`

### Other components

- **Domain author**
- **Game engine**

## Connections

- Domain author → Domain source: writes (evidence: `README.md`)
- Domain source → Translator CLI: translated by (evidence: `README.md`)
- Translator CLI → Domain lexer: starts compilation (evidence: `README.md`)
- Domain lexer → Syntax parser: tokenizes for (evidence: `README.md`)
- Syntax parser → Domain validation: validates through (evidence: `README.md`)
- Domain validation → Compiler IR: lowers into (evidence: `README.md`)
- Compiler IR → C generator: feeds (evidence: `README.md`)
- C generator → Generated planner: emits C for (evidence: `README.md`)
- Generated planner → Planner hook: executes via (evidence: `README.md`)
- Game engine → Planning unit: requests decomposition (evidence: `README.md`)
- Planning unit → Planner hook: delegates planning (evidence: `HTNIntegration/src/Hook/HTNPlanningUnit.h`)
- Planning unit → Database hook: uses database (evidence: `HTNIntegration/src/Hook/HTNPlanningUnit.h`)
- Database hook → World state: owns state (evidence: `HTNIntegration/src/Hook/HTNDatabaseHook.h`)
- Planner hook → World state: plans against (evidence: `HTNIntegration/src/Hook/HTNPlannerHook.h`)
- Planner hook → Generated planner: dispatches to (evidence: `HTNIntegration/src/Hook/HTNPlannerHook.h`)
- Planning unit → Primitive-task plan: returns plan (evidence: `HTNIntegration/src/Hook/HTNPlanningUnit.h`)
- Primitive-task plan → Game engine: engine executes (evidence: `README.md`)
- Game engine → Call-term bindings: binds functions (evidence: `README.md`)
- Call-term bindings → Call-term registry: registers in (evidence: `HTNFramework/src/Core/HTNCallTermBinding.h`)
- Planner hook → Call-term registry: uses bindings (evidence: `HTNIntegration/src/Hook/HTNPlannerHook.h`)
- Generated planner → Execution debugger: captures execution (evidence: `README.md`)
- Domain editor → Translator CLI: uses compiler tooling
- Domain author → Domain editor: authors in (evidence: `README.md`)
- VS Code client → Language server: language tooling
- Visual planner demo → Generated planner: runs compiled domains (evidence: `README.md`)
- Visual planner demo → Execution debugger: renders events (evidence: `README.md`)
- NPC simulation → Planning unit: plans through (evidence: `HTNDemo/src/AI/AIHTNDemoWandererAgent.cpp`)
- Hot-reload example → Runtime bridge: loads generated module