Contributing

How to use contributing in Paradox Modding Toolkit.

The toolkit is GPL and built to be extended. The canonical contributor docs live in the repo and travel with the code:

• CONTRIBUTING.md - setup, tests, the rules that get PRs merged, the PR flow.
• docs/webviews.md - how the visual tools (GUI editor, event graph, Flag Builder, Workshop panel, Examples Wiki) are built, and the checklist for adding a new one.
• AGENTS.md - the full architecture and conventions reference.

This page is the short version, with the development loops spelled out.

What helps most#

Concrete examples from real mods: a script snippet the toolkit handles wrongly, with the file it came from. Wrong or missing folder mappings (especially EU5) have their own Schema gap issue form, and the per-game schema tables (packages/server/src/games/<game>/schema.ts) are deliberately small and community-editable, so fixing one is a good first PR.

Wiki contributions#

Useful guides, tips, tools and examples are welcome too. Contact me to suggest a wiki addition if you think it would help the community. No code contribution is needed.

Setup#

You need Node 22 or newer and pnpm. A game install is not required for most work.

git clone https://github.com/JDeffner/paradox-modding-toolkit.git
cd paradox-modding-toolkit
pnpm install
pnpm run compile

The three development loops#

Pick by what you are iterating on, fastest first.

1. Browser preview, for UI work#

pnpm run preview:webviews
pnpm run preview:webviews -- path/to/some_window.gui

This starts a dev server on http://localhost:5317 with two pages:

• /gallery renders every px-ui component (buttons, menus, dialogs, toasts, color picker, sortable lists) from the live stylesheet. Edit anything under packages/vscode/src/webviews/shared/ and the page reloads on save.
• /gui boots the real GUI editor over a stub host, laying out the .gui file you passed. Nothing is written to disk.

Buttons at the bottom right switch between a Dark and a Light stand-in for the VS Code theme. You get real browser devtools here, which webviews inside VS Code never give you.

2. Live panels, for feature work#

Use the separate PXTK Development profile for toolkit checks. F5 and package:test select it. Before the first test installation, create the profile by launching it:

code --new-window --profile "PXTK Development"

For Live Webview, install the companion into that profile:

code --profile "PXTK Development" --install-extension JDeffner.live-webview

The companion must be enabled in the Extension Development Host. The current development build also needs the built helper from a Live Webview checkout: run pnpm build there and set liveWebviewPath in the toolkit's ignored dev-paths.json, or PX_LIVE_WEBVIEW_PATH, to that checkout. Installing the Marketplace companion alone does not supply the helper.

Select Run Extension + Live Webview and press F5. It builds the development version and starts pnpm run watch:webviews:live. Successful frontend builds reload the affected panels; failed builds keep the current panel. Use the companion's Explorer view to pause, resume or reload an instance, and its logs to inspect callbacks.

Host code, HTML generators and their imported CSS require a rebuild and host restart. Reload restores state that the panel saves or requests from its host; unsaved DOM state can be lost. The normal watch:webviews loop and Run Extension remain available. See the canonical webview guide for the full setup.

3. The packaged artifact#

pnpm run package:test

This compiles, packages and installs the test VSIX into PXTK Development. Reload that window and exercise the affected action through its real entry point. Check the visible or saved result and a relevant failure case. Installation alone is not an editor check. Normal packaging removes the Live Webview helper.

Automated extension-host suites should use disposable user-data and extensions folders under .local/testing/, with the same isolation arguments for installation and launch. Keep generated mods and test outputs in ignored local folders. Never commit a VSIX.

Verify before you push#

pnpm run typecheck
pnpm run lint
pnpm test

Some test suites need paths to a game install or a mod corpus, read from a gitignored dev-paths.json (copy dev-paths.example.json). Without it they skip, loudly, and that is fine. If you touched packages/server/src, also run node scripts/check-game-boundary.mjs.

Sending a PR#

Branch from main (feat/, fix/, docs/, chore/), add one changelog bullet under "Unreleased" in packages/vscode/CHANGELOG.md, and open the PR. CI and an automated review run on every PR; the maintainer squash-merges. The full rules, including the ones that will get a PR bounced (hand-written game knowledge, vscode imports in the server, per-game if checks), are in CONTRIBUTING.md.

Website and documentation#

Maintain shared guides, corrections and documentation screenshots in this wiki. Publish here first. The product website lives in website/ in the main repository and imports these same pages. Wiki edits trigger its Toolkit website GitHub Actions workflow through gollum; a passing build updates the site independently of extension releases.

The canonical Embedding and Protocol Reference documents remain docs/EMBEDDING.md and docs/PROTOCOL.md in the code repository. Update those with the implementation, then publish the wiki mirrors from the intended release or explicitly requested revision. Keep preview behavior labelled. The website consumes the published mirrors.

Homepage copy, visual identity, navigation, release presentation, website-only credits and recordings use normal repository PRs. Do not maintain another editable copy of the handbook in the website.

After publishing documentation, check the workflow and the changed website page. If a bulk Git update does not produce a gollum run, dispatch the same workflow with gh workflow run website.yml --ref main. Failed imports, broken links or browser checks stop deployment and leave the last successful site in place. See the website README and agent publication rules for the local checks and full procedure.