prettier-plugin-pdx-script weekly downloads statistics

prettier-plugin-pdx-script

A Prettier plugin for formatting PDXScript (Paradox game script) files. Powered by tree-sitter-pdx_script.

Overview

PDXScript is the scripting language used in Paradox Interactive games such as Victoria 3, Hearts of Iron IV, Stellaris, Europa Universalis IV, and Crusader Kings III. These scripts are distributed as .txt files with nested key-value and block structures.

This plugin provides automatic, consistent formatting for PDXScript files using Prettier. It uses a tree-sitter WASM parser to reliably parse PDXScript, then applies opinionated formatting rules. The parser is compiled from tree-sitter-pdx_script, a tree-sitter grammar for Paradox script files.

Installation

npm install --save-dev prettier-plugin-pdx-script

Prettier will automatically discover the plugin. No additional configuration is needed.

Usage

# Format a single file
npx prettier --write path/to/file.txt

# Check formatting without writing
npx prettier --check path/to/file.txt

# Format all .txt files in a directory
npx prettier --write "path/to/scripts/**/*.txt"

Formatting Rules

Rule	Before	After
Indentation	4 spaces or mixed	Tabs (one per nesting level)
Empty blocks	my_decl = { }	my_decl = {}
Block values	key = { nested = val }	key = {<br>    nested = val<br>}
Comments	# comment	# comment
Operators	Preserved as-is	=, >, < all supported

Example

Input:

my_declaration={
    key1= value1
    key2 =value2
    nested={
        inner_key = "hello world"
    }
    # a comment
}
another_decl = { }

Output:

my_declaration = {
	key1 = value1
	key2 = value2
	nested = {
		inner_key = "hello world"
	}
	# a comment
}
another_decl = {}

Architecture

The plugin follows the standard Prettier plugin architecture with three components:

Input Text
    │
    ▼
┌──────────────┐
│   Parser     │  tree-sitter WASM parser + AST conversion
│  (index.ts)  │  Converts tree-sitter SyntaxNodes → plain objects
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Printer     │  Walks the AST, produces Prettier Doc output
│(printer.ts)  │  Handles each node type with specific formatting rules
└──────┬───────┘
       │
       ▼
  Formatted Text

Key Design Decisions

1. Tree-to-plain-object conversion: Tree-sitter nodes use JavaScript getters (e.g., node.children is computed), but Prettier's path.map/path.call traverse node properties directly. The convertTree() function in index.ts converts the tree-sitter AST to plain objects that Prettier can navigate.

2. Tab indentation: Paradox script files conventionally use tab indentation, which is preserved in this plugin.

3. Operator preservation: The =, >, and < operators in key-value pairs are preserved from the source. They are anonymous tokens in tree-sitter (not in namedChildren) and are found by iterating node.children.

CJS / ESM Dual Support

This package ships both ESM and CJS entry points:

{
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./dist/tree-sitter/tree-sitter-pdx_script.wasm": "./dist/tree-sitter/tree-sitter-pdx_script.wasm",
    "./package.json": "./package.json"
  }
}

ESM consumers use import, CJS consumers use require() — no dynamic await import() needed.

The grammar WASM is also accessible via require.resolve("prettier-plugin-pdx-script/dist/tree-sitter/tree-sitter-pdx_script.wasm") for use with setGrammarBinary().

API

setGrammarBinary(loader)

Override the grammar WASM binary loader. Use this when bundling the plugin (e.g. in a VS Code extension) where the WASM file cannot be loaded from the plugin's package directory.

import { setGrammarBinary } from "prettier-plugin-pdx-script";

// Load from a bundled Uint8Array
setGrammarBinary(() => myWasmBinary);

getGrammarBinary()

Get the current grammar binary loader function. Useful for wrapping the default loader or testing.

setLocateFile(fn)

Override the locateFile callback used to locate web-tree-sitter's own runtime WASM (tree-sitter.wasm). This is passed directly to web-tree-sitter's Parser.init({ locateFile }).

Use this when bundling the plugin and the default resolution (relative to scriptDir) does not point to the correct location.

import { setLocateFile } from "prettier-plugin-pdx-script";

setLocateFile((fileName, _scriptDir) => {
  return path.join(__dirname, "wasm", fileName);
});

Important: setLocateFile() must be called before any parse() invocation (same constraint as setGrammarBinary()).

getLocateFile()

Get the current locateFile callback. Useful for wrapping the default resolver or testing.

Bundling

When bundling this plugin (e.g. in a VS Code extension or webpack/esbuild build), the default WASM loading may fail. There are two WASM files to account for:…