Iris/docs/api/modded.md

# Iris on Fabric, Forge and NeoForge

`art.arcane.iris.modded.api` is the surface a **mod** compiles against. It answers three questions: is this
level generated by Iris, how do I drive Iris from my mod, and how do I get my own blocks, items and mobs
placed by an Iris pack.

It ships in the Fabric, Forge and NeoForge jars only. It is absent from the Bukkit plugin jar, shares no types
with `art.arcane.iris.api`, and is not covered by [terrain.md](terrain.md), [world-events.md](world-events.md)
or [tree-feller.md](tree-feller.md) — those describe the Bukkit surface, which does not exist on a mod loader.

Everything here assumes Minecraft 26.2, Java 25, and one of Fabric, Forge or NeoForge. The mod id is
`irisworldgen` on all three.

| What you want | Where |
|---|---|
| Detect Iris, read the engine, start a pregeneration, read/write mantle data | `IrisModdedAPI` |
| Have Iris place *your* blocks, items and mobs | `ModdedDataProvider` |
| Alias one custom key onto a fixed vanilla state, with no provider class | `IrisModdedAPI.registerCustomBlockData` |

---

## Depending on Iris

**There is no published Maven artifact for the mod jars.** No module in this repository applies
`maven-publish`, and the JitPack route documented in [README.md](README.md) resolves the Bukkit sources, not
the modded adapter. Until that changes, building from source is the only path.

The three adapters are standalone Gradle builds — each `adapters/<loader>/settings.gradle` does
`includeBuild('../..')` to substitute `art.arcane:core` and `art.arcane:spi` from the root build, which is what
keeps Loom, ForgeGradle and ModDevGradle off one plugin classpath. The root build drives them through their own
wrappers:

```bash
./gradlew buildFabric     # -> dist/Iris v<version> [Fabric] <mc>+<loader>.jar
./gradlew buildForge      # -> dist/Iris v<version> [Forge] <mc>+<loader>.jar
./gradlew buildNeoforge   # -> dist/Iris v<version> [NeoForge] <mc>+<loader>.jar
```

Then compile against the jar you will actually run:

```gradle
dependencies {
    compileOnly(files('libs/Iris-fabric.jar'))
}
```

The adapters are **not** in the root `settings.gradle` by default. Add `-PincludeModdedAdapters=true` for IDE
import only; it closes a composite build cycle (root -> adapter -> root) and Gradle may reject it.

### Soft dependency

Declare the optional relationship, then do not rely on load order — the ServiceLoader path below works
regardless of it, because Iris does the discovering.

Fabric (`fabric.mod.json`) — `suggests`, not `depends`; a hard `depends` makes Iris mandatory:

```json
{
  "suggests": { "irisworldgen": "*" }
}
```

NeoForge (`META-INF/neoforge.mods.toml`):

```toml
[[dependencies.yourmod]]
modId = "irisworldgen"
type = "optional"
ordering = "AFTER"
side = "BOTH"
```

Forge (`META-INF/mods.toml`) is the same with `mandatory = false` instead of `type`.

### Detecting Iris

Two checks, and they answer different questions.

**Is the mod present?** Ask the loader — `FabricLoader.getInstance().isModLoaded("irisworldgen")`, or
`ModList.get().isLoaded("irisworldgen")` on Forge and NeoForge. Cheap, but tells you nothing about whether
Iris actually generates anything.

**Are Iris classes on the classpath?** If your integration lives in a class that imports
`art.arcane.iris.modded.api.*`, that class must not load unless Iris is present. Keep the imports behind a
presence check and a separate class, or probe reflectively:

```java
private static final boolean IRIS_PRESENT = irisPresent();

private static boolean irisPresent() {
    try {
        Class.forName("art.arcane.iris.modded.api.IrisModdedAPI");
        return true;
    } catch (Throwable absent) {
        return false;
    }
}
```

Do not gate on a version string. Probe for the class or method you need.

**Is *this* level Iris?** `IrisModdedAPI.isIrisLevel(level)`. A server can mix Iris and vanilla dimensions
freely, so presence of the mod is not presence of an Iris world.

---

## `IrisModdedAPI`

