HTN Planner 2.3.0

This release adds native negative numeric literals to the domain language, preserves their spelling in the debugger and improves diagnostics for malformed signed values.

(!remember -1.0 is_moving)
(= ?offset -0.5)
(== (+ -2 3) 1)
(== (- -2 3) -5)

Highlights

• Negative integers and floats in task/callterm arguments, fact queries, assignments, comparisons, arithmetic, lists, axioms, deferred arguments and world-state files.
• Existing subtraction, unary negation and decrement keep their meaning: (- 5 2), (- 1.0), (-- 1.5) and (- ?value 1).
• Negative literals generate numeric atoms directly, without an extra runtime negation. The minimum signed 32-bit integer is emitted portably as INT32_MIN.
• Debugger labels retain numeric spelling, full decimal precision and trailing zeros in static lists.
• Located diagnostics for malformed signed values and numeric overflow.

Compatibility

No C runtime API/ABI, generated planner ABI, RuntimeBridge ABI or HTNAtom layout change from 2.2.0. Runtime integrations need no API migration.

Rebuild tools using the C++ compiler frontend because the owned AST layout now includes literal spelling. Translate domains adopting the new syntax with the updated translator, and regenerate instrumented domains to obtain the improved debugger labels. Existing generated modules do not require regeneration solely for ABI compatibility.

Windows x86_64 and Ubuntu 24.04 x86_64 SDKs are included. Linux is validated with GCC 14 and Clang 18/libstdc++; HTNEditor remains Windows-only and experimental. The project is under active development.

Validation

• Complete public-source suites: 354 Windows Debug and 345 Linux GCC Release tests passed; generated C11 checked with Clang 18.
• Windows SDK: eight variants, 24 external consumer executions, eight object/export checks, negative configuration checks and Natvis validation.
• Linux SDK: four variants with GCC/Clang consumers, 24 executions, eight ELF audits and eight incompatible-domain ABI checks, plus six expected configuration rejections.
• Windows engine integration, including native negative literals, confirmed by the maintainer. That external engine itself has not been tested on Linux.

Download the Windows ZIP or Linux tar.gz below together with its .sha256 file.

Complete release notes · Language guide · Linux setup

HTN Planner 2.2.0

This release adds a native Linux SDK and ships the Visual Studio Natvis debugger visualizer with the Windows SDK.

Highlights

• Ubuntu 24.04 x86_64/WSL2 support, validated with GCC 14 and Clang 18 using libstdc++.
• Linux builds for the runtime, translator, integration, visual demos and generated debugger, language server, benchmarks and tests.
• Linux hot reload demo using .so domain modules. Engine file watching, compilation scheduling, loading and synchronization remain client responsibilities.
• Four Linux SDK variants with CMake integration; eight Windows SDK variants.
• debug/HTN.natvis included in Windows packages and propagated through the CMake targets.

Compatibility

No C runtime API/ABI, generated planner ABI, RuntimeBridge ABI, atom-layout or domain-language change from 2.1.0. Use the package for the target platform and matching configuration/instrumentation variant. Windows binaries cannot be reused on Linux.

HTNEditor remains excluded on Linux. Other distributions, architectures, libc++ and macOS remain unverified. The project is under active development.

Validation

• Source regression suites: 336 Windows Debug, 336 Linux Debug and 327 Linux Release tests passed.
• Final Windows SDK: 24 consumer executions, eight object/export checks, negative configuration checks and Natvis validation across all eight variants.
• Final Linux SDK: GCC and Clang consumers passed 40 checks across four variants, plus six expected configuration rejections.
• Windows engine integration reported successful; the external engine itself has not been validated on Linux.

Download the Windows ZIP or Linux tar.gz below, together with its .sha256 file. Both packages contain version 2.2.0 manifests and build provenance.

Complete release notes · Linux setup

HTN Planner 2.1.0

This release adds runtime list expressions, clearer callterm diagnostics, a domain
language guide, and smaller generated C through implementation sharing, reachability
analysis and optional instrumentation.

Highlights

• Runtime lists: use bound variables, arithmetic, callterms and nested lists as
  owned values in callterm arguments, assignments, facts, axioms and tasks, including
  deferred arguments.
