Paradox Modding Toolkit

A language workbench for Paradox mods. Crusader Kings III, Victoria 3 and Europa Universalis V: a real script parser, scope-aware completion, instant diagnostics for the bugs the game swallows in silence, deep tiger integration, a visual GUI editor, and a localization workflow no other tool has.

Install · What you get · Outside VS Code · Repo layout · Docs

Beta (0.3.0). Young project, useful day to day, rough edges included. Bug reports and missing-feature complaints are the point, not a nuisance: open an issue.

Install

Search for Paradox Modding Toolkit in the VS Code Extensions view, or:

ext install JDeffner.px-toolkit

Then open your mod folder and run Paradox: Run Setup & Health Check. It finds the game, checks the dump folder, and offers to download tiger. The default amount of configuration is none. Full walkthrough: Getting Started.

What you get

The Project panel: the game is auto-detected, and every workspace mod carries its own toggles for indexing and for which mod the views follow.

Simulate Event walks an event beside its source, with each option and the effects it runs.

Select a node in the event graph: blue is what it fires, orange is what fires it.

• Completion that knows the grammar and the scope. Key positions offer triggers and effects, value positions offer traits, events, on_actions and loc keys, and scope:, culture:, title: prefixes complete their referents. Items valid in the current scope rank first. Nothing is hidden.
• Diagnostics for the silent-failure class. Unbalanced braces, a missing UTF-8 BOM, a loc header that disagrees with its filename, localisation/ instead of localization/, references to events that do not exist. These are the bugs that make the game ignore your file without a word.
• tiger, integrated. Auto-download of ck3-tiger or vic3-tiger, reports as native Problems, dependency mods passed through as load_mod, and a baseline workflow so a legacy mod shows only new findings.
• A visual GUI editor. A pixel-accurate rendering of your window that you can work in: click to select, drag, resize, edit properties. Every change is one surgical text edit and one undo, and the editor refuses gestures the engine would ignore instead of writing a line the game drops.
• Localization that keeps up. Inline loc as inlay hints, BOM-correct editing, a coverage view, and scaffolding for entire translation mods.
• Event tooling. An interactive event graph, a static event simulator that walks a whole chain, and a mod report you can read top to bottom.

The full tour with screenshots is the Feature Overview.

Which games

	Crusader Kings III	Victoria 3	Europa Universalis V
Language support	full	full	full
Folder schema	verified against a live install	verified against a live install	community-sourced, not yet verified
Deep validation	ck3-tiger	vic3-tiger	none exists yet
Visual GUI editor	yes	no	no

CK3 is where the toolkit grew up and where every feature exists. The exact per-game limits, the detection ladder and the EU5 honesty note are on Supported Games.

Not just VS Code

The language server is standard LSP over --stdio and runs from neovim, Zed, Helix or your own application. Grab px-lsp-server-<version>.tar.gz from the releases, or px-lsp-win-x64-<version>.zip for one download that already contains Node and a launcher.

• packages/server/README.md covers standalone setup and the per-language capability table.
• docs/EMBEDDING.md covers embedding the server in your own application: the process contract, initialization options and the paradox/* methods beyond standard LSP.
• docs/PROTOCOL.md is the method-by-method wire reference.

Repo layout

pnpm monorepo. The extension is a thin client; all parsing and analysis lives in a separate server process, and everything game-specific sits behind one GameProfile boundary that CI enforces.

Package
packages/vscode	The Paradox Modding Toolkit extension, the primary client. Its README is the user-facing one.
packages/server	@px-lsp/server: parser, index, scope engine, features, per-game profiles, bundled data. Speaks node-ipc and --stdio.
packages/protocol	@px-lsp/protocol: the wire contract and the helpers shared between server and clients.

Development

pnpm install
pnpm run compile     # esbuild bundles dist/extension.js (client) + dist/server.js
pnpm run typecheck
pnpm test            # vitest

Corpus-gated tests and dev scripts read machine paths from dev-paths.json (copy dev-paths.example.json). Architecture, conventions and the release recipe are in AGENTS.md. Working with a total conversion or a dozen mods at once? docs/PERFORMANCE.md has the measured costs and the settings that shrink them.

Contributing

Concrete examples from real mods are the most useful thing you can send.

• Issues for bugs, false diagnostics and feature ideas. Wrong or missing folder mappings, especially for EU5, have their own "Schema gap" form.
• Pull requests are welcome. The per-game schema tables (packages/server/src/games/<game>/schema.ts) are deliberately small and community-editable, so adding a folder kind is a good first contribution.
• Fork it and take what is useful. It is GPL-3.0-or-later, so keep distributed derivatives open.

License

GPL-3.0-or-later, see LICENSE. Bundled third-party data keeps its own terms: the CK3 wiki token lists are CC BY-SA 3.0 (ATTRIBUTION.md) and the EU5 schema import is MIT (THIRD-PARTY-NOTICES.md). No game assets are redistributed.