All static, all null-tolerant: a null or non-Iris `ServerLevel` yields `false`, `null` or a no-op. You never
have to pre-check.

| Method | What it does |
|---|---|
| `isIrisLevel(ServerLevel)` | Whether the level's chunk generator is `IrisModdedChunkGenerator`. The cheapest check |
| `isStudioLevel(ServerLevel)` | Whether it is a throwaway pack-authoring world. Persist nothing against one |
| `getEngine(ServerLevel)` | The `Engine` behind the level, or null. See the stability warning below |
| `pregenerate(ServerLevel, int radiusBlocks)` | Starts a cached async pregeneration around the origin |
| `pregenerate(ServerLevel, int, int centerX, int centerZ, boolean sync, boolean cached)` | Same, with a centre and write mode |
| `getMantleData(ServerLevel, int x, int y, int z, Class<T>)` | Reads Iris's per-block sidecar storage |
| `setMantleData(ServerLevel, int x, int y, int z, T)` | Writes it |
| `deleteMantleData(ServerLevel, int x, int y, int z, Class<T>)` | Removes a value of that type |
| `retainMantleDataForSlice(Class<?>)` | Declares a mantle type Iris must keep rather than discard |
| `registerProvider(ModdedDataProvider)` | Registers a custom content provider imperatively |
| `registerCustomBlockData(String namespace, String key, String state)` | Aliases one key onto a fixed block state |

### `Engine` is internal

`getEngine` returns `art.arcane.iris.engine.framework.Engine`. That type is **internal to Iris** and changes
without a deprecation cycle — as do `art.arcane.iris.core.*`, `art.arcane.iris.util.*` and
`art.arcane.iris.spi.*`. Treat the returned `Engine` as an opaque token to hand back to Iris. Every method in
the table above that needs one resolves it for you; prefer those.

Never cache an `Engine`. A pack hotload or a level unload replaces it, and the old instance goes inert.
`getEngine` already returns null while the generator is binding and during shutdown.

### Pregeneration

`pregenerate` returns as soon as the job is queued. Progress goes to Iris's own logging and boss bar, not to
your caller. Only one job runs server-wide, so it returns `false` if one is already active — and `false` also
means "not an Iris level", so check `isIrisLevel` first if you need to tell those apart. Call it on the server
thread.

`cached = true` writes an on-disk pregeneration cache so an interrupted run resumes instead of regenerating.
`sync = true` writes chunks synchronously: slower, but it bypasses the async write queue.

### Mantle data

The mantle is Iris's own per-block storage, independent of chunk NBT, and it is how Iris carries data between
generation stages. Three things to know:

1. **Coordinates are world-space.** `y` is translated by the engine's minimum height internally. A `y` outside
   the engine's height range reads as null and writes as a no-op — no exception.
2. **Reads never create storage; writes do.** `getMantleData` returns null when no mantle region exists for
   that column yet. `setMantleData` and `deleteMantleData` create the region, which can touch disk — do not
   call them per block in a tick loop on the server thread.
3. **Declare your types or lose them.** Iris discards mantle slices it does not need once a region's
   generation data has served its purpose. Any type you write and expect to read back later must be declared
   once during mod setup:

```java
IrisModdedAPI.retainMantleDataForSlice(MyMarker.class);
```

Registration is by canonical class name, process-wide across every Iris world, and cannot be undone. All three
mantle methods throw `IllegalStateException` if the engine's mantle has already been closed.

---

## `ModdedDataProvider`

The extension point. Implement it and a pack can name `yourmod:something` in a block palette, a loot table or a
spawn entry, and Iris will ask you to resolve it.

```java
public interface ModdedDataProvider {
    String modId();
    default boolean isReady();                                    // default true
    Collection<Identifier> getTypes(ModdedDataType type);
    boolean isValidProvider(Identifier id, ModdedDataType type);
    default ModdedBlockData getBlockData(Identifier blockId, Map<String, String> state);   // default null
    default void processBlockPlacement(ModdedBlockPlacementContext context);               // default no-op
    default Entity spawnMob(ServerLevel level, double x, double y, double z, Identifier entityId); // default null
    default void init();                                          // default no-op
}
```

