diff --git a/.gitignore b/.gitignore
index a6992a671..53ce7d898 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,4 @@ collection/
DataPackExamples/
TreeGenStuff/
+dist/
diff --git a/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/CustomBiomeSource.java b/adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/CustomBiomeSource.java
similarity index 100%
rename from nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/CustomBiomeSource.java
rename to adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/CustomBiomeSource.java
diff --git a/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/IrisChunkGenerator.java b/adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/IrisChunkGenerator.java
similarity index 100%
rename from nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/IrisChunkGenerator.java
rename to adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/IrisChunkGenerator.java
diff --git a/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/NMSBinding.java b/adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/NMSBinding.java
similarity index 100%
rename from nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/NMSBinding.java
rename to adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/NMSBinding.java
diff --git a/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/VanillaStructureBiomes.java b/adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/VanillaStructureBiomes.java
similarity index 100%
rename from nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/VanillaStructureBiomes.java
rename to adapters/bukkit/nms/v1_21_R7/src/main/java/art/arcane/iris/core/nms/v1_21_R7/VanillaStructureBiomes.java
diff --git a/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/CustomBiomeSource.java b/adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/CustomBiomeSource.java
similarity index 100%
rename from nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/CustomBiomeSource.java
rename to adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/CustomBiomeSource.java
diff --git a/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/IrisChunkGenerator.java b/adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/IrisChunkGenerator.java
similarity index 100%
rename from nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/IrisChunkGenerator.java
rename to adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/IrisChunkGenerator.java
diff --git a/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/NMSBinding.java b/adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/NMSBinding.java
similarity index 100%
rename from nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/NMSBinding.java
rename to adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/NMSBinding.java
diff --git a/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/VanillaStructureBiomes.java b/adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/VanillaStructureBiomes.java
similarity index 100%
rename from nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/VanillaStructureBiomes.java
rename to adapters/bukkit/nms/v26_1_R1/src/main/java/art/arcane/iris/core/nms/v26_1_R1/VanillaStructureBiomes.java
diff --git a/adapters/fabric/build.gradle b/adapters/fabric/build.gradle
new file mode 100644
index 000000000..ed65288cc
--- /dev/null
+++ b/adapters/fabric/build.gradle
@@ -0,0 +1,27 @@
+plugins {
+ id 'java'
+}
+
+group = 'art.arcane'
+version = rootProject.version
+
+java {
+ toolchain {
+ languageVersion = JavaLanguageVersion.of(25)
+ }
+}
+
+dependencies {
+ implementation(project(':spi'))
+}
+
+processResources {
+ inputs.property('version', project.version)
+ filesMatching('fabric.mod.json') {
+ expand('version': project.version)
+ }
+}
+
+tasks.named('jar', Jar).configure {
+ archiveFileName.set("Iris-${project.version}-fabric-skeleton.jar")
+}
diff --git a/adapters/fabric/src/main/java/art/arcane/iris/fabric/IrisFabricBootstrap.java b/adapters/fabric/src/main/java/art/arcane/iris/fabric/IrisFabricBootstrap.java
new file mode 100644
index 000000000..b3a1f7d55
--- /dev/null
+++ b/adapters/fabric/src/main/java/art/arcane/iris/fabric/IrisFabricBootstrap.java
@@ -0,0 +1,25 @@
+/*
+ * Iris is a World Generator for Minecraft Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.fabric;
+
+public final class IrisFabricBootstrap {
+ public void onInitialize() {
+ throw new UnsupportedOperationException("The Iris Fabric adapter is a build skeleton; worldgen is not wired yet (see CROSSPLATFORM_PLAN.md Phase 4).");
+ }
+}
diff --git a/adapters/fabric/src/main/resources/fabric.mod.json b/adapters/fabric/src/main/resources/fabric.mod.json
new file mode 100644
index 000000000..47ea06179
--- /dev/null
+++ b/adapters/fabric/src/main/resources/fabric.mod.json
@@ -0,0 +1,13 @@
+{
+ "schemaVersion": 1,
+ "id": "irisworldgen",
+ "version": "${version}",
+ "name": "Iris",
+ "description": "Iris World Generation Engine (Fabric adapter - SKELETON, worldgen not yet wired)",
+ "authors": ["Arcane Arts (Volmit Software)"],
+ "license": "GPL-3.0",
+ "environment": "server",
+ "entrypoints": {
+ "main": ["art.arcane.iris.fabric.IrisFabricBootstrap"]
+ }
+}
diff --git a/adapters/neoforge/build.gradle b/adapters/neoforge/build.gradle
new file mode 100644
index 000000000..02f44592b
--- /dev/null
+++ b/adapters/neoforge/build.gradle
@@ -0,0 +1,27 @@
+plugins {
+ id 'java'
+}
+
+group = 'art.arcane'
+version = rootProject.version
+
+java {
+ toolchain {
+ languageVersion = JavaLanguageVersion.of(25)
+ }
+}
+
+dependencies {
+ implementation(project(':spi'))
+}
+
+processResources {
+ inputs.property('version', project.version)
+ filesMatching('META-INF/neoforge.mods.toml') {
+ expand('version': project.version)
+ }
+}
+
+tasks.named('jar', Jar).configure {
+ archiveFileName.set("Iris-${project.version}-neoforge-skeleton.jar")
+}
diff --git a/adapters/neoforge/src/main/java/art/arcane/iris/neoforge/IrisNeoForgeBootstrap.java b/adapters/neoforge/src/main/java/art/arcane/iris/neoforge/IrisNeoForgeBootstrap.java
new file mode 100644
index 000000000..9f2f695ad
--- /dev/null
+++ b/adapters/neoforge/src/main/java/art/arcane/iris/neoforge/IrisNeoForgeBootstrap.java
@@ -0,0 +1,25 @@
+/*
+ * Iris is a World Generator for Minecraft Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.neoforge;
+
+public final class IrisNeoForgeBootstrap {
+ public IrisNeoForgeBootstrap() {
+ throw new UnsupportedOperationException("The Iris NeoForge adapter is a build skeleton; worldgen is not wired yet (see CROSSPLATFORM_PLAN.md Phase 4).");
+ }
+}
diff --git a/adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml b/adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml
new file mode 100644
index 000000000..d25912b22
--- /dev/null
+++ b/adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml
@@ -0,0 +1,10 @@
+modLoader = "javafml"
+loaderVersion = "[1,)"
+license = "GPL-3.0"
+
+[[mods]]
+modId = "irisworldgen"
+version = "${version}"
+displayName = "Iris"
+description = "Iris World Generation Engine (NeoForge adapter - SKELETON, worldgen not yet wired)"
+authors = "Arcane Arts (Volmit Software)"
diff --git a/build-all.sh b/build-all.sh
new file mode 100755
index 000000000..50d85f485
--- /dev/null
+++ b/build-all.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+./gradlew buildAll "$@"
diff --git a/build.gradle b/build.gradle
index 1e28c8274..e5dd17977 100644
--- a/build.gradle
+++ b/build.gradle
@@ -41,7 +41,8 @@ plugins {
}
group = 'art.arcane'
-version = '4.0.0-26.1'
+version = providers.gradleProperty('irisVersion').getOrElse('4.0.0-26.1')
+String minecraftVersion = providers.gradleProperty('minecraftVersion').getOrElse('26.1.2')
String volmLibCoordinate = providers.gradleProperty('volmLibCoordinate')
.orElse('com.github.VolmitSoftware:VolmLib:master-SNAPSHOT')
.get()
@@ -72,7 +73,7 @@ def nmsBindings = [
]
Class nmsTypeClass = Class.forName('NMSBinding$Type')
nmsBindings.each { key, value ->
- project(":nms:${key}") {
+ project(":adapters:bukkit:nms:${key}") {
apply plugin: JavaPlugin
def nmsConfig = new Config()
@@ -98,7 +99,7 @@ def included = configurations.create('included')
def jarJar = configurations.create('jarJar')
dependencies {
nmsBindings.keySet().each { key ->
- add('included', project(path: ":nms:${key}", configuration: 'runtimeElements'))
+ add('included', project(path: ":adapters:bukkit:nms:${key}", configuration: 'runtimeElements'))
}
add('included', project(path: ':core', configuration: 'shadow'))
add('jarJar', project(':core:agent'))
@@ -118,6 +119,46 @@ tasks.register('iris', Copy) {
into(layout.buildDirectory)
}
+tasks.register('buildBukkit', Copy) {
+ group = 'iris'
+ dependsOn('jar')
+ from(layout.buildDirectory.file("libs/Iris-${project.version}.jar"))
+ rename { "Iris-${project.version}+mc${minecraftVersion}.jar" }
+ into(layout.projectDirectory.dir('dist'))
+}
+
+tasks.register('buildFabric', Copy) {
+ group = 'iris'
+ dependsOn(':adapters:fabric:jar')
+ from(project(':adapters:fabric').layout.buildDirectory.file("libs/Iris-${project.version}-fabric-skeleton.jar"))
+ rename { "Iris-${project.version}+mc${minecraftVersion}-fabric-skeleton.jar" }
+ into(layout.projectDirectory.dir('dist'))
+}
+
+tasks.register('buildNeoforge', Copy) {
+ group = 'iris'
+ dependsOn(':adapters:neoforge:jar')
+ from(project(':adapters:neoforge').layout.buildDirectory.file("libs/Iris-${project.version}-neoforge-skeleton.jar"))
+ rename { "Iris-${project.version}+mc${minecraftVersion}-neoforge-skeleton.jar" }
+ into(layout.projectDirectory.dir('dist'))
+}
+
+tasks.register('buildAll') {
+ group = 'iris'
+ dependsOn('buildBukkit', 'buildFabric', 'buildNeoforge', ':spi:jar')
+ doLast {
+ File dist = layout.projectDirectory.dir('dist').asFile
+ File[] jars = dist.listFiles((java.io.FileFilter) { File f -> f.name.endsWith('.jar') })
+ println('')
+ println('=== Iris buildAll -> dist/ ===')
+ if (jars != null) {
+ jars.sort { it.name }.each { File f ->
+ println(String.format(' %-60s %8d KB', f.name, (long) (f.length() / 1024)))
+ }
+ }
+ }
+}
+
tasks.register('irisDev', Copy) {
group = 'iris'
from(project(':core').layout.buildDirectory.files('libs/core-javadoc.jar', 'libs/core-sources.jar'))
diff --git a/gradle.properties b/gradle.properties
index b4be6da17..851b86f52 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -22,4 +22,6 @@ org.gradle.caching=true
org.gradle.configureondemand=false
nmsTools.repo-url=https://repo.codemc.org/repository/nms/
-nmsTools.specialSourceVersion=1.11.4
\ No newline at end of file
+nmsTools.specialSourceVersion=1.11.4
+irisVersion=4.0.0-26.1
+minecraftVersion=26.1.2
diff --git a/settings.gradle b/settings.gradle
index 3537f125b..42c96bc12 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -69,5 +69,8 @@ if (useLocalVolmLib && localVolmLibDirectory != null) {
}
include(':core', ':core:agent')
-include(':nms:v1_21_R7')
-include(':nms:v26_1_R1')
+include(':spi')
+include(':adapters:bukkit:nms:v1_21_R7')
+include(':adapters:bukkit:nms:v26_1_R1')
+include(':adapters:fabric')
+include(':adapters:neoforge')
diff --git a/spi/build.gradle b/spi/build.gradle
new file mode 100644
index 000000000..019cf2024
--- /dev/null
+++ b/spi/build.gradle
@@ -0,0 +1,16 @@
+plugins {
+ id 'java-library'
+}
+
+group = 'art.arcane'
+version = rootProject.version
+
+java {
+ toolchain {
+ languageVersion = JavaLanguageVersion.of(25)
+ }
+}
+
+tasks.named('jar', Jar).configure {
+ archiveBaseName.set('iris-spi')
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/ChunkWriteTarget.java b/spi/src/main/java/art/arcane/iris/spi/ChunkWriteTarget.java
new file mode 100644
index 000000000..250148dbf
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/ChunkWriteTarget.java
@@ -0,0 +1,32 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Hot-path chunk write surface backed by the fastest native section-write mechanism each adapter offers.
+ */
+public interface ChunkWriteTarget {
+ void setBlock(int x, int y, int z, PlatformBlockState state);
+
+ void setBiome(int x, int y, int z, PlatformBiome biome);
+
+ int minHeight();
+
+ int maxHeight();
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/IrisPlatform.java b/spi/src/main/java/art/arcane/iris/spi/IrisPlatform.java
new file mode 100644
index 000000000..0806652fc
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/IrisPlatform.java
@@ -0,0 +1,40 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+import java.io.File;
+
+/**
+ * Root platform service provided by each adapter; the single entry point core uses to reach the host platform.
+ */
+public interface IrisPlatform {
+ String platformName();
+
+ String minecraftVersion();
+
+ PlatformRegistries registries();
+
+ PlatformScheduler scheduler();
+
+ PlatformCapabilities capabilities();
+
+ File dataFolder();
+
+ void log(LogLevel level, String message);
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/LogLevel.java b/spi/src/main/java/art/arcane/iris/spi/LogLevel.java
new file mode 100644
index 000000000..fdd03eaf3
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/LogLevel.java
@@ -0,0 +1,29 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Severity levels for platform-routed log messages.
+ */
+public enum LogLevel {
+ DEBUG,
+ INFO,
+ WARN,
+ ERROR
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformBiome.java b/spi/src/main/java/art/arcane/iris/spi/PlatformBiome.java
new file mode 100644
index 000000000..64883336d
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformBiome.java
@@ -0,0 +1,30 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Neutral handle for a resolved biome backed by an adapter-owned native handle.
+ */
+public interface PlatformBiome {
+ String key();
+
+ String namespace();
+
+ Object nativeHandle();
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformBlockState.java b/spi/src/main/java/art/arcane/iris/spi/PlatformBlockState.java
new file mode 100644
index 000000000..a7d3c9e68
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformBlockState.java
@@ -0,0 +1,38 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Neutral handle for a resolved block state; the canonical key is the config currency and the native handle is adapter-owned.
+ */
+public interface PlatformBlockState {
+ String key();
+
+ String namespace();
+
+ boolean isAir();
+
+ boolean isSolid();
+
+ boolean hasTileEntity();
+
+ PlatformBlockState withProperty(String name, String value);
+
+ Object nativeHandle();
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformCapabilities.java b/spi/src/main/java/art/arcane/iris/spi/PlatformCapabilities.java
new file mode 100644
index 000000000..550081158
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformCapabilities.java
@@ -0,0 +1,40 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Capability flags describing which optional platform features an adapter supports; all default to unsupported.
+ */
+public interface PlatformCapabilities {
+ default boolean customBiomes() {
+ return false;
+ }
+
+ default boolean dataPacks() {
+ return false;
+ }
+
+ default boolean structurePlacement() {
+ return false;
+ }
+
+ default boolean regionizedThreading() {
+ return false;
+ }
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformEntityType.java b/spi/src/main/java/art/arcane/iris/spi/PlatformEntityType.java
new file mode 100644
index 000000000..e2c7e91cb
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformEntityType.java
@@ -0,0 +1,30 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Neutral handle for a resolved entity type backed by an adapter-owned native handle.
+ */
+public interface PlatformEntityType {
+ String key();
+
+ String namespace();
+
+ Object nativeHandle();
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformItem.java b/spi/src/main/java/art/arcane/iris/spi/PlatformItem.java
new file mode 100644
index 000000000..87a7cc41d
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformItem.java
@@ -0,0 +1,30 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Neutral handle for a resolved item type backed by an adapter-owned native handle.
+ */
+public interface PlatformItem {
+ String key();
+
+ String namespace();
+
+ Object nativeHandle();
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformRegistries.java b/spi/src/main/java/art/arcane/iris/spi/PlatformRegistries.java
new file mode 100644
index 000000000..194db1b10
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformRegistries.java
@@ -0,0 +1,40 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+import java.util.List;
+
+/**
+ * Resolves namespaced string keys against the platform's live registries into interned neutral handles.
+ */
+public interface PlatformRegistries {
+ PlatformBlockState block(String key);
+
+ PlatformBiome biome(String key);
+
+ PlatformItem item(String key);
+
+ PlatformEntityType entity(String key);
+
+ List blockKeys();
+
+ List biomeKeys();
+
+ List structureKeys();
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformScheduler.java b/spi/src/main/java/art/arcane/iris/spi/PlatformScheduler.java
new file mode 100644
index 000000000..2f560d5f2
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformScheduler.java
@@ -0,0 +1,34 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Platform task dispatch; region scheduling targets the owning region thread on regionized platforms and the global thread elsewhere.
+ */
+public interface PlatformScheduler {
+ void global(Runnable task);
+
+ void region(PlatformWorld world, int chunkX, int chunkZ, Runnable task);
+
+ void async(Runnable task);
+
+ void laterGlobal(Runnable task, int ticks);
+
+ void laterRegion(PlatformWorld world, int chunkX, int chunkZ, Runnable task, int ticks);
+}
diff --git a/spi/src/main/java/art/arcane/iris/spi/PlatformWorld.java b/spi/src/main/java/art/arcane/iris/spi/PlatformWorld.java
new file mode 100644
index 000000000..ff29a5f1a
--- /dev/null
+++ b/spi/src/main/java/art/arcane/iris/spi/PlatformWorld.java
@@ -0,0 +1,42 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2026 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see .
+ */
+
+package art.arcane.iris.spi;
+
+/**
+ * Neutral view of a loaded world for edit and lifecycle paths; never used on the generation hot path.
+ */
+public interface PlatformWorld {
+ String name();
+
+ long seed();
+
+ int minHeight();
+
+ int maxHeight();
+
+ PlatformBlockState getBlock(int x, int y, int z);
+
+ void setBlock(int x, int y, int z, PlatformBlockState block, int flags);
+
+ PlatformBiome getBiome(int x, int y, int z);
+
+ boolean isChunkLoaded(int chunkX, int chunkZ);
+
+ Object nativeHandle();
+}