Introduction

pkl4mc brings the PKL configuration language to Minecraft 1.20.1 (Forge). You write datapacks, recipes, worldgen, and mod configs in a typed language with autocomplete, comments, variables, and reuse. pkl4mc evaluates them to the JSON Minecraft already understands.

PKL (“Pickle”) is a typed, composable configuration language by Apple. Typos and type errors surface in your editor and in the errors command, not as silent in-game failures.

Why not just JSON?

JSON has no variables, no comments, no types, and no reuse. A typo in a field name fails silently. You find out when your loot table drops nothing or your ore doesn’t generate.

A smelting recipe in JSON:

{
  "type": "minecraft:smelting",
  "category": "misc",
  "ingredient": { "item": "minecraft:sea_pickle" },
  "result": "nothingcore:cooked_sea_pickle",
  "experience": 0.7,
  "cookingtime": 200
}

The same recipe in PKL, using the bundled recipe schema:

amends "@pkl4mc/recipes.pkl"

smelting {
  new {
    name = "cooked_sea_pickle"
    category = "misc"
    input { item = "minecraft:sea_pickle" }
    output { item = "nothingcore:cooked_sea_pickle" }
    experience = 0.7
    cookingTime = 200
  }
}

Misspell a field and your editor flags it before the game even starts.

What PKL can do

• Virtual datapacks: .pkl files in config/pkl4mc/data/ are evaluated and injected into the data system on world load. Iterate with the reload command, no restart needed.
• Typed schemas for vanilla formats (recipes, loot tables, tags, worldgen) and 35 mods. Browse the schema catalog.
• Recipe removal and replacement across vanilla and modded recipe types, declaratively. The recipe removals schema covers all operations.
• Editor autocompletion with real ids: the dump command exports every registry id of your running modpack, so item, tag, and fluid fields autocomplete and validate.
• Mod configs in PKL for mod developers, through the config support API.
• Conditional content: files can branch on which mods are loaded, so one pack works across modpack variants.

What PKL can NOT do

• No imperative scripting. PKL is a configuration language, not a scripting engine. There are no event handlers, no callbacks, no KubeJS-style “on block break, do X”. If a feature needs code to run at game time, it needs a mod.
• No registry-frozen content without restart. Some integrations (Totemic instruments and totem carvings) register at mod-load time. Files are read once at startup, and changes need a game restart.
• No Totemic ceremonies. Ceremonies need imperative callbacks and stay unsupported by design.
• No retroactive worldgen. Biome, feature, and dimension changes apply to newly generated chunks only. Existing chunks keep their generation.
• No client-side gameplay scripting. Client support is limited to serving resources, such as the EMI customization schema.

Who is this for?

Modpack and datapack developers who want types, reuse, and autocomplete instead of raw JSON. Mod developers get PKL configs and schema shipping through the library API.

Continue with installation and IDE setup.