Paradox Modding Toolkit

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

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

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

Start editing

1. Install Paradox Modding Toolkit (JDeffner.px-toolkit), then open Start Here in the PX Toolkit sidebar. Create a mod or find an existing one by name. Add it to the current workspace to see its files in Explorer, or open it in a new window.
2. Run Paradox: Run Setup & Health Check. Check the detected game, mod and data paths. CK3 and Victoria 3 include vocabulary snapshots; EU5 needs your own script_docs dump.
3. Open a script file. Completion offers engine words and indexed definitions; hover explains the word under the cursor. The Project panel opens the visual tools and publishing commands. Use Paradox: Validate Mod from the Command Palette to check your mod.

New to modding? Start with Getting Started. The VS Code Setup Guide shows installation, game setup and a first edit.

This is a beta. Check generated content in the game before publishing it. After game patches, regenerate your dumps to match the installed version.

The upcoming 0.6.0 update is prepared as the 0.5.5 prerelease. Its changes are listed under 0.6.0 in the changelog.

At the cursor

• Toolkit Settings: open Project > Settings > All settings for one searchable catalogue. Each setting shows its save destination and active source, with destination controls on the row. Question-mark help appears on hover or keyboard focus. Drafts survive context changes, and stale saves leave newer values intact.

• Live editing: suggestions, navigation and rename follow unsaved edits. Problems update when referenced events or required translations change in another file.

• Completion templates: choose Minimal, Examples or Names with px.completion.mode. Preview inserted code and expected values, or run Paradox: Export Generated Snippets (HTML / Print) to browse, copy and print the full catalogue.

• Completion and navigation: scope-aware ranking, definitions, references, rename, symbols and block skeletons. Items outside the inferred scope are annotated rather than hidden.

• Documentation from the game: hover descriptions, scope information, localized text and texture previews, plus searchable vanilla examples.

• Graphics assets: CK3 and Victoria 3 .asset indexing, context-specific completion, reference navigation and DDS previews. Use px.indexAssets to toggle scanning.

• Section folding: ### Title or longer hash headings fold through the next heading or the end of the file, across closing braces.

• Validation: instant structural checks for malformed files, encodings and folder mistakes. CK3 and Victoria 3 also integrate tiger for deeper validation.

• Localization: coverage, inlay hints, quick fixes and workflows for adding languages or making a translation mod. File and folder actions reuse owned entries, follow related localization files and offer mod-specific author defaults.

• Project settings: shared authoring rules travel with .px-toolkit/project.json; personal paths stay in your VS Code User profile. Both are available in the same settings catalogue. Existing settings upgrade with conflict reporting and source preservation.

• Mod Compatibility (experimental): exact game-version routes, reusable compatibility notes and migration recipes, required choices, reviewed changes and recovery. Includes CK3 faith/rite and portrait mask mip migrations. A custom faith and mask fixture passed CK3 1.20.0.3 playtesting, including a separate clothes-gene merge; this does not establish compatibility for other mods. Enable px.experimentalFeatures to try it.

• Compatibility Patch (experimental): combine an ordered set of CK3 mods, save contribution and field decisions, and review affected choices after updates. Build a separate patch with guarded writes, preservation of manual output edits and recovery. Unsupported work stays visible. Enable px.experimentalFeatures to try it.

• Context actions: right-click files, definitions, overrides and localization references to open, compare or edit the selected source. Project shows the current mod, with All Tools and Customize in its title bar.

• BBCode preview: choose BBCode Preview from VS Code's editor selector or open it beside the source. Preview includes unsaved edits and preserves the BBCode language mode.

Build and inspect content

The Flag Builder, Coat of Arms Designer and DDS viewer have bottom-left background controls: dark, light, custom color and reset. Each tool remembers its choice in the workspace.

The Event Simulator walks an event and its options beside the source. The Event Graph follows firing chains and lets you edit event content. Both are static tools; they do not execute the game.

The GUI Editor lets you select, move and resize widgets, inspect inherited properties and save source-preserving edits. Its preview models supported layout rules; runtime bindings still need an in-game check. CK3 also has forms for traits, cultures, traditions, legacies, dynasties and coats of arms. Victoria 3 and EU5 have the Flag Builder.

The Dynasty Tree supports copying DNA for mod files or the game, including lookup in dependency mods and pasting portrait-editor DNA. Character edits preserve comments, spacing, trait groups and detailed death blocks. Choose a death reason and quotation preferences; stale forms retain your draft and leave newer source edits intact.

