urosidoki/htn_planner

What it solves

Game AI often needs to decide a sequence of actions that achieves a goal. Hierarchical task network (HTN) planning breaks high-level tasks into smaller, more concrete steps. This library provides an HTN planner for games, with a declarative domain language that is compiled ahead of time into native C. That means the runtime executes the planner directly, without parsing domain text during gameplay, which keeps performance predictable.

How it works

You write a domain in a Lisp-like syntax, for example a patrol method that checks a condition (guard_on_duty) and then executes two primitive tasks: move to a checkpoint and scan an area. The included HTNTranslator tool validates the domain and generates C source code. That generated planner is then compiled into your game or as a separate module. At runtime, the planner uses a world state and call terms to decide which primitive tasks to run. The engine drives the actions: it calls the decomposition API, reads the resulting primitive tasks, and completes them one by one. An integration layer (HTNIntegration) provides hooks and planning units to simplify this. For debugging, instrumented builds can capture the whole decomposition tree and show it visually.

Who it's for

Game developers who need structured decision-making for NPCs, squads, or AI directors. The README lists use cases like NPC behavior, active-plan validation, squad coordination, and AI Director flows. It is built for C++ projects on Windows x64 and Linux x64, with support for Visual Studio 2022 and GCC/Clang on Ubuntu 24.04. If you want to embed a fast, offline-compiled planner into your game engine, this library is aimed at you.

Highlights

• Compiles domain source into native C, so the runtime is fast and free of parsing overhead.
• Includes a command-line translator (HTNTranslator) for validation and C code generation.
• Offers a C++ integration layer with planner hooks, planning units, and a world-state database.
• Ships with an SDL/ImGui visual demo and a generated execution debugger.
• Provides an editor (HTNEditor), language server (HTNLanguageServer), and VS Code extension.
• Supports hot reload of generated domain modules.
• Packageable SDKs for Windows and Linux with CMake integration.
• Tested with a suite covering compiler, runtime, integration, and ABI validation.