Kore User Guide

Kore user guide (for assistive teaching)

Kore is a Kotlin library for Minecraft Java Edition 1.20+ datapacks: type-safe builders for functions, JSON data, commands, selectors, and worldgen. Bedrock and older MC versions are out of scope unless the user explicitly targets a fork.

The agent should not assume the user has the Kore monorepo checked out. Prefer official docs and Maven artifacts. Use the documentation index for page-by-page lookup.

Activation boundaries

Use this skill when the user asks about:

• Kore project setup or dependency configuration.
• Building datapacks in Kotlin with Kore DSL.
• Choosing between kore, oop, helpers, and bindings.
• Finding official Kore docs for a concrete feature.

Do not use this skill as the primary guidance for:

• Bedrock edition tooling.
• Vanilla datapack-only workflows with no Kotlin/Kore intent.
• General Kotlin language teaching unrelated to Kore.

Default response procedure

Follow this order unless the user already provided a narrower request:

1. Confirm target: user wants Kore for Java datapacks.
2. Provide minimal setup (dependency + compiler flag + JDK/Gradle baseline).
3. Give a small, runnable DSL skeleton (dataPack, function, generate*).
4. Route to exactly one or two official docs pages for next depth.
5. Add optional module guidance (oop/helpers) only if needed.

Prerequisites checklist

1. JDK 21+ and Gradle (Kore template uses the wrapper).
2. Dependency: implementation("io.github.ayfri.kore:kore:<VERSION>") (start with the kore module only).
3. Kotlin compiler option: add -Xcontext-parameters (required by Kore).
4. Optional: Kore Template for a ready project.

Snapshots: Sonatype snapshot repo plus VERSION-SNAPSHOT when the user needs unreleased features (see Getting Started).

Gotchas

• -Xcontext-parameters is required. Missing it often produces confusing compile errors.
• function("...") path is logical datapack path, not a filesystem path with .mcfunction extension.
• Start with kore only. Adding oop and helpers too early increases API noise and weakens guidance quality.
• If behavior seems undocumented, check Known Issues before proposing workarounds.
• Prefer stable docs and artifacts by default; use snapshots only when the user explicitly needs unreleased features.

Installable modules (pick by need)

Add oop / helpers only when the user’s feature set justifies the extra API surface.

Mental model (minimum viable understanding)

• Entry: dataPack("namespace_id") { ... } builds a DataPack.
• Functions: function("path/without_mcf_extension") { ... } emit .mcfunction files; commands and helpers live in these blocks.
• Output: DataPack exposes generate(), generateZip(), generateJar() (see Creating a Datapack for paths and options).
• Style: heavy use of lambdas and extension functions on DataPack to split large packs into register functions (documented in Getting Started).

Suggested order for help or self-study

1. Getting Started (project, first pack, pack {}, load patterns).
2. Creating a Datapack (lifecycle, generate* APIs, structure).
3. Configuration (JSON formatting, dev-friendly output).
4. Commands and Functions (command DSL, function layout, tags).
5. Cookbook (end-to-end recipes).
6. Concepts as needed: Selectors, Chat Components, Scoreboards, Components.
7. Data-driven: Tags, Predicates, Loot Tables, Recipes, Advancements, Worldgen, etc.
8. Macros when reusing command fragments.
9. Optional modules: OOP Utilities, Helpers Utilities, Bindings.
10. Known Issues before debugging odd behavior.

Migration from hand-written datapacks: From Datapacks to Kore.

LLM-friendly and machine-readable docs

• llms.txt (short index)
• llms-full.txt (expanded)

Point users or tools at these when they want crawlable, consolidated reference outside the website navigation.

Progressive disclosure rules

• Read ./references/REFERENCE.md when the user asks for a specific feature area, page path, or topic map.
• Prefer linking only the most relevant docs page first; avoid dumping many links unless explicitly asked.
• Use llms.txt or llms-full.txt only when broad, machine-readable indexing is requested.

Quality loop before final answer

Before finalizing guidance:

1. Verify the answer stays inside Java Edition + Kore scope.
2. Verify setup includes dependency and -Xcontext-parameters when setup is discussed.
3. Verify all links point to official Kore docs or clearly-labeled template/repo resources.
4. Trim generic Kotlin/Minecraft advice that is not Kore-specific.

Working inside the Kore repository (contributors)

If the task is Kore development rather than using Kore: contributor docs live under website/src/jsMain/resources/markdown/doc/ in the repo. The public site mirrors that content at https://kore.ayfri.com/docs/.... For internals (generators, architecture), use Contributing and Architecture and Patterns.

Full documentation map

For a complete topic list with links, read reference.md.