Getting Started
This guide takes you from zero to a real development workflow with Kore. Instead of stopping at a minimal "hello world," you will build a small but structured datapack, run it in-game, iterate quickly, and learn how to scale your project.
New to Kotlin? The Kotlin basics for Kore section at the end of this page covers the small subset you need.
This guide targets the JVM, the primary way to build and export a datapack (generate() / generateZip()). The same calls also work on Node.js; see Multiplatform Support for that and for the browser-only exportAsStrings() / generateZipBytes() alternatives.
If you already have solid datapack experience and want an architecture-first migration guide, jump to Coming from Datapacks. To try Kore before setting anything up, the playground runs it in your browser and shows the generated pack.
What you will build
By the end of this page, you will have:
- A Kotlin project configured for Kore.
- A datapack with metadata and multiple functions.
- A simple game loop entry point (
load+ user-triggered functions). - A practical local development cycle to edit, regenerate, and test quickly.
- A clean starting structure you can keep expanding.
Prerequisites
- Java 25 (JDK 25) or higher, required by both Kore and Minecraft 26.3.
- Gradle (wrapper recommended:
./gradlew). - IntelliJ IDEA (recommended) or another IDE with Kotlin support.
- Minecraft Java Edition 26.3 installed, with a world to test in.
- Basic understanding of Minecraft datapacks (helpful but not required).
Step 1: Create your project
You have two ways to start.
Option A: Use the Kore Template (recommended)
The fastest option is the template repository, which is already configured for Kotlin + Gradle + Kore, including the Gradle plugin that copies the generated datapack into your world.
- Open Kore Template and click "Use this template" (or clone it).
- Open it in IntelliJ IDEA and let Gradle sync.
- In
build.gradle.kts, setpackNameandworldsto your datapack name and your world. Run./gradlew koreWorldsto list the world names Minecraft knows about. - In
src/main/kotlin/Main.kt, set the same name in thedataPack("...")call. - Run
./gradlew koreRun. - Type
/reloadin game.
Option B: Add Kore to an existing Kotlin project
If you already have a Kotlin project, add Kore and the Gradle plugin manually.
Core modules
kore- core DSL to generate datapacks.oop- object-oriented gameplay abstractions.helpers- helper utilities built on top of Kore.bindings- experimental importer for existing datapacks.
For your first datapack, use only kore.
Gradle Kotlin DSL
Applying the plugin does not add the Kore dependency, so declare it yourself. See the Gradle Plugin page for every option of the kore { } block.
Gradle Groovy DSL
2.28.0-26.3 is the latest stable release, for Minecraft 26.3. Kore also publishes builds for Minecraft snapshots, the newest release including them is 2.28.0-26.3: snapshot features can still change from one snapshot to the next, see Version Support.
Snapshot builds (latest unreleased changes)
If you want bleeding-edge features:
Kotlin compiler and JVM settings
Kore relies on context parameters, which are stable since Kotlin 2.4. Make sure your build.gradle.kts contains:
Step 2: Write a first useful datapack
Instead of a single command, create a tiny but realistic pack with:
- metadata (
pack), - one function for player feedback,
- one function for setup behavior.
If you are new to Kotlin syntax, read the code like this:
dataPack("starter_kore") { ... }creates a builder context.path(...)sets the folder Kore writes the pack into. The Gradle plugin passes its output directory in thekore.outputsystem property, andoutis the fallback when you runmainfrom the IDE.- each
function("...") { ... }block writes one generated.mcfunctionfile. .generate()writes the pack as a folder, which is what the plugin copies into your worlds.
Create Main.kt:
Set packName = "starter_kore" in the kore { } block so it matches the dataPack("starter_kore") name, then run ./gradlew koreRun, which runs main, generates the pack and copies it into the worlds listed in kore { worlds }.
Step 3: Load and test in Minecraft
- Open your world.
- Run
/reload. - Trigger the function:
If everything is correct, chat displays your message.
The same idea runs in your browser with the hello world example of the playground, a load function saying hello, with the commands Kore generates for it:
Step 4: Use load {} as your real entry point
In Kore, using load {} is usually better than manually naming a startup function and wiring tags yourself. It directly creates and registers a function in minecraft:load, which makes your startup flow explicit and less error-prone.
Most datapacks become easier to maintain when you separate:
- initialization (
load), - recurring logic (
tickwhen needed), - feature functions (your own namespaced functions).
Add this structure in Kore by defining dedicated functions and using consistent names:
With this approach:
load("bootstrap")runs once after/reload.tick("runtime/checks")runs every game tick.function("feature/...")stays your reusable API surface.- folder-like names keep generated files organized as the project grows.
Step 5: Organize code before it gets messy
A common beginner mistake is placing everything in one main function. Prefer small helpers and focused files early.
Example using extensions:
This pattern scales much better than one giant builder block.
Step 6: Use a fast development loop
During development, run this once and leave it running:
The loop is then:
- Edit Kotlin code and save: Gradle regenerates the pack and copies it into your worlds.
- In-game:
/reload(sent for you over RCON on a dedicated server). - Run the function you are testing.
See The development loop for the RCON setup.
Tips:
- Use
.generate()when you want to inspect generated files locally. - Use
.generateZip()when you want easy distribution, see Generating output. - Enable pretty JSON in Configuration when debugging generated resources.
Step 7: Build an advanced mini-pack with a custom enchantment
At this point, create a pack that is closer to production structure:
- startup flow with
load, - runtime flow with regular functions,
- one custom data-driven feature (a custom enchantment).
Example:
What this gives you:
- a generated
data/starter_kore/enchantment/vampiric.json, - startup player feedback via
minecraft:load, - a clear split between command functions and data-driven definitions.
To validate in-game:
- Run
./gradlew koreRunto regenerate the pack and copy it into your world. - Run
/reload. - Check logs/chat for load output.
- Test enchantment behavior with commands or controlled test scenarios.
Going beyond a minimal datapack
Once your first commands work, move to data-driven features:
- Add recipes, loot tables, predicates, and tags.
- Create multiple function entry points per feature.
- Separate "bootstrap" code from "gameplay" code.
- Reuse helper functions to avoid duplicated command blocks.
Good expansion ideas after the custom enchantment:
- A welcome system with per-player conditions.
- A starter kit function with basic inventory setup.
- A scoreboard-based progression mechanic.
- A custom recipe that complements your enchantment.
- A balancing pass for enchantment costs, rarity, and max level.
Kotlin basics for Kore
If you are new to Kotlin, do not worry. You only need a small subset to be productive with Kore.
val and var
valmeans read-only reference (preferred by default).varmeans mutable reference (use only when reassignment is needed).
Functions
You declare functions with fun. Kore code is mostly function calls inside builders.
Null safety
Kotlin distinguishes nullable (String?) and non-null (String) types.
Use:
?.for safe calls,?:for fallback values (Elvis operator).
Lambdas and builder blocks
Kore uses Kotlin lambdas heavily:
The { ... } block is a lambda, and inside it Kore exposes a DSL context with helper functions.
Extension functions (very important in Kore projects)
Kotlin lets you add functions to existing types without inheritance. This is ideal for structuring large datapacks.
You can then call registerWelcome() inside your dataPack {} builder.
Kotlin tips that matter specifically in Kore projects
- Prefer
valby default; immutable declarations reduce accidental state issues. - Use extension functions on
DataPackto keep your DSL composable. - If your IDE imports the wrong DSL symbol, qualify temporarily with
this.in the builder scope, then fix the import. - Keep function names and file-like paths consistent (
feature/x,system/y) to keep generated output predictable. - Declare each function path once: two functions sharing a path with different bodies make generation throw.
- Prefer
load {}andtick {}builders over manual tag wiring for standard lifecycle hooks.
Quick Kotlin learning resources
- Kotlin documentation
- Kotlin null safety
- Kotlin extensions
- Learn X in Y Minutes - Kotlin
- Kotlin Playground
Troubleshooting
Unresolved Kore DSL symbols
- Check that the dependency exists in the correct module.
- Confirm you're on Kotlin 2.4 or higher (context parameters are stable there).
- Refresh/sync Gradle in your IDE.
Java/Kotlin toolchain errors
- Confirm JDK 25 is installed and selected by Gradle.
- Confirm
jvmToolchain(25)is configured.
Datapack generates but does not work in-game
- Confirm the namespace/function path in
/function. - Run
/reloadafter every./gradlew koreRun. - Run
./gradlew koreWorldsand check that the world name inkore { worlds }is listed. - Confirm
packNameequals the name indataPack("..."), and thatmainwrites a folder withgenerate(): the plugin copies<output>/<packName>only. - Open logs and verify no JSON or command syntax error is reported.
Recommended learning path after this guide
Start here next:
- Pack Setup & Output
- Runtime Logic - how Kotlin
val/if/formap to in-game scoreboards, storage, andexecute - Functions
- Commands
- Selectors
- Cookbook
- Recipes
- Enchantments
For the full index, see Introduction, and for a tour of everything Kore covers, the Features page.