`ModdedDataType` is `BLOCK`, `ITEM` or `ENTITY`. Constants may be added — write a `default` arm in any switch
expression over it.

### The contract

`modId()` is your identity, not decoration. It de-duplicates registrations and labels every log line Iris emits
about your provider. It must be non-null and stable; returning null aborts discovery.

`isValidProvider(id, type)` is the gate. Iris calls it before every resolution callback, on generation threads,
for every key it could not resolve itself. Keep it to a namespace comparison or a set lookup.

`isReady()` is how a provider whose registries populate late excuses itself. Iris **skips** a provider that
returns false rather than treating it as absent, so returning false is strictly better than returning wrong
answers.

`getTypes(type)` feeds command suggestion and pack tooling. It is not the resolution path — return an empty
collection rather than null, and do not do work here that `isValidProvider` should do.

`getBlockData(blockId, state)` resolves a claimed block. `state` holds the `[prop=value]` pairs from the pack's
key, already parsed, possibly empty, never null. Return null to decline and Iris tries the next provider, then
falls back to air. Return `ModdedBlockData.direct(blockState)` when the state is final.

`processBlockPlacement(context)` finishes a **deferred** placement. Return
`ModdedBlockData.deferred(placeholder)` from `getBlockData` when the real block needs a loaded level — a block
entity, neighbour state, or mod registries not reachable from a generation thread. Iris writes your placeholder
during generation and calls you back later on the server thread with the chunk loaded. Pick a placeholder with
the same shape and occlusion as the final block so terrain around it generates correctly. Only the *first*
provider claiming the identifier is called for a given position.

`ModdedBlockPlacementContext` is an immutable record: `engine`, `level`, `position`, `blockId`, `state`,
`blockState`. `blockState` is what is currently at `position` — normally your placeholder, though a later
generation stage may have replaced it. `state` is defensively copied and unmodifiable.

`spawnMob(...)` spawns a claimed custom entity on the server thread. Return null to decline.

`init()` runs once, immediately after Iris accepts your provider.

### Threading

| Callback | Thread | Notes |
|---|---|---|
| `isValidProvider`, `getBlockData` | Generation threads, many at once | Must be fast. Must not touch world state |
| `processBlockPlacement` | Server thread, chunk loaded | Safe to write blocks and attach block entities |
| `spawnMob` | Server thread | |
| `init` | Whichever thread registered you | Mod init for ServiceLoader, your caller otherwise |
| `modId`, `isReady`, `getTypes` | Any | |

Implementations must be thread-safe. `getBlockData` in particular is called concurrently for every unresolved
key a pack names, which during a pregeneration is a lot.

### Registration by ServiceLoader

Iris discovers providers with `java.util.ServiceLoader`. Ship a service file naming your implementation's
binary name; the class needs a public no-argument constructor.

`src/main/resources/META-INF/services/art.arcane.iris.modded.api.ModdedDataProvider`:

```
com.example.yourmod.iris.YourIrisProvider
```

One binary name per line. Nested classes use `$`, for example
`com.example.yourmod.YourMod$IrisProvider`.

Iris loads the service with **its own** class loader:
`ServiceLoader.load(ModdedDataProvider.class, ModdedCustomContentRegistry.class.getClassLoader())`. Your service
file therefore has to be visible from Iris's loader, which is the normal case on all three loaders but is the
thing to suspect first if nothing happens. Confirm with the registration log line below; if it never appears,
fall back to `registerProvider`.

### When discovery runs

`ModdedCustomContentRegistry.discover()` runs inside `ModdedEngineBootstrap.bootCommon(...)`, which is the very
first thing each loader's entrypoint calls — `IrisFabricBootstrap.onInitialize`,
`IrisForgeBootstrap`/`IrisNeoForgeBootstrap` construction. That is **before** the Iris chunk generator is
registered and long before any server starts. Consequences:

- A ServiceLoader-declared provider is available before any world could resolve a block. This is the safe path.
- Discovery runs **once per process**. A second `discover()` is a no-op.
- Your `init()` must not assume a server, a level, or a fully populated game registry. Defer that work and gate
  it behind `isReady()`.

