# Known issues and compatibility

> Kore-focused limitations, documented DSL constraints, and generation rough edges with links to docs and source.

Updated 2026-10-23. Canonical: https://kore.ayfri.com/docs/advanced/known-issues

This page lists **limitations and rough edges that touch Kore directly**: the `kore` module, **`bindings`**, and *
*`helpers`** where Kore documents behavior. It is not a general Minecraft gameplay reference.

Each item is tagged:

| Category                        | Meaning                                                                                                                                  |
|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| **Kore limitation**             | Kore or a dependency Kore wires in (for example [knbt](https://github.com/BenWoodworth/knbt)) cannot express or round-trip the case yet. |
| **Documented DSL / helper cap** | Behavior is spelled out in Kore’s own command or helper docs (often because the vanilla command format or text API is narrow).           |
| **Generation rough edge**       | `generate()` / `generateZip()` / merge paths behave as implemented; surprising until you read the generation docs.                       |

For the high-level "what Kore does not include,"
see [From Datapacks to Kore](https://kore.ayfri.com/docs/guides/from-datapacks-to-kore.md#what-kore-will-not-do-for-you).

---

## Kore limitations

### NBT and SNBT (via knbt)

**Category:** Kore limitation

Kore builds NBT and SNBT through **[knbt](https://github.com/BenWoodworth/knbt)** (`StringifiedNbt` and builders). Entry
points include [
`NbtTagUtils.kt`](https://github.com/Ayfri/Kore/blob/master/kore/src/commonMain/kotlin/io/github/ayfri/kore/utils/NbtTagUtils.kt)
and the `nbt { }` / `toSnbt()` helpers used across commands and components.

For normal day-to-day usage and examples, start with [NBTs](https://kore.ayfri.com/docs/concepts/nbts.md); this section focuses on limitations
and
workarounds.

Implications:

- **Typed NBT lists:** In knbt, `NbtList` is **homogeneous** (one element type per list). That matches Java edition NBT,
  but it means you cannot build a single list that mixes unrelated tag kinds through the normal DSL. See
  the [knbt README](https://github.com/BenWoodworth/knbt/blob/main/README.md) (`NbtList` description).
- **Exotic SNBT text:** Some SNBT spellings or parser extensions you might see in external tools are **not** necessarily
  available through Kore’s knbt-backed path. Prefer compounds, homogeneous lists, and literals Kore’s builders support.

**Workaround:** Emit a **`literal("...")`** only when you must hand-craft a fragment, or post-process generated files.
Upgrading or patching **[knbt](https://github.com/BenWoodworth/knbt)** (Kore pins a version in [
`gradle/libs.versions.toml`](https://github.com/Ayfri/Kore/blob/master/gradle/libs.versions.toml)) is the right place
for format-level fixes.

### Resource packs

**Category:** Kore limitation

Kore generates **datapacks** only (`data/`, functions, JSON registries, `pack.mcmeta`). It does **not** emit **resource
packs** (`assets/`). That scope is stated on the site (for example [Home](https://kore.ayfri.com/docs/home.md)) and
in [From Datapacks to Kore](https://kore.ayfri.com/docs/guides/from-datapacks-to-kore.md#what-kore-will-not-do-for-you).

**Workaround:** Maintain a separate resource-pack project or tooling; you can still keep both in one Gradle repo.

### Bindings importer

**Category:** Kore limitation

The **`bindings`** module is **experimental**. Official docs: [Bindings](https://kore.ayfri.com/docs/advanced/bindings.md). Roadmap and design
discussion: [GitHub #176](https://github.com/Ayfri/Kore/issues/176).

Notable constraints from Kore’s own docs and README:

- Generated APIs may **change** between Kore versions; pin versions and review diffs.
- **Unknown resource types** are **skipped** so codegen stays
  valid ([Bindings troubleshooting](https://kore.ayfri.com/docs/advanced/bindings.md#troubleshooting)).
- **Macros** in imported `.mcfunction` files are detected via **`$()`-style patterns**, not a full Minecraft
  parser ([Bindings](https://kore.ayfri.com/docs/advanced/bindings.md)).
- **CurseForge** downloads need a **CurseForge API key**; **GitHub** may need a token for rate
  limits ([Download sources](https://kore.ayfri.com/docs/advanced/bindings.md#download-sources)).

**Workaround:** Treat imports as a typed starting point; simplify or remap packs that confuse the importer (
`remappings { }`, `includes` / `excludes` in [Configuration](https://kore.ayfri.com/docs/advanced/bindings.md#configuration)).

### JSON / NBT serialization (generate vs decode)

**Category:** Kore limitation

Decoding support varies by serializer:

- **Chat components** decode fully into their typed forms via `ChatComponents.serializer()` (text, translatable, score,
  selector, keybind, nbt, object), including nested `extra`, styling, and hover/click events. **`NbtAsJsonSerializer`**
  decodes JSON/NBT into an `NbtTag`.
- **Item components** (`ComponentsSerializer`) decode **generically**: each entry becomes a raw `CustomComponent` keyed
  by its component name. This round-trips, but the values stay opaque instead of becoming their typed counterparts (such
  as `DamageComponent`), because `Component` is not a sealed hierarchy and has no name to serializer registry to
  dispatch
  on. Typed item-component decoding would require that registry (ideally generated).
- Book **page** serializers stay **write-only**: they encode what you build in Kotlin but do not decode vanilla
  JSON/SNBT.

**Workaround:** For the write-only and generic cases, treat your Kotlin project as the **source of truth** and inspect
**generated files** under `path` / zip. For contributors extending serializers, see
[Arguments](https://kore.ayfri.com/docs/contributing/arguments.md) and the relevant feature docs.

### Custom components and `@SerialName`

**Category:** Kore limitation

When you define **[custom components](https://kore.ayfri.com/docs/concepts/components.md)** backed by NBT, property names sometimes need an
explicit **`@SerialName("vanilla_json_key")`** because the **KNBT** stack does not always follow the same naming path as
Kore’s JSON `namingStrategy` for that shape. The guide shows this in context (for example the `UseComponent` example
with `durability_damages`).

**Workaround:** Copy patterns from [Components](https://kore.ayfri.com/docs/concepts/components.md) and match the keys your target **pack format** expects (use Minecraft’s registry JSON or Kore’s generators as reference, not guesswork).

---

## Documented DSL / helper caps

These are **not Kore bugs**; Kore documents them so authors know what the DSL will and will not do.

### Command macros

**Category:** Documented DSL / helper cap

[Macros](https://kore.ayfri.com/docs/commands/macros.md) require **Minecraft 1.20.2+** for the feature itself. Kore’s doc lists DSL limits:
macros only in **functions**, **no type checking**, and macros are **not** threaded through every possible command
argument slot.

**Workaround:** Prefer normal Kotlin command builders where types matter; keep macro surfaces small and **test in-game**.

### Markdown renderer (`helpers`)

**Category:** Documented DSL / helper cap

The [Markdown renderer](https://kore.ayfri.com/docs/helpers/markdown-renderer.md) turns Markdown into **text components**. The helper lists
features Minecraft **cannot** represent (images, tables, fenced code blocks, etc.)
in [Not supported (Minecraft limitations)](https://kore.ayfri.com/docs/helpers/markdown-renderer.md#not-supported-minecraft-limitations).

**Workaround:** Stay in the **supported** subset documented on that page, or build **`textComponent`** trees by hand.

## Quick reference

| Need                  | Where to look                                                                            |
|-----------------------|------------------------------------------------------------------------------------------|
| Tune JSON output      | [Configuration](https://kore.ayfri.com/docs/guides/configuration.md) (`prettyPrint`, comments, paths)             |
| Folder vs zip vs jar  | [Creating A Datapack - Generation](https://kore.ayfri.com/docs/guides/creating-a-datapack.md#generating-output)          |
| Import external packs | [Bindings](https://kore.ayfri.com/docs/advanced/bindings.md)                                                      |
| Module layout         | [From Datapacks to Kore](https://kore.ayfri.com/docs/guides/from-datapacks-to-kore.md)                            |
| Report a bug or gap   | [Kore on GitHub](https://github.com/Ayfri/Kore/issues) with pack format and Kore version |