CK3 Modding Toolkit for VS Code

Crusader Kings III mod development, end to end: a language server with a real Paradox-script parser, scope-aware completion, instant diagnostics for the silent-failure class of bugs, deep ck3-tiger integration, a live mod overview, and a localization workflow no other tool has.

Early alpha (0.1.1). This is a young project and things will change. It is already useful day to day, but you will hit rough edges. Feedback is not just welcome, it is the point: see Contributing below.

Highlights

• Scope-aware completion: key positions offer verbs (triggers/effects), value positions offer nouns (traits, events, on_actions, loc keys), and scope:, culture:, title: prefixes complete their referents. Items valid in the current scope rank first; others are annotated, never hidden.
• Hover docs with texture previews: merged script_docs and wiki docs, the live scope chain at the cursor, resolved loc text, and inline .dds image previews from a pure-TS DDS decoder.
• Structural diagnostics for the bugs the game swallows silently: unbalanced braces, missing UTF-8 BOM, loc header/filename mismatches, folder traps (localisation/, plural on_actions), references to events that do not exist.
• Deep ck3-tiger integration: auto-download, run on save or manually, JSON reports as native Problems, and a baseline workflow to adopt tiger on a legacy mod (suppress today's reports, see only new ones).
• CK3 sidebar: mod overview, localization coverage, overrides and conflicts (with the LIOS/FIOS winner), an interactive event graph with a node inspector, and a GUI widget tree.
• DDS and images: zoomable .dds preview, a PNG/JPEG/WebP to DDS converter in the explorer right-click menu, and CK3: Show Image Guidelines with the sizes vanilla actually uses.
• Localization workflow: inline loc as inlay hints, BOM-correct quick-fix editing, a coverage view, and scaffolds for whole translation mods.
• Content scaffolds: CK3: New Content generates events, decisions, interactions and on_action hooks that are correct by construction.
• Live debugging: CK3: Launch CK3 (debug mode) plus a CK3: Toggle error.log Watcher that surfaces in-game script errors as editor squiggles.
• GUI and data types in .gui files: completion, hover, widget tree, and [Character.GetFather...] data-type chains that resolve through return types.
• Multi-mod workspaces: every workspace mod is a first-class mod, indexed together, with per-mod tiger baselines and no "primary mod" to configure.
• Bundled 10-chapter tutorial (CK3: Open Tutorial) with every snippet verified against the game files.
• A Claude/agent skill for CK3 modding ships in skills/ck3-modding/ for AI-assisted modding.

Quick start

1. Install the extension, open your mod folder, and run CK3: Run Setup & Health Check. It finds the game via Steam, checks the logs folder, and offers to download ck3-tiger. The walkthrough covers the rest.
2. (Recommended) Launch CK3 with -debug_mode, open the console (`), run script_docs, then run CK3: Reload Game Data (script_docs). This upgrades the token data from the bundled wiki lists to your exact game version.

The default configuration is nothing: open your mod folder(s), run Setup once, and everything else is optional. Full walkthrough and every setting are in the wiki: Getting Started and Configuration.

Documentation

The full docs live in the wiki:

• Home
• Getting Started
• Editor Features
• Sidebar Views
• DDS and Images
• Configuration
• Multi-Mod and Translation
• Claude Skill
• Credits

Contributing & feedback

This is an alpha 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.
• PRs are welcome. The schema table (shared/src/schema/ck3Schema.ts) is 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.

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: client/ (VS Code integration) · server/ (language server: parser, index, scopes, features) · shared/ (types, wire protocol, schema table) · 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. Design rationale and the full plan are in docs/rework-plan.md and docs/research.md.

Acknowledgements

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

• ck3-tiger by amtep, the validator behind the diagnostics integration.
• cwtools and cwtools-vscode, for the landscape and design inspiration.
• jesec/ck3-modding-wiki, the source of the bundled fallback token lists in wikidocs/ (CC BY-SA 3.0, see wikidocs/ATTRIBUTION.md).
• Paradox's own in-game _*.info format docs, the primary ground truth for the schema layers. No game assets are redistributed.

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 (wikidocs/ is CC BY-SA, see wikidocs/ATTRIBUTION.md).