Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Cognitive Modeling Language

This is a description of the Cognitive Modeling Language used to describe HTNs and other planning models.

Cognitive model source files consist of a package and a set of domains. Follow the links in the diagram to see details about each element.

package namespace domain


package com.ursafrontier.tutorials

domain games.rings-and-poles



achieves name


action cap_name , { property_definition }


action PlaceRing {
    integer ring
    string pole

Action Invocation

namespace . cap_name ( kwarg , ) event_expectations

And Expression

unary_rel_expression and

And Predicates

and predicate_union ,

The comma (,) separating predicate unions can be spelled and if desired. You may have to use paranethesis to avoid ambiguity since the comma binds looser than the or keyword but the and keyword binds tigher than the or keyword.

Array Type

[ type ]


behavior cap_name { trigger }


behavior PlayRingsAndPoles {
    when PlayGame() {

Binding Variables

? name

Binding variables are used to pull information from the agent state during planning. They may only be used in the preconditions or guards of methods or macros. A collection of guards fails if the binding variables can’t be assigned values that satisfy all the guards.

The planner must be able to assert a set of potential values for each binding variable based on inspecting the predicates in the guard clauses. That is, each binding variable must appear by itself as a predicate argument or as the variable being tested for inclusion in a set. Function calls or other expressions are only used to filter the set of potential values.


take(block) when clear(block), pos(block, ?pos), ?pos != "table", not holding("hand", _) {



[A-Z] - _ [A-Za-z] [0-9]



domain namespace action behavior event function method perception task


event cap_name , { property_definition }

Event Expectation

namespace . cap_name ( kwarg , ) as name is success failure

Event Expectations

{ event_expectation }


name = statement and_expression or


function function_name ( function_arg , ) preconditions { statement }

Function Arg

type name

Function Name

name ?


not predicate name = expression


Map Type

[ type , type ]


name ( function_arg , ) achievement preconditions { method_step }

A method that isn’t tied to a task is considered a macro in automated planning. The planner treats it as if it were a method attached to a task with the same name.

Method Step

action_invocation implies implication , choice calculation task_invocation ( method_step )


[a-z] - _ [A-Za-z] [0-9]


name .


perception name ( function_arg , ) => type

Perceptions are not yet used by any system. They are included for future use.

Perceptions define a function that the cognitive model can use to query the environment. The implementation depends on the environment in which the cognitive model runs, similar to how action adjudication is handled.


implies implication ,


when predicates

Preconditions may not have binding variables when associated with a function definition.


function_name ( predicate_arg , )


predicate_union ,

The comma (,) separating predicate unions can be spelled and if desired. You may have to use paranethesis to avoid ambiguity since the comma binds looser than the or keyword but the and keyword binds tigher than the or keyword.

Predicate Arg

unused_name expression

Predicate arguments in guard clauses may contain binding variables when guarding a method rather than a function. These won’t appear in the syntax diagrams, but they may be used where any variable would be present in the guard expression.

An “unused name” is a placeholdeer variable in a predicate that indicates that the value in that position is not used. That is, when evaluating the predicate, the value in that position is free to be anything. This only works with predicates. For example, the predicate foo(_, 1, _) matches any value in the first and third positions and only matches the value 1 in the second position. Obviously, this doesn’t work with functions since the function operates on the values in the arguments.

Predicate Union

not predicate inclusion relational_expression or

Property Definition

type name = constant

Relational Expression

sum_expression == != < <= > >= sum_expression


expression ( statement )

A parenthesized list of statements has its own scope, so any variables set will be unset when leaving the parenthesis. The value of a list of statements is the value of the last statement in the list.


x = 3
y = (
  x = 4
  x * 2

At the end of this code, x will be 3 and y will be 8.

Sum Expression

product_expression + - product_expression


name ( function_arg , ) preconditions postconditions

When using an HTN planner, task preconditions and postconditions are not evaluated.

Task Invocation


when cap_name ( kwargs ) and_predicates { method_steps }


signed unsigned integer real boolean char string array_type map_type

Unary Relational Expression

not expression rel_expression

Unused Name

_ name