• Clearer condition errors: a standalone callterm must return a boolean.
  Non-boolean results report NonBooleanConditionResult through the configured
  error policy; boolean false remains an ordinary condition failure.
• Smaller generated source: qualified aliases share implementations and unused
  code is removed while retaining every public top-level method and deferred entry.
• Translator controls: --instrumentation=full|none selects optional debugger
  and profiling emission; --code-stats reports generated source size by category.
• Language documentation: a complete tutorial and reference is included in the
  repository and SDK.

In the measured Wanderer workload and its include, sharing and reachability reduced
full output from 22,055 to 9,859 lines and none output from 13,963 to 6,239 lines
(about 55%). These are source-size results for one workload, not a runtime speedup.

Compatibility

The C runtime ABI, RuntimeBridge ABI and HTNAtom layout are unchanged from 2.0.4.
Use matching CRT/instrumentation variants. Regenerate and recompile domains to use
the new features and reductions. Rebuild clients of the extended C++ compiler APIs
and update exhaustive error-reason switches for NonBooleanConditionResult.

full remains the default. none omits generated debugger/profiling output while
retaining validation, ownership, runtime errors and source locations. It does not
strip author-written debug callterms.

Validation and platform

• Windows x64 / Visual Studio 2022, MSVC v143.
• Complete source suites: 335 Debug, 326 Profile and 326 Release tests passed.
• Eight SDK variants, 24 external consumer executions and eight object/export checks.
• Allocation and hot reload pipeline self-tests passed; invalid CRT/variant selections rejected.
• The client reported successful engine integration smoke testing.
• Final documentation packaging preserved the validated binaries, headers and examples.

Native Linux validation and comparative performance profiling remain pending.
Hot reload requires client-owned loading, lifetime management and synchronization.
The project remains under active development.

Download

• HTNSDK-2.1.0-windows-x86_64.zip
• HTNSDK-2.1.0-windows-x86_64.zip.sha256

SHA-256:

8ab1f66e957404e5e980aa0969a371584171f3981c2b3ac3ec83f70e6bf1d6ea

Full release notes and migration
| Domain language guide

HTN Planner v2.0.4

Release date: 2026-09-30.
Windows x64/MSVC v143 is the validated distribution target.

Compatibility warning: this version changes the public callterm error API,
generated planner descriptor and RuntimeBridge ABI. Despite the patch number,
it does not provide the usual SemVer patch compatibility guarantee. Replace
any earlier local 2.0.4 candidate and rebuild everything with matching headers.

Changes

• Generated methods and compound tasks run through an iterative dispatcher.
  Suspended calls occupy a fixed array in each execution storage instance;
  the recursion machinery adds no external runtime component or bridge function.
• HTNTranslator --call-frame-capacity=N controls that array (default 8192).
  Exhaustion returns HTN_DECOMPOSITION_CALL_FRAME_CAPACITY_EXCEEDED, unwinds
  the attempt and leaves storage reusable. Its diagnostic includes the domain,
  configured capacity and regeneration option.
• Definition->get_execution_info(storage) exposes capacity, peak frames,
  bytes per frame and last error. The result is borrowed; peak/error reset on
  each decomposition. No change to existing decomposition status numeric values.
• HTNCallTermErrorPolicy extends missing-call reports to argument count/type
  mismatches and argument/return conversion failures. Nested calls and task
  arguments use the same callback, once per failed invocation, with source data.
• Axioms can assign their unused output/IO parameters and propagate results
  through the caller and backtracking. Pure output arguments must arrive unbound;
  assignment to a bound IO slot fails before evaluating its initializer.
• Unknown variables in axiom expressions are rejected with located diagnostics.
• Generated debugger rows now preserve source expressions, nested calls and
  parentheses. Internal lowering assignments and temporary variables are hidden
  from the tree and watch; results, source locations and retries are retained.

Engine migration

1. Install this SDK separately from the previous published version. Use matching
   CRT and instrumentation variants for all headers, libraries and modules.
2. Replace Core/HTNMissingCallTerm.h with Core/HTNCallTermError.h.
   Rename HTNMissingCallTermPolicy/Reason/Info/Callback to
   HTNCallTermErrorPolicy/Reason/Info/Callback, and update custom error switches.