Convert batches of DDS, PNG, JPEG and WebP images from Utils or file context menus, with progress, cancellation and a choice to skip or overwrite existing outputs. The Project panel also opens game launch options, custom calendars, multi-mod indexing and the Steam Workshop Panel. Workshop uploads use your running Steam client and show the parts being uploaded before confirmation.

DDS conversion offers full or custom mip chains and a reference-matching option for format and mip count. Inspect stored mip levels in the viewer and export the displayed level. Conversion rejects texture arrays, cubemaps and volume textures instead of exporting only one surface.

In the Workshop panel, Create legacy version makes a separate listing for a game version. Its first upload can use the current project files or a saved mod ZIP. Later uploads change Workshop information only, so keep a separate project if you need to update legacy mod files. Stop waiting ends a stalled wait without retrying the upload; check Steam before trying again if the result is uncertain.

Choose your workflow

Game and client support

EU5's schema is community-sourced and has not been verified against a live install. Read Supported Games for the full matrix and dump commands.

The standalone language server is available as @px-lsp/server, with a tested Neovim setup. Zed and Helix integrations are currently unverified. Application authors can use the Embedding guide, including the browser library. Tiger and the visual tools remain VS Code features.

AI-agent modding skills live in the separate paradox-ai-modding project.

Contributing & feedback

This is a beta shaped by the people who use it. The best thing you can do is tell me what breaks and what is missing:

• File an issue for bugs, false diagnostics, or feature ideas. Concrete examples from real mods are gold. Wrong or missing folder mappings, especially for EU5, have their own "Schema gap" issue form.
• PRs are welcome. The per-game schema tables (packages/server/src/games/<game>/schema.ts) are deliberately small and community-editable: adding a folder kind or loc requirement is a good first contribution.
• Fork it and take inspiration. If a piece of this is useful in your own tooling, use it. It is GPL-3.0-or-later, so keep distributed derivatives open.
• Join the Discord for release notes, quick questions and modding help. The extension links to it from the bottom of the Project panel and from Paradox: Join the Discord.

Dev quickstart

pnpm install
pnpm run compile      # esbuild bundles dist/extension.js (client) + dist/server.js
pnpm run typecheck
pnpm test             # vitest; copy dev-paths.example.json to dev-paths.json to also run the vanilla corpus suites

Layout (pnpm monorepo): packages/vscode/ (this extension) · packages/server/ (language server: parser, index, scopes, features, per-game profiles, bundled data) · packages/protocol/ (types, wire protocol, shared helpers) · packages/*/test/ (vitest suites incl. corpus/fixture tests). The extension is a client/server LSP split: the thin client runs in the extension host, all parsing and analysis lives in a separate server process. Everything game-specific sits behind one GameProfile boundary that CI enforces. The architecture map and conventions are in AGENTS.md.

Acknowledgements

The extension stands on work by others. The key sources and inspirations:

• tiger by amtep, the validator behind the ck3-tiger and vic3-tiger diagnostics integration.
• pngjs (MIT), bundled for PNG decoding that preserves packed mask channels, including RGB under zero alpha.
• yauzl and pend (MIT), bundled for reading legacy mod ZIP archives without loading the archive into memory.
• cwtools and cwtools-vscode, for the landscape and design inspiration.
• kaiser-chris/cwtools-eu5-config, the source of the EU5 folder schema (MIT, pinned commit; the Victoria 3 equivalent was used as a cross-check only). Full notices in THIRD-PARTY-NOTICES.md.
• jesec/ck3-modding-wiki, the source of the bundled CK3 fallback token lists (CC BY-SA 3.0, see ATTRIBUTION.md).
• Paradox's own in-game _*.info format docs, the primary ground truth for the CK3 schema layers. No game assets are redistributed.
• Steam Workshop supplies the public category and compatibility-version tag names bundled for each game's upload picker.

The complete table with licenses is on the Credits wiki page.

License

GPL-3.0-or-later. In short: use, modify and redistribute freely, but any distributed fork or derivative must publish its source under the GPL too. See LICENSE. Bundled third-party data keeps its own terms (the CK3 wiki token lists are CC BY-SA, see ATTRIBUTION.md; the EU5 schema import is MIT, see THIRD-PARTY-NOTICES.md).