Planning Domain Description Language Support
This extension makes VS Code a great place for modeling planning domains.
- planning domain modeling
- planning domain validation by number of regression or scalability test cases
- planning solution industrializing by problem file generation from templates
- plan validation
Extension is activated on any
.pddl files (commonly holding domain or problem definitions) or selected PDDL commands to configure parser and planner.
Creating PDDL files and running the planner
Simplest way to get started is to:
- open a blank folder in VS Code using File > Open Folder...,
- create two blank files using File > New File named
problem.pddl, both files will show up in the Explorer pane, open them side by side in the editor,
- open the domain.pddl file and type
domain. The auto-completion suggests to insert the entire structure of the domain file. Use the Tab and Enter keys to skip through the placeholders and make your selections.
- open the problem.pddl file and type
problem. The auto-completion suggests to insert the entire structure of the problem file. Make sure that the
(domain name) here matches the name selected in the domain file.
- When prompted to configure a PDDL Parser, follow the instructions, or select Later to postpone this if you do not have a PDDL parser handy. See more info.
- When you are ready to run the planner on your domain and problem files (both must be open in the editor), invoke the planner via context menu on one of the file text content, or via the Alt + P shortcut. The planning.domains solver will be used, so do not send any confidential PDDL code.
- Configure your own PDDL planner by following instructions.
Explore VS Code PDDL show-cases
To exercise the features of this PDDL Extension, clone this vscode-pddl-samples repository and open the folder in VS Code. Follow the instructions and explanations in the readme.
You can copy the following URL to your browser's address bar and open it, it will let you select where you want to clone the repo onto your local storage and opens it for you in VS Code - all automated:
Starting from existing PDDL models
Open editor.planning.domains in your browser, select Import from the menu and browse the catalog of all the International Planning Competition benchmarks. Or find more examples here.
Following snippets are supported if you start typing following prefix
domain: creates a domain skeleton
action: instantaneous action
action-durative: durative action
problem: creates a problem skeleton
Commonly used PDDL keywords are highlighted.
Hover, go to definition and find all references
Similar to other programing languages, you can hover over a PDDL predicate, function or type and see the definition. If some comments are placed on the same line, they are also displayed while hovering. The code comments may include markdown syntax.
You can jump to definition of predicates and functions in two ways: Ctrl+click or Right-click > Go to Definition menu.
You can also right click on such symbol and select Find All References.
Jump to Symbol e.g. predicate/function/action
Use the VS Code keyboard shortcut Ctrl + Shift + O to open up the symbol listing. That lists all predicates, functions and actions in the domain file. That way you may review the full list of actions in a concise way and jump to their declaration.
Global predicate/function/type renaming
Put cursor into a predicate, function or type name and press F2 to rename its appearances in the domain file and all associated problem files currently open in the editor.
When typing in the domain or problem file characters such as
:, Visual Studio Code pops up the suggested keywords or names of predicates/functions.
Some PDDL constructs are supported with smart snippets, which are aware of where you are in the document and what is in your model:
PDDL parser can be configured to run in the background and draw attention to syntactic errors, so you can fix them before running the planner. This dramatically shortens the time you need to come up with a valid PDDL.
To learn more about how to configure the extension to work with one of the parsers available or even your own, read this wiki page.
Run the planner and visualize plans
The planner can be invoked in the context of a currently edited PDDL file. There are two ways how to do that via the user interface.
Ctrl + Shift + P and type plan to filter the list of available commands. The PDDL: Run the planner and visualize the plan command should be visible.
- Right click on the PDDL file and select PDDL: Run the planner and visualize the plan
- Alternatively you can set up a keyboard shortcut such as
Alt + P to be associated with the above command (see VS Code documentation for that)
There are multiple scenarios supported:
- if command is invoked on the domain file,
- and if single corresponding problem file is open, the planner will run without asking further questions
- and if multiple corresponding problem files are open, the list of applicable problem files will appear and the user will select one.
- if command is invoked on a problem file, the domain file (if open in the editor) will be selected automatically.
Domain and problem files correspond to each other, if:
- they have the same domain name i.e.
(domain name) and
- they are located in the same folder and
- both files are open in the editor.
Control+click on action names in
.plan files to jump to the action definition in the domain file.
Hide actions from plan visualization
Plan visualization details may be fine-tuned using an additional file
<domain> refers to the domain file name without the
.pddl extension, placed into the same folder as the domain file. Following syntax is supported:
The entries may use regular expression pattern. Note that backslashes in the regex must be doubled up to comply with JSON syntax.
Generate plan report
Plan visualization displays a menu symbol ☰ in the top-right corner, which shows applicable commands. For example the PDDL: Generate plan report, which opens the plan report generated into a self-contained HTML file that you can save and share/email.
Planning with command-line switches
When using a planner executable, further command-line options may be specified.
Auto-completion snippets for symmetric and sequential initialization
Creating a realistic problem files to test the domain may be tedious. Here are several ways to make it substantially faster:
Initializing a sequence of symmetric relationships.
Initializing a symmetric relationships.
Regression testing of PDDL domains
The PDDL Tests explorer tree lists all configured test cases and supports single test execution as well as a bulk test execution.
To add a test case, create a file named
*.ptest.json anywhere in the workspace. This is a simple example:
Use other JSON properties like
expecedPlans to define the test assertion or
options to specify command-line options to use.
Interesting by-product of this feature is that it can be used to give effective demos. Right click on the Open PDDL domain and test problem and both files open side-by-side in the editor. This lends itself well to switching between different models during a presentation/meeting/review.
Problem file generation
In order to test the PDDL domain model and its scalability, it is useful to be able to generate realistic problem files from real data. However, as the PDDL model is under development, so is the structure of the problem files. Those test problem file quickly get out of date and are pain to maintain by hand. There are multiple ways how to generate problem files now. Simplest is to use one of the supported templating libraries, which are powerful enough to satisfy great number of use cases. If that is not sufficient (e.g. data needs to be retrieved from a database, cloud service and heavily manipulated), you can invoke any script or program by specifying the command-line call. Such program, however, must accept the templated problem file on its standard input and provide the actual PDDL via its standard output.
There are several templating options supported out of the box:
But there is a wealth of templating libraries, including Razor see RazorTemplates, which is popular in asp.net, or T4.
For the ultimate flexibility, here is how to configure a Python script to do a custom pre-processing of the problem file:
"label": "Case #1",
"label": "Case #1.1",
"label": "Case #2",
"label": "Case #3",
Note that if you are referring to other files such as Python scripts or JSON data files in the
.ptest.json, you may use relative path i.e. relative to the path, where the
.ptest.json file is located as that is the runtime context in which the pre-processor will be executed.
The templated problem file and the problem file generated using the pre-processed PDDL test case may be open side-by-side and used as a live preview of the code generation.
Problem generation via a Python script
This is what happens if you set
"kind": "python": Before executing the test, the extension runs the
populate_transform.py script using the
python command, pipes the
problem_template.pddl onto it and reads the PDDL output of the script. The script uses the data from the configured .json file in this case, but as this is basically a command-line argument, you could refer to a database table just as well.
If you have multiple python installations (e.g. 2.7, 3.5), there are several ways how to indicate which one you want to use:
- python executable is in the %path%
- you are using the Python extension to select the python runtime
- you simply configure the python executable path via the
python.pythonPath setting property
Normalized plan comparison
Plans from different planners are hard to compare due to different formatting of the output. Normalized diff re-formats the plan, removes all extra lines or comments, orders simultaneous actions alphabetically, shifts plan times (by a convention plans start at time epsilon) and opens the Diff window.
Open file explorer pane, select two .plan files, right-click and select PDDL: Normalize and compare 2 plans.
If the valstep utility (experimental feature) is configured, the diff also includes the final state values. This is useful when you want to check that the plan leads to the exact same goal state despite some minor differences in the action sequence (e.g. different permutations or redundant actions).
Plan final state evaluation
The PDDL: Normalize and evaluate plan command exposes in isolation the transformation used by the PDDL: Normalize and compare 2 plans command. In addition, this is a live preview, which evaluates your plan changes on-the-fly.
A .plan file can be generated using an option in the Plan Visualization menu (☰), or using a PDDL: Export plan to a file... command.
All .plan files have a context menu option PDDL: Validate plan, which requires the
validate executable path to be configured in the pddl.validatorPath setting. See VAL for more details.
Sometimes it is more convenient to create a desired plan by hand and using the
validate tool to find out what is wrong in the domain model. While manually modifying the .plan file, all parsing and validation problems are displayed in the Problems panel of VS Code as long as a corresponding problem and domain files (located in the same folder) are open in the editor and the
validate executable location is configured via the pddl.validatorPath setting.
Plan happenings validation
A context menu option in .plan file PDDL: Convert plan to happenings... supports export to a
.happenings file. This shows the exact temporal sequence of action starts and ends.
This notation is more convenient when checking temporal plans for correctness.
Control+click on action names in
.happenings files to jump to the action definition in the domain file.
This is the syntax supported by the preview:
; timed initial fluent
1.000: (= (available_fuel-truck truck1) 1000)
; timed initial literal
5.000: set (final-approach p1)
5.001: start (land p1 rw1)
5.100: unset (final-approach p1)
7.001: end (land p1 rw1)
; re-occurring actions
10.001: start (land p1 rw1) #2
12.001: end (land p1 rw1) #2
All first occurrences of happenings are
#1 implicitly. Labeling the first occurrence as
#1 is optional.
end label durative span actions. Instructions
unset label timed-initial literals (TILs). Instruction
(= (function) value) is for timed-initial fluents (TIFs).
.happenings back to
.plan, right click on the happenings file and select the PDDL: Convert happenings to plan... command.
Plan Happenings effect evaluation
Plan happenings (.happenings) files may be executed and action effects listed as decorations in the code editor.
For this to work, the setting
pddl.valStepPath must be set with the location of the ValStep utility, which is currently not distributed with the extension.
Plan Happenings -> domain completeness test suite auto-generation
To test robustness of your planning model, you can auto-generate a "plan-resume" re-planning test suite. Open a .happenings file and select
PDDL: Execute plan and generate plan-resume test cases from the context menu. This command executes the happenings and evaluates all intermediate states in the course of the plan. Then it generates a problem file for each of those states (treating them as new initial states) and the same goal. The command then also summarizes all those new problem files into a new test manifest named after the problem file
<problem_file_name>_re-planning.ptest.json, which you can open in the Test Explorer and run as a test suite. You get to select the folder for all the generated files. This way you can test whether your domain model includes actions to recover from possible plan failures. You can then manually edit those generated problem files to model actual plan failure modes.
For this to work, the setting
pddl.valStepPath must be set to the location of the ValStep utility, which is currently not distributed with the extension. There is a known issue with time-initial literals and fluents - they are not re-included into the generated problem files.
Block folding in
:init section of the problem file
For large problem files, it is convenient to be able to fold blocks of statements between
;;) comments lines.
Browsing the Planning.Domains PDDL collection
The file explorer side bar includes a tree displaying the Planning.Domains PDDL collection.
The domain, problem and plan files are downloaded and displayed as read-only files and the planner may be invoked on them as usual.
See unfixed issues and submit new ones here.
For more information