3. Configure CallTermErrorPolicy / CallTermErrorCallback directly on
   HTNPlannerExecutionContext. Core generated hosts use callterm_error_policy
   / callterm_error_callback. Keep ClientContext / client_context borrowed
   for the duration of execution. Initialization validation uses the new callback
   type; runtime argument checks require actual invocation values.
4. Rebuild copied integration code. Regenerate every domain using the new
   translator; rebuild the host, RuntimeBridge and generated objects/DLLs together.
5. Review axiom calls: use a fresh unbound variable for ?out_; use ?io_
   for bound-value matching. Assignment to an already bound IO slot fails.
6. Test deep planning and inspect peak frames. Increase --call-frame-capacity
   if needed, or reduce it to suit the client's memory budget, then regenerate.
   The capacity counts suspended generated method/task frames, not entities.
7. Update copied debugger renderers to respect TitleToken.SpaceBefore. Rebuild
   the host and regenerate instrumented domains for the new debug metadata layout.

auto& execution = planningUnit.GetExecutionContext();
execution.ClientContext = &engineContext;
execution.CallTermErrorPolicy = HTNCallTermErrorPolicy::Report;
execution.CallTermErrorCallback = ReportCallTermError;
// void ReportCallTermError(void*, const HTNCallTermErrorInfo*);

The client chooses how to handle Report (log, assert or terminate).
FailSilently suppresses reports. Unset retains its SDK assertion behavior
when an invocation error occurs. An ordinary callable result of false/unbound
does not itself constitute an invocation error.

ABI	Plain	Decomposition debug	Profiling	Debug + profiling
Planner	0x48540007	0x48550009	0x48560007	0x48570009
RuntimeBridge	0x48580008	0x48590008	0x485A0008	0x485B0008

Old descriptors/tables are rejected. HTNAtom layout remains unchanged.
Packaged variants include plain and decomposition debug; advanced profiling
is not enabled in the standard eight-variant distribution.

Capacity and memory

The 1000-entity ComplexScenario regression reaches 3843 of 8192 frames. Its
execution storage is 2,366,984 bytes per instance in the measured builds.
This is one workload: 100 original mixed-behavior entities plus 900 idle entities.
It is neither a general 1000-entity limit nor a guarantee for other domains.
Capacity determines fixed per-instance memory; tune it for the target game.

Validation

Current debugger correction

The complete public solution built in Debug and Release. All 244 Debug tests
and 235 Release tests passed on 2026-09-30. Logs:
build/logs/public-port-debugger-Debug-tests.log and
build/logs/public-port-debugger-Release-tests.log.
The SDK was rebuilt with this correction on 2026-09-30 (build ID
c9d2878ef0084464964c779ce7cf4cd0). All eight variants passed validation
from a fresh ZIP extraction: 24 external consumer executions and eight
domain-object/bridge-export checks. Incompatible CRT selections and unknown
variants were rejected. All 184 payload checksums and the archive SHA-256
were verified, including the updated instrumented planner ABI 0x48550009.
Local validation evidence: build/logs/release-2.0.4-sdk-audit.json and
build/logs/release-2.0.4-sdk-validation/.

Release notes were finalized after validation and the archive was repackaged.
Every binary, header, example and build-provenance file was verified unchanged
against the validated archive. Earlier local 2.0.4 packages must be replaced.

Earlier candidate (before the debugger metadata correction)

• Complete public solution built in Debug, Release and Profile.
• Full suites passed: 242 Debug tests, 234 Release tests and 234 Profile tests.
• Regression coverage includes non-tail/mutual recursion, deep rollback,
  capacity exhaustion/reuse, debugger completion, nested callterm reports and
  axiom/IO assignments.
• All eight SDK variants passed packaging and extracted-package validation:
  24 external consumer executions and eight domain-object/bridge-export checks.
• Incompatible CRT selections and unknown variants were rejected. Checksums,
  build provenance, ABI metadata and source isolation passed validation.
• Allocation-probe and hot reload pipeline self-tests passed, including invalid
  candidates, rollback and restoration of the original DLL.

Comparative performance profiling and native Linux validation remain pending.
Hot reload support still requires client-owned loading, lifetime management and
synchronization. Each client must validate integration in its own engine.

See recursion, callterm errors,
axiom assignments and
debugger correction for full details.

HTN Planner v2.0.3

Release date: 2026-09-29.
Windows x64/MSVC remains the validated distribution target.