### Registration imperatively

`IrisModdedAPI.registerProvider(provider)` works at any time and is the option if you would rather not ship a
service file, or need to build the provider from your own config.

Ordering is the catch: Iris only consults providers registered **before** a pack resolves the block in
question, and blocks already resolved are not revisited. Register during mod setup. Registering after Iris's
own ServiceLoader pass is fine; registering after a world has generated is not.

A second registration under a `modId()` already present is logged and ignored. `init()` runs during the call.

### How discovery and failures are reported

Everything below is logged under the `Iris` logger. One line per accepted provider confirms registration —
this is what to grep for when checking whether your service file was seen:

```
Iris registered custom content provider 'yourmod'
```

A duplicate `modId()` is rejected with `already registered; ignoring duplicate`.

Iris catches throwables from every provider callback, logs them against your `modId()`, and continues with the
remaining providers — one broken provider does not stop world generation:

```
Iris custom content provider 'yourmod' failed resolving block yourmod:thing
Iris custom content provider 'yourmod' failed post-placement for yourmod:thing at BlockPos{...}
Iris custom content provider 'yourmod' failed spawning mob yourmod:critter
Iris custom content provider 'yourmod' failed to initialize      # registerProvider path only
```

`init()` during ServiceLoader discovery is the one exception, and it is all-or-nothing: a throwable there
aborts the pass, restores the registry to its pre-discovery state, and rethrows. The log line names the
provider that failed, by mod id and class name:

```
Iris custom content provider discovery failed at provider 'yourmod' (com.example.yourmod.iris.YourIrisProvider)
```

If your provider's own `modId()` throws while Iris is building that message, the class name alone is logged; if
the failure happened outside any provider, it reads `the provider service loader`. A `null` provider or a null
`modId()` from the ServiceLoader fails the pass with a message naming which.

### Static aliases, no provider class

For the common case of "my key is really this vanilla block", skip the provider:

```java
IrisModdedAPI.registerCustomBlockData("yourmod", "fancy_log", "minecraft:oak_log[axis=y]");
```

The state string uses the same syntax packs use and is parsed **immediately** — a typo is logged at startup and
the registration dropped, rather than surfacing later as missing blocks. Aliases take precedence over provider
lookups for the same key. Null arguments are ignored.

---

## How pack resolution works on modded

Paths are relative to the loader's config directory (`config/` on a normal server install).

| Path | What it is |
|---|---|
| `config/irisworldgen/packs/<pack>/` | Installed packs. A pack is valid when `dimensions/<dimension>.json` exists |
| `config/irisworldgen/generated/datapack/iris/` | The generated forced datapack. Iris owns this — do not edit it |
| `config/irisworldgen/modded.json` | Mod-side config: default pack, auto-download, primary world routing |
| `config/iris/` | Engine data directory: settings and per-world engine state |

Note the split: the engine's data folder is `config/iris`, but every modded pack path — installer, validator,
command suggestions, forced datapack, engine creation — resolves under `config/irisworldgen/packs`. Install
packs there.

At `bootCommon`, Iris kicks off an async default-pack prefetch. If `modded.json` has
`autoDownloadDefaultPack` enabled and the configured `defaultPack` is missing, Iris downloads
`IrisDimensions/<pack>` from the `master` branch into the packs folder. If that fails it logs a pointer to
`/iris download <pack>`. A pack that is already installed is left alone.

When a level asks for its pack, `ModdedWorldEngines.packFolder(pack)` resolves
`config/irisworldgen/packs/<pack>`. A missing pack is a hard failure with the expected absolute path printed —
Iris does not silently generate vanilla terrain in its place.

### The forced datapack

Iris cannot register dimension types and per-pack biomes through a mod registry, because vanilla world creation
reads them from the datapack layer. So Iris **generates a datapack** from the installed packs and injects it as
a built-in, top-priority repository source:

- Fabric: a `PackRepository` mixin, via `FabricForcedDatapackSources`
- Forge and NeoForge: `event.addRepositorySource(ModdedForcedDatapack.repositorySource())`

