linkGetting Started

This guide takes you from zero to a working datapack using Kore and Kotlin. It also highlights a few Kotlin/Kore tips that Java beginners often miss.

linkPrerequisites

• Java 21 (JDK 21) or higher
• Kotlin + Gradle (using the Gradle wrapper is recommended)
• An IDE with Kotlin support (IntelliJ IDEA recommended)
• Basic knowledge of Minecraft datapacks will help you.

linkOption A — Use the Kore Template (recommended)

The fastest way to start is the Kore Template repository. It's preconfigured and ready to run.

• On GitHub: open https://github.com/Ayfri/Kore-Template and click “Use this template” to create your repo, or clone it directly.
• In IntelliJ IDEA:
  1. File > New > Project from Version Control
  2. Enter URL: https://github.com/Ayfri/Kore-Template and choose a directory
  3. Open the project, trust it, let Gradle import/sync
  4. In the src/main/kotlin folder, open Main.kt and run the main function

The template already sets Java 21 and enables the required Kotlin options.

linkOption B — Add Kore to an existing Gradle project

Add the dependency.

Kotlin DSL:

implementation("io.github.ayfri.kore:kore:VERSION")

Groovy DSL:

implementation 'io.github.ayfri.kore:kore:VERSION'

Enable context receivers and set Java toolchain:

kotlin {
	compilerOptions {
		freeCompilerArgs.add("-Xcontext-parameters")
	}

	jvmToolchain(21)
}

linkYour first datapack (Hello, Kore)

Create a Main.kt and paste:

fun main() {
	val datapack = dataPack("hello_kore") {
		function("display_text") {
			tellraw(allPlayers(), textComponent("Hello Kore!"))
		}

		pack {
			description = textComponent("Hello Kore datapack")
		}
	}

	// Generate a zip you can drop in your world's datapacks folder
	datapack.generateZip()
	// Alternatively, generate files in a folder: datapack.generate()
}

• Run main from your IDE.
• A datapack archive is produced; put it into your Minecraft world's datapacks/ folder.
• In-game, run: /function hello_kore:display_text.

linkTips for Kotlin newcomers

• Null safety: Kotlin's type system distinguishes nullable and non-nullable types. Use ? for nullable types and prefer safe calls ( ?.) and the Elvis operator (?:). See Null Safety.

val name: String? = System.getenv("USER")
val length: Int = name?.length ?: 0 // safe call + default when null

• Type inference: You rarely need to specify types explicitly—Kotlin infers them for you. Use val for read-only variables and var for mutable ones. Prefer val for immutability.

val count = 0 // Int inferred
var title = "Hello" // String inferred
// Prefer val; use var only when you need to reassign

• Smart casts: The compiler automatically casts types after checks (e.g., if (x is String) { x.length }).

fun lengthIfString(x: Any): Int = if (x is String) x.length else 0

• Extension functions: Add new functions to existing types without inheritance. Kore uses this for DSLs. See Extensions.

fun String.titleCase(): String = replaceFirstChar { it.titlecase() }
// Usage: "kore".titleCase() -> "Kore"

• Standard library: Kotlin's standard library is rich—explore kotlinlang.org/api/latest/jvm/stdlib/.

val names = listOf("Alex", "Steve", "Sam")
val shout = names.map { it.uppercase() }.filter { it.startsWith("S") }

• DSLs + context receivers: Inside dataPack { ... }, many builders are available without qualifiers. The compiler flag -Xcontext-parameters is required.
• Extract helpers with extensions: Attach utilities to DataPack to keep code organized:

fun DataPack.myBasics() = function("setup") {
	// your setup
}

fun main() = dataPack("my_pack") {
	myBasics()
}

• Name collisions in builders: Some builder names exist in multiple contexts (e.g., nbt, predicate). If your IDE auto-imports the wrong symbol, qualify with this. inside the DSL scope to target the correct function, or fix the import. Example:

predicate("my_function") {
	this.nbt("my_nbt") { /* ... */ } // Use this to correctly import nbt()
}

Then just remove this. now that you know the import is correct.

• Idempotency: Declaring the same record twice is safe, Kore only keeps the last one.

• Kotlin Playground: Try out code online at play.kotlinlang.org.

• Official docs: The Kotlin documentation is excellent for learning language features and best practices.

linkProject layout and outputs

• Your code lives under src/main/kotlin (template already set).
• Generated datapacks: .generate() writes a folder; .generateZip() writes a zip; .generateJar() targets mod loaders.
• During development, enable pretty JSON in Configuration to inspect outputs.
• Split your code into multiple files to keep things organized.

linkTroubleshooting

• Unresolved DSL symbols: Ensure the Kore dependency is on the classpath and -Xcontext-parameters is enabled.
• Java version errors: Verify jvmToolchain(21) and that your JDK is 21.
• Dev loop: Re-run your program after edits to regenerate the datapack.

linkWhat to read next (Docs index)

linkCore guides

• Home
• Creating a Datapack
• Configuration

linkFeatures

• Functions
• Predicates
• Components
• Chat Components
• Colors
• Enchantments
• Recipes
• Loot Tables
• Item Modifiers
• Advancements
• Scoreboards
• Worldgen
• Test Features (GameTest)

linkHelpers

• Display Entities
• Inventory Manager
• Scheduler

linkSee also

• “Hello World” walkthrough: Kore Hello World
• Minecraft wiki: Datapack
• Kore on GitHub
• Kore on Maven Central
• Kore on Discord