Compatibility warning: despite the patch version, this update changes domain
syntax and the generated planner descriptor ABI. It is not a drop-in replacement
for 2.0.2 and does not follow the usual SemVer patch compatibility guarantee.

Changes

• Explicit variable declarations: (= ?distance (call get_distance ?from ?to)).
  The destination must be fresh. Implicit (?distance (call ...)) is rejected;
  == remains equality comparison.
• Nested callterms are evaluated in comparisons, arithmetic and arithmetic task
  arguments. Missing-call reports point to the actual call expression.
• HTNCallTermRegistry::ValidateGeneratedCallTerms checks registrations, bindings
  and instances without invoking calls. Every original call site is checked,
  including linked sources; repeated IR copies are deduplicated.

Engine migration

1. Keep the previous SDK for rollback; install 2.0.3 separately.
2. Replace headers, libraries, translator and matching RuntimeBridge from the same
   package and CRT/instrumentation variant. Rebuild copied integration code too.
3. Migrate implicit assignment syntax to explicit = declarations of fresh
   variables. Keep == comparisons unchanged.
4. Regenerate all domain C sources and rebuild their objects/DLLs and the host.
5. Configure registry bindings and instances, then validate the definition:

const bool Ready = Registry.ValidateGeneratedCallTerms(
    *Definition, Bindings, ReportMissingCallTerm, ClientContext);

The callback uses HTNMissingCallTermCallback. Handle a false result in the engine's
initialization code. Keep runtime missing-call policy configured and revalidate
following hot reload or binding changes.

Planner ABI values: plain 0x48540005, instrumented 0x48550006, profiling
0x48560005, instrumented/profiling 0x48570006. Old modules are incompatible.
HTNAtom layout and RuntimeBridge function signatures/revision are unchanged from
2.0.2; nevertheless use the matching rebuilt package throughout.

Validation

• SDK: all eight variants, 24 consumer executions and eight object/export checks passed.
• Incompatible CRT selections and unknown variants were rejected.
• Public source suites: 226 Debug tests and 218 Release tests passed before export.
• Engine integration: the maintainer confirmed successful compilation and operation.
  Initialization validation helped identify callterms missing from daemon registrations.

The engine confirmation does not claim separate manual coverage of every missing
reason or hot reload scenario; automated tests cover the documented missing reasons.

HTN Planner v2.0.2

Fixes

• Fix missing HTNAtom_SetInt and HTNAtom_SetFloat exports in RuntimeBridge.
• Improve hot reload validation and rollback coverage.
• Strengthen SDK packaging and generated DLL regression tests.

Upgrade requirements

RuntimeBridge ABI revision is now 7. Rebuild the host, RuntimeBridge and generated domain modules together.
Planner and HTNAtom layouts remain unchanged.

Validation

• 209 tests passed.
• Hot reload self-test passed.
• All 8 SDK variants passed: 24 consumer executions and 8 object/export checks.

HTN Planner 2.0.0

HTN Planner 2.0.0 — 2026-09-23

Windows x64 / MSVC v143 remains
the supported SDK target. Linux support is not included in this release.

Features and fixes

• Method and axiom overloads resolve by name and argument count, including
  includes, qualified calls, recursion and deferred method calls.
• Arithmetic arguments are evaluated before compound tasks, primitive tasks,
  callterms and axioms. Backend diagnostics retain source provenance.
• Nested axiom alternatives preserve output and IO bindings across backtracking.
  Already-bound outputs unify with candidates instead of being overwritten.
  Resuming alternatives does not replay earlier host effects.
• Deferred methods use &; # is reserved for axiom conditions. Incorrect
  prefixes in task lists produce a located diagnostic.
• Client services and missing-callterm handling are configured on the execution
  context. Reports distinguish unregistered names, missing bindings and missing
  daemon instances.
• Lexer/parser/include errors carry typed diagnostics and source locations.
• Use cases explain integration patterns and client responsibilities.
• An isolated ClangCL smoke build prepares future portability work. It is not
  certification of the complete toolset or Linux/GCC compatibility.

Migration from 1.1.0

This update contains source, domain syntax and binary incompatibilities. It is
not a drop-in SDK replacement. The major version increment reflects these
incompatibilities. Review this migration before upgrading.