It contributes world presets, dimension types and biomes under the `irisworldgen` namespace, with ids derived
from the pack and dimension names — `irisworldgen:packs/<pack>/dimensions/<dimension>/preset`,
`.../dimension_type`, `.../biomes/<biome>`. This is why an Iris dimension shows up in the vanilla world
creation screen as `IRIS:<Pack>`.

It is regenerated when the pack changes: a studio hotload calls `ModdedForcedDatapack.regenerate()`. If
regeneration fails and a previously published pack is still readable, Iris keeps the last known-good one and
logs the failure rather than starting with no dimension types.

**The failure you need to recognise.** If injection did not happen for your loader — a mixin that failed to
apply, an event that never fired — Iris logs this once at startup and world creation will fail no matter how
many times you restart:

```
Iris forced datapack 'iris_worldgen' was never loaded by this server.
N installed pack(s) at <path> contributed no dimension types or custom biomes.
Datapack source injection failed for this loader (mixin/event not applied), so world
creation will fail and restarting will not fix it.
```

That is a loader/environment problem, not a pack problem. Nothing an integrating mod does can fix it.

### Commands worth knowing

The modded command tree is `/iris`, aliased `/ir` and `/irs`, gated at gamemaster permission level.

| Command | What it tells you |
|---|---|
| `/iris pack validate [pack]` | Validates every installed pack, or one. Runs on a worker thread, reports per pack, and counts unloadable packs |
| `/iris pack status [pack]` | Replays the **recorded** validation results — blocking errors and warnings per pack. Says so and returns nothing if `validate` has not run this session |
| `/iris pack cleanup <pack> [apply]` | Previews unused pack resources; `apply` deletes them |
| `/iris pack restore <pack> [apply]` | Previews a restore of pack resources; `apply` performs it |
| `/iris datapack status` | Per Iris dimension: active dimension type, its min/max/logical height, what the pack wants, and whether they match |
| `/iris datapack install` | Writes the pack's dimension type into `<world>/datapacks/iris/data/irisworldgen/dimension_type/` as an override |
| `/iris datapack list` | Datapack URLs declared by installed pack dimensions, plus the datapacks actually present in `<world>/datapacks/` |
| `/iris download <pack> [branch] [overwrite]` | Installs a pack from `IrisDimensions/<pack>` into the packs folder. Aliased `dl` |
| `/iris version` | Iris version and loader |

`/iris datapack status` is the first thing to run when an Iris dimension generates at the wrong height. A
mismatch means the level's active dimension type disagrees with the pack, which happens when a world was
created before a pack's height range changed. `install` writes the override; the world still needs a restart.

`/iris datapack ingest`, `pull` and `remove` exist but refuse on modded, with a message explaining why: the
Modrinth ingest workflow is Bukkit tooling. Native vanilla and datapack structure placement **does** work on
modded — install the datapack into `<world>/datapacks/` and restart, and its registered structures generate.

---

## What is not supported

- **No published artifact.** Build from source, as above. There is no Maven coordinate for the modded jars and
  no `maven-publish` in this build.
- **Core types are internal.** `art.arcane.iris.engine.*`, `art.arcane.iris.core.*`,
  `art.arcane.iris.util.*` and `art.arcane.iris.spi.*` change without notice. `Engine`, reachable through
  `getEngine` and `ModdedBlockPlacementContext.engine()`, is the one internal type this surface exposes, and it
  is exposed as a token to hand back rather than an API to call.
- **No event bus.** `IrisPlatform.callEvent` is a no-op on every mod loader adapter. There is no modded
  equivalent of `IrisWorldEngineEvent` or `IrisPregenerationEvent`; poll `isIrisLevel`/`getEngine` instead.
- **No `art.arcane.iris.api`.** The Bukkit terrain, world-event, pregen and tree-feller interfaces are not in
  the mod jars. There is no modded terrain-query surface yet.
- **No PlaceholderAPI.** [placeholders.md](placeholders.md) is Bukkit-only.
- **Datapack ingest is Bukkit-only**, per the command note above.
- **`ModdedCustomContentRegistry`'s resolution methods are Iris internals.** They are public only because the
  adapter's generation code lives in another package. Go through `IrisModdedAPI`.