Installation & IDE Setup

Download the mod

Download pkl4mc from CurseForge and drop it into mods/.

Start the game once

pkl4mc creates its working directory:

data/ holds loose .pkl files, with data/example/ seeded with two example files to start from. datapacks/ holds full .pkl datapacks (folders or zips). schemas/ holds bundled schemas, copied out for your editor. registries/ holds registry id modules, filled by /pkl dump. PklProject is the auto-generated editor project config.

Your files live in data/, datapacks/, and assets/. Everything under schemas/, registries/, PklProject, and .pkl-lsp/ is auto-generated scaffolding for editor support. Don’t edit it, pkl4mc rewrites it on boot.

Install the PKL extension

Install the PKL extension for your editor: pkl-vscode for VS Code, or the PKL plugins for Zed, Neovim, and IntelliJ. The extension provides syntax highlighting, diagnostics, and completion.

Set up the PKL language server

The extension bundles pkl-lsp, the language server that powers autocomplete and hover docs. pkl4mc pre-writes the language server’s project state on every boot, so @pkl4mc/ and @reg/ imports resolve without a “Sync Projects” click.

Setup:

1. Run /pkl dump in-game once. The command exports every registry id of your running modpack to config/pkl4mc/registries/, which makes item, tag, and fluid ids autocomplete. Details on the dump command page.
2. Open config/pkl4mc/ as your editor workspace root.

Re-run /pkl dump after adding or removing mods. A stale dump only affects editor completion. The runtime never validates against it, so it cannot break world loads.

Patched pkl-lsp (optional)

1. Download pkl-lsp-0.8.0-pkl4mc.jar from the release.
2. JDK 23+ required.
3. In your editor’s settings.json:

   "pkl.lsp.path": "/path/to/pkl-lsp-0.8.0-pkl4mc.jar",
   "pkl.lsp.java.path": "/path/to/jdk-23-or-newer/bin/java"
4. Reload the editor window.

Install the PKL CLI (optional)

The game never needs the pkl CLI. Install it if you want to evaluate files outside Minecraft, for example in CI or scripts. The published pkl4mc schema package makes the schemas consumable from plain PKL projects.