https://github.com/ayfri/kore
A Kotlin library to generate Datapacks for Minecraft Java.
https://github.com/ayfri/kore
datapack functions kore kotlin-dsl kotlinserverside minecraft minecraft-datapack minecraft-kotlin modding modding-tools
Last synced: 3 months ago
JSON representation
A Kotlin library to generate Datapacks for Minecraft Java.
- Host: GitHub
- URL: https://github.com/ayfri/kore
- Owner: Ayfri
- License: gpl-3.0
- Created: 2022-11-13T14:36:08.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2026-02-10T20:47:06.000Z (4 months ago)
- Last Synced: 2026-02-10T23:48:09.846Z (4 months ago)
- Topics: datapack, functions, kore, kotlin-dsl, kotlinserverside, minecraft, minecraft-datapack, minecraft-kotlin, modding, modding-tools
- Language: Kotlin
- Homepage: https://kore.ayfri.com
- Size: 12.3 MB
- Stars: 123
- Watchers: 1
- Forks: 5
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Kore
A Kotlin library to write Datapacks for Minecraft.
**Check the [website](https://kore.ayfri.com) for the latest documentation.**
**LLM-friendly documentation**: [llms.txt](https://kore.ayfri.com/llms.txt) | [llms-full.txt](https://kore.ayfri.com/llms-full.txt)
This library is compatible and made for Minecraft Java 1.20 and later versions, I don't think I will support older versions nor Bedrock Edition.
You can still create your own fork and make it compatible with older versions.
I will accept pull requests for older versions on a separate branch.
## Getting Started
New on Kore ? Read the [Getting Started](https://kore.ayfri.com/docs/getting-started) guide to learn how to create your first datapack.
You can use the [Kore Template](https://github.com/Kore-Minecraft/Kore-Template) to start a new project with Kore.
Or install one or more Kore modules by hand with Gradle. If you're starting a new datapack project, begin with the core
`kore` module.
With Kotlin DSL:
```kotlin
implementation("io.github.ayfri.kore:kore:VERSION")
```
With Groovy DSL:
```groovy
implementation 'io.github.ayfri.kore:kore:VERSION'
```
For builds published automatically from every commit on `master`, add the Sonatype snapshots repository and use the same
version with the `-SNAPSHOT` suffix:
```kotlin
repositories {
mavenCentral()
maven("https://central.sonatype.com/repository/maven-snapshots/")
}
dependencies {
implementation("io.github.ayfri.kore:kore:VERSION-SNAPSHOT")
}
```
Then activate the `-Xcontext-parameters` compiler option:
```kotlin
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xcontext-parameters")
}
}
```
You should also use Java 21 or higher:
```kotlin
kotlin {
jvmToolchain(21)
}
```
Then create a `Main.kt` file and start writing your datapacks. See the [documentation](https://kore.ayfri.com/docs/home) for more information, including the [Commands guide](https://kore.ayfri.com/docs/commands/commands) for all available commands.
## Installable Modules
Kore is split into installable modules. Start with `kore`, then add the others only when you need their extra
abstractions or tooling.
### Core DSL - `kore`
- Docs: [Getting Started](https://kore.ayfri.com/docs/getting-started)
- Use it to create Minecraft datapacks with the main Kore DSL.
- Coordinates: `io.github.ayfri.kore:kore:VERSION`
### Gameplay abstractions - `oop`
- Docs: [OOP Utilities](https://kore.ayfri.com/docs/oop/utilities)
- Adds object-oriented wrappers for entities, teams, scoreboards, timers, boss bars, spawners, and related gameplay
systems.
- Especially useful when several gameplay features need to exchange state, for example wiring teams into boss bars,
scoreboards, timers, or entity handles.
- Coordinates: `io.github.ayfri.kore:oop:VERSION`
### Helper utilities - `helpers`
- Docs: [Helpers Utilities](https://kore.ayfri.com/docs/helpers/utilities)
- Adds utility-focused features such as renderers, raycasts, scheduler utilities, scoreboard math, state delegates, and
VFX helpers.
- Great for filling gaps around the core DSL, like rich text rendering, reusable state access, particle shapes, or
math-heavy scoreboard workflows.
- Coordinates: `io.github.ayfri.kore:helpers:VERSION`
### Datapack importer - `bindings` (experimental)
- Docs: [Bindings](https://kore.ayfri.com/docs/advanced/bindings)
- Imports existing datapacks and generates type-safe Kotlin bindings for their resources.
- Coordinates: `io.github.ayfri.kore:bindings:VERSION`
## Example
```kotlin
fun main() {
val datapack = dataPack("test") {
function("display_text") {
tellraw(allPlayers(), textComponent("Hello World!"))
}
recipes {
craftingShaped("enchanted_golden_apple") {
pattern(
"GGG",
"GAG",
"GGG"
)
key("G", Items.GOLD_BLOCK)
key("A", Items.APPLE)
result(Items.ENCHANTED_GOLDEN_APPLE)
}
}
function("tp_random_entity_to_entity") {
val entityName = "test"
val entity = allEntities(limitToOne = true) {
name = entityName
}
summon(Entities.CREEPER, vec3(), nbt {
this["CustomName"] = textComponent("Hello World!")
})
execute {
asTarget(allEntities {
limit = 3
sort = Sort.RANDOM
})
ifCondition {
score(self(), "test") lessThan 10
}
run {
teleport(entity)
}
}
}
pack {
description = textComponent("Datapack test for ", Color.GOLD) + text("Kore", Color.AQUA) { bold = true }
}
}
datapack.generateZip()
}
```
## Community Creations
- [SimplEnergyKore](https://github.com/e-psi-lon/SimplEnergyKore)
- [Kore-Bindings](https://github.com/e-psi-lon/Kore-Bindings)
- [OreCrops](https://github.com/e-psi-lon/OreCrops)
- [realms-map](https://github.com/Aeltumn/realms-maps)
_How to add your project to the list ?_
- Create an issue or contact me on [Discord](https://discord.gg/BySjRNQ9Je).
## Features
- Datapack generation as files or zips or jar files for mod-loaders.
- Function generation.
- All commands with all subcommands and multiple syntaxes.
- Generation of all data-driven features of Minecraft (Advancements, Loot Tables, Recipes, ...).
- Selectors.
- NBT tags.
- Chat components.
- World generation.
- Lists for all registries (Blocks, Items, Entities, Advancements, ...).
- Colors/Vector/Rotation/... classes with common maths/conversion operations.
- Macros support.
- Inventory/Scheduler managers.
- Helper modules for raycasts, text renderers, scoreboard math, delegates, and VFX pipelines.
- OOP gameplay helpers for boss bars, cooldowns, entities, scoreboards, spawners, teams, and timers.
- Scoreboard display manager (like on servers).
- Merging datapacks, even with existing zips.
- Generation of datapacks as mods usable with mod-loaders (Fabric, NeoForge, ...).
- Debugging system inside commands or functions.
- Common NBT tags generation (blocks, items, entities, ...).
- OOP module (experimental).
> Note: All APIs for commands, selectors, NBT tags, ... are public, so you can use them to create your own features.
## Website
### How the website works
- **Location**: The website is a Kotlin Multiplatform subproject under `website/`.
- **Frameworks & tools**: It uses [**Kobweb**](https://kobweb.varabyte.com/) (Kotlin/Compose for Web) with a Kotlin/JS target, Markdown processing, and small JS/npm deps exposed via the Gradle plugin. Generated Kotlin files are written to `build/generated/kore/src/jsMain/kotlin` during the build.
- **Runtime**: [`AppEntry.kt`](./website/src/jsMain/kotlin/io/github/ayfri/kore/website/AppEntry.kt) initializes the Kobweb app, configures a custom Markdown renderer, and sets the site-wide error page via `InitKobweb`.
- **Build output**: The static site export is produced by the `kobwebExport` Gradle task and placed under `website/.kobweb/site/` for deployment.
### How to run the website
- **Prerequisites**:
- Java 21 (JDK 21) installed and `JAVA_HOME` set.
- The project uses the Gradle wrapper (`gradlew`). Ensure it is executable on your platform.
- Node tooling for the Kotlin/JS parts (npm/yarn).
- **Kobweb CLI (recommended for local dev)**:
- The Kobweb CLI provides a convenient development workflow for Kotlin/Kobweb projects. It runs a dev server with live reload and can export a static build.
- **Install the Kobweb CLI**: See the official instructions on the Kobweb website: [Kobweb CLI - Installation](https://kobweb.varabyte.com/docs/getting-started/getting-kobweb).
- **Run the dev server (live reload)**:
```bash
kobweb run
```
- By default the dev server runs on `http://localhost:8080` and watches Kotlin sources, Markdown content under `website/src/jsMain/resources/markdown/`, and static resources. Changes trigger rebuilds and browser reloads.
- Configure server settings (port, logging, etc.) in `website/.kobweb/conf.yaml`.
- **Export a static site**:
```bash
kobweb export
```
- The static output is written to `website/.kobweb/site/` and is suitable for deployment to static hosts.
- **Gradle tasks (alternative)**:
- If you prefer not to install the CLI, the Gradle tasks are still available:
```bash
./gradlew :website:kobwebStart -t # Run with live reload
./gradlew :website:kobwebStop # Stop the server
./gradlew :website:kobwebExport -PkobwebExportLayout=STATIC -PkobwebBuildTarget=RELEASE -PkobwebReuseServer=false
```
- **Troubleshooting**:
- If the dev server doesn't pick up generated Kotlin or Gradle config changes, restart the server.
- To change the dev server port, edit `website/.kobweb/conf.yaml` or use the CLI configuration options.
- If you see stale files, run `./gradlew :website:clean :website:build` before restarting the dev server.
### Notes for contributors
- Generated Kotlin for docs and GitHub releases is written to `build/generated/kore/src/jsMain/kotlin` and is created by Gradle tasks during the build; you generally do not need to commit those generated files.
- If you modify Markdown front-matter or layout logic, re-run the build/export tasks to regenerate the site artifacts.
## Known issues
Check out the [Known Issues](https://kore.ayfri.com/docs/advanced/known-issues) page for a list of known issues and workarounds.
## Star History
## Contributing
If you want to contribute to this project, you can follow these steps:
1. Fork the repository.
2. Run gradle `kore:run` to run the tests.
3. Make your changes.
4. Create a pull request and wait for it to be reviewed and merged.
You can also create an issue if you find a bug or if you want to suggest a new feature.
## Support
If you want to support the project, please consider donating !
## License
This project is licensed under the GNU 3.0 License – see the [LICENSE](LICENSE) file for details.