Script editing, visual tools and Steam Workshop publishing for Paradox mods.

For Crusader Kings III, Victoria 3 and Europa Universalis V.

Install · What you get · Use the LSP · Repo layout · Docs

Build with the language server: Install the server · Embed in an application · Wire protocol

Beta. 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

Open Start Here in the PX Toolkit sidebar to create a mod or find an existing one by name. Choose Add to Current Workspace to see its files in Explorer, or open it in a new window. Then run Paradox: Run Setup & Health Check to connect the game. Extra validation is optional. Full walkthrough: Getting Started.

What you get

The upcoming 0.6.0 update is prepared as the 0.5.5 prerelease. See the preview release notes for its scope and validation limits.

Open Toolkit Settings from Project > Settings > All settings to search, filter and reset settings, with an explicit choice of save scope. CK3 character-history edits preserve source formatting and comments. DDS conversion can match a reference texture or write a custom mip chain. Workshop legacy listings keep a separate item for each saved game version; their first upload can use the current project files or a saved mod ZIP, and later uploads change listing information only.

Shared mod rules live in .px-toolkit/project.json; personal game and workspace paths stay in the VS Code User profile. Older settings upgrade on trusted startup, preserving legacy files and reporting conflicts. The optional Mod Compatibility workflow uses exact game-version routes, reusable notes and recipes, human decisions, reviewed edits and recovery. CK3 faith/rite and portrait mask migrations are experimental and off by default. They do not establish target-game compatibility.

The separate experimental Compatibility Patch workflow maintains a patch for an ordered set of CK3 mods. Save how conflicting contributions should combine, review changed decisions after an update, and preserve independent manual output edits. Unsupported rules and assets remain explicit manual work. Both compatibility workflows require px.experimentalFeatures, which is off by default.

Create your first mod with the guided tutorial, convert batches of images, and get suggestions and navigation that follow unsaved edits. Problems update when referenced events or required translations change in another file.

Right-click files, definitions, overrides or localization references to act on that source. The Project panel shows the current mod, with All Tools and Customize in its title bar. BBCode files offer BBCode Preview in VS Code's editor selector and can preview unsaved edits beside the source.

Choose minimal completion templates, full examples or names only, with insertion previews and expected-value hints. Export the generated snippets to a searchable, printable catalogue. The flag, coat-of-arms and DDS tools also offer dark, light and custom preview backgrounds.

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 card in the event graph: blue is what it fires, orange is what fires it, and the inspector edits the event as words. The layout puts time on the x axis, so left to right means "happens after".

The GUI editor draws your .gui file with a measured layout engine and lets you work in it: tree, layers, canvas, inspector, element library.

The Flag Builder (Victoria 3, EU5) composes a coat of arms exactly as the game recolors it, and saves it back as script.

The Examples Wiki searches every trigger, effect and scope the game reported about itself, ranked by real usage count.

The Wiki hub opens references and examples for the selected game, installed launch-option documentation where available, CK3 image guidelines, diagnostics, the workspace mod report and credits.

• 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 (CK3, Vic3). A pixel-accurate rendering of your window that you can work in: click to select, drag, resize, edit properties, insert from a library where every element previews as the game draws it. Every change is a surgical text edit, and the editor refuses gestures the engine would ignore instead of writing a line the game drops.
• A Flag Builder (Vic3, EU5). Compose coats of arms from the game's and your mods' patterns and emblems, drag them on the canvas, and save script.
• A Coat of Arms Designer (CK3). The same job, built the way the game's own designer works: Background, Layout and Emblems tabs, several emblems aligned and distributed at once, a snapping grid, the dynasty, house and title frames at any of their six tiers, and a library outside any mod.
• Visual content creators (CK3). A trait, a dynasty legacy track, a culture, a tradition or a whole dynasty tree as a form over the keys the game documents, previewed with the game's own art and text. Reopening something you already have rewrites only the lines you changed, so your comments and formatting survive.
• Event tooling. An event graph whose x axis is time, with a structured inspector that edits events as words rather than script; a simulator that walks a whole chain; and a mod report you can read top to bottom.
• Localization that keeps up. Inline loc as inlay hints, BOM-correct editing, a coverage view, and scaffolding for entire translation mods.
• DDS tooling. Inline texture previews on hover, a zoomable viewer with PNG export, image-to-DDS conversion, and measured size guidelines.
• Graphics assets (CK3, Vic3). Index .asset files, complete graphics keywords, follow mesh and shader references, and preview textures. Toggle scanning with px.indexAssets.
• Comment sections. Fold ### Title headings through the next heading or the end of the file, across closing braces.
• Dynasty DNA (CK3). Copy DNA for mod files or the game, resolve it across dependency mods, and paste portrait-editor DNA into the selected mod.
• Steam Workshop publishing. Create or update your mod's Workshop item through the running Steam client, no Paradox launcher involved. New items start private and the id is written back into descriptor.mod. A Workshop panel edits the item's description, visibility, required DLC and items, the preview gallery and the per-language translated title and description, shows its statistics, and uploads each part selectively. The listing lives as files beside the mod's content, and a .pxignore decides what an upload leaves out.
• Custom calendars. A total-conversion mod declares its era system in <mod>/.px-toolkit/calendar.json, committed with the mod, and every script date shows its in-game form: 3000.1.1 reads 1000 BC on hover and as an inlay hint.
• A wiki that lists the guides and the other tools. A Modding Guides page per game links every modding page of that game's wiki, and a Modding Tools page collects the validators, translators and editors other modders built, with the ones the toolkit replaces left out.
• Large workspaces are the design case. A game install plus five Workshop mods, all indexed, opens in 61 s cold where it used to take 143, and one command stops VS Code itself crawling the game's textures and audio.

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	yes	no
Flag Builder	no	yes	yes

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.

Use the language server

The language server is standard LSP over --stdio and runs from neovim, Zed, Helix or your own application. It is on npm:

npm install -g @px-lsp/server
px-lsp                       # stdio is the default transport

The releases page carries the same payload for people who would rather not use npm: px-lsp-server-<version>.tar.gz, 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 on npm: parser, index, scope engine, features, per-game profiles, bundled data. Speaks node-ipc and --stdio.
packages/protocol	@px-lsp/protocol on npm: the wire contract and the helpers shared between server and clients.

The pxtk command and local MCP tools are maintained in the separate paradox-toolkit-cli project, which consumes the shared server and protocol packages.

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

The standalone product website and handbook live in website/. Its GitHub Pages build is independent of extension releases. website/DESIGN.md records the visual identity and its sources.

Website sources:

Source	Use	License
Source Sans 3	Website headings, interface and reading text	SIL Open Font License 1.1
Archivo	Website wordmark	SIL Open Font License 1.1
IBM Plex	Website code typography	SIL Open Font License 1.1
Marked	Build-time Markdown rendering	MIT
Playwright	Website browser checks	Apache-2.0

Concrete examples from real mods are the most useful thing you can send. CONTRIBUTING.md covers setup, the F5 dev loop, tests and the PR flow; docs/webviews.md shows how the visual tools are built and how to add one.

• 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.
• Discord for release notes, quick questions and modding help.

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), the EU5 schema import is MIT, and the icons the webviews draw are Lucide (ISC) and VS Code codicons (CC BY 4.0), all in THIRD-PARTY-NOTICES.md. No game assets are redistributed.

PNG conversion bundles pngjs (MIT) to preserve all mask channels. Its license is included in THIRD-PARTY-NOTICES.md.

Source	Use	License
VS Code language-server libraries	LSP transport and bundled server	MIT