1. Change deferred calls in task lists from #method to &method. Keep #axiom
   in conditions. Do not perform a global replacement of #.
2. Add void* inClientContext as the first parameter of custom converter
   FromAtom and ToAtom functions. Forward it to nested conversions. See
   type conversions.
3. Configure Unit.GetExecutionContext().ClientContext, MissingCallTermPolicy
   and, for Report, MissingCallTermCallback. Core clients use the corresponding
   fields on HTNGeneratedPlannerContext. Unset asserts if a missing callterm
   is reached; it is not a configured fallback. See missing callterms.
4. Adapt direct registry calls to supply an execution context. Bindings retain
   registry/daemon information; runtime options belong to each execution.
5. Revalidate domains that relied on overwriting a bound ?out_ value. A different
   candidate now fails/unifies normally and may cause backtracking.
6. Regenerate all domain C and rebuild the host, SDK libraries and domain modules
   together. Do not mix old generated objects or bridge DLLs with this SDK.

Generated planner ABI identifiers are 0x48540004 (plain), 0x48550005
(decomposition), 0x48560004 (profiling) and 0x48570005 (both).
The runtime bridge revision is 6; use the ABI identifiers from the selected
package variant's manifest and validate definitions before adoption.

Boundaries

Primitive actions, cancellation, file watching, compilation, module loading and
safe hot reload are client responsibilities. The repository provides integration
examples. Callterm side effects are not rolled back when planning fails.

The public source and SDK contain only the generated planner path.

SDK validation

On 2026-09-23, the Windows SDK passed all eight variant checks and 24 external
consumer executions. The negative checks correctly rejected incompatible CRT
linkage and an unknown variant. These results cover the packaged core, reference
integration and dynamic-domain consumers; they do not establish Linux support.

HTN Planner 1.1.0

HTN Planner 1.1.0 adds builtin numeric expressions to generated domains.

Highlights

• Integer and floating-point arithmetic with +, -, *, / and %.
• Unary increment and decrement expressions with ++ and --.
• Nested arithmetic expressions as operands in builtin comparisons.
• Runtime type validation for numeric operands.
• Runtime failure for division or modulo by zero.
• Numeric expression domain available in HTNDemo.

Validation

• Validated all eight Windows x64 SDK variants.
• Passed 24 isolated external consumer executions.
• Verified nested and mixed arithmetic through the generated execution path.
• Verified failure cases for division by zero and invalid operand types.
• Verified rejection of incompatible CRT linkage and unknown SDK variants.

Compatibility

This release retains the existing generated planner and runtime bridge ABI identifiers. Existing 1.0.0 integrations remain source and binary compatible.

Supported platform

• Windows x64.
• Visual Studio 2022 and MSVC v143.
• CMake 3.25 or newer for packaged SDK consumption.

HTN Planner 1.0.0

HTN Planner 1.0.0

HTN Planner 1.0.0 is the first stable public release of the generated planner,
compiler toolchain and Windows x64 SDK.

Highlights

• Ahead-of-time compilation from domain source to native C.
• Compiler-owned lexer, AST, validation, linking and IR pipeline.
• Generated runtime with configurable fact, axiom and hierarchical backtracking.
• World state, lists, callterms, includes, overrides and deferred domain calls.
• Generated execution debugger with source locations and bound values.
• Optional C++ integration with planner hooks and active-plan handling.
• Runtime bridge and example pipeline for dynamically loaded domains and hot reload.
• SDL and ImGui visual demo with complex example domains.
• Editor, language server and VS Code language support.

SDK

The Windows x64 package supports MSVC v143, C++20 clients and C11 generated
domains. It contains eight variants covering /MT, /MTd, /MD and /MDd,
with plain and instrumented execution contracts.

The release gate builds every variant and runs 24 isolated consumer executions,
including direct runtime use, the reference integration and dynamic domain modules.

Engine integration validation

The SDK has been integrated into an external game engine with customized hooks,
planning units, resource conversion, engine-specific callterms, visual debugging
and dynamic domain hot reload. This integration exercises the public ABI and package
outside the planner repository.

Supported platform

• Windows x64.
• Visual Studio 2022 and MSVC v143.
• CMake 3.25 or newer for packaged SDK consumption.

See the SDK distribution guide, variant matrix
and release checklist for the complete contract.