Architectury is a framework that\nlets you write one mod codebase that compiles to both NeoForge and Fabric JARs.\nThe common subproject has a shared API; platform subprojects implement\nplatform-specific behavior behind the @ExpectPlatform abstraction.
Use when: one shared codebase must build and ship both NeoForge and Fabric artifacts.Do not use when: the project is single-loader only (minecraft-modding for NeoForge/Fabric, not both).Do not use when: the task is Paper/Bukkit plugin development (minecraft-plugin-dev).| Component | \nPurpose | \n
|---|---|
architectury-loom | \nGradle plugin — extends Fabric Loom for multiloader support | \n
architectury-api | \nRuntime library — abstractions over both platforms | \n
@ExpectPlatform | \nAnnotation marking methods with platform-specific implementations | \n
common/ | \nShared code (no loader-specific APIs) | \n
fabric/ | \nFabric-specific code + entrypoint | \n
neoforge/ | \nNeoForge-specific code + entrypoint | \n
# gradle.properties property names used by this skill's static helper.\n# Get every tool version from the exact generated or known-working project.\nmod_version=1.0.0\nminecraft_version=1.21.11\nenabled_platforms=fabric,neoforge\n\narchitectury_version=<project pin>\nfabric_loader_version=<project pin>\nfabric_api_version=<project pin ending in +1.21.11>\nneoforge_version=<project pin in the 21.11.x family>\nloom_version=<project pin>\nPin architectury_version, the Architectury plugin version, and loom_version\nfrom the same generated or known-working project line. This skill deliberately\ndoes not publish a copyable dependency matrix: its static helper cannot resolve\nwhether a particular set of versions is compatible.
For the current Minecraft 26.2 / Java 25 lane, use the official\nArchitectury Template Generator only when\nits version selector offers the exact target. Generate a Multiplatform\nproject with Fabric and NeoForge, then preserve the generated Gradle layout and\npins as one set. If the generator does not offer the target, begin with an\nalready working project on that exact line and inspect its resolved build; do\nnot relabel a 1.21.11 template as 26.2. The published template downloads are\nnot a substitute for an exact-current scaffold.
\nDo not mechanically change only minecraft_version in the retained example:\n26.2 is unobfuscated and its Loom/remapping setup differs from 1.21.11.
references/architectury-reference.md./scripts/check-version-sanity.sh --root <project>Run the sanity checker after editing gradle.properties. It is a static\nsyntax-and-version-family preflight: it catches missing keys, snapshot pins,\nmissing fabric / neoforge platforms, and obvious version-family drift. It\ndoes not resolve dependencies, prove loader compatibility, or replace the\nproject's Fabric and NeoForge build and smoke tests.
my-mod/\n├── build.gradle ← root build (shared config)\n├── settings.gradle\n├── gradle.properties\n├── common/\n│ ├── build.gradle\n│ └── src/main/java/com/example/mymod/\n│ ├── MyMod.java ← shared init\n│ ├── registry/\n│ │ └── ModItems.java ← shared registry declarations\n│ └── platform/\n│ └── PlatformHelper.java ← @ExpectPlatform methods\n├── fabric/\n│ ├── build.gradle\n│ └── src/main/\n│ ├── java/com/example/mymod/fabric/\n│ │ ├── MyModFabric.java ← Fabric entrypoint\n│ ├── java/com/example/mymod/platform/\n│ │ └── PlatformHelperImpl.java ← Fabric @ExpectPlatform implementation\n│ └── resources/\n│ ├── fabric.mod.json\n│ └── assets/...\n└── neoforge/\n ├── build.gradle\n └── src/main/\n ├── java/com/example/mymod/neoforge/\n │ ├── MyModNeoForge.java ← NeoForge @Mod entry\n ├── java/com/example/mymod/platform/\n │ └── PlatformHelperImpl.java ← NeoForge @ExpectPlatform implementation\n └── resources/\n ├── META-INF/neoforge.mods.toml\n └── assets/...\nThe old fixed Gradle scripts were a 1.21.11 snapshot and are intentionally not\npresented as a current scaffold. For either supported lane, read\nreferences/legacy-1.21.11-template.md\nor references/architectury-reference.md\nbefore changing generated build files. They preserve version anchors and\nsource-set boundaries without encouraging a partial build script to be copied\ninto a different Minecraft line.
common/.../MyMod.javapackage com.example.mymod;\n\nimport dev.architectury.registry.registries.DeferredRegister;\nimport dev.architectury.registry.registries.RegistrySupplier;\nimport net.minecraft.core.registries.Registries;\nimport net.minecraft.resources.Identifier;\nimport net.minecraft.resources.ResourceKey;\nimport net.minecraft.world.item.Item;\n\npublic class MyMod {\n public static final String MOD_ID = \"mymod\";\n\n // Architectury's DeferredRegister — works on both platforms\n public static final DeferredRegister<Item> ITEMS =\n DeferredRegister.create(MOD_ID, Registries.ITEM);\n\n public static final RegistrySupplier<Item> MY_ITEM =\n ITEMS.register(\"my_item\", () -> new Item(new Item.Properties().setId(\n ResourceKey.create(Registries.ITEM,\n Identifier.fromNamespaceAndPath(MOD_ID, \"my_item\"))\n )));\n\n public static void init() {\n ITEMS.register(); // registers with both platforms\n }\n}\n@ExpectPlatform — platform-specific methodsDefine the contract in common/:
package com.example.mymod.platform;\n\nimport dev.architectury.injectables.annotations.ExpectPlatform;\nimport net.minecraft.world.level.material.Fluid;\n\npublic class PlatformHelper {\n\n @ExpectPlatform\n public static boolean isModLoaded(String modId) {\n // This body is replaced at compile time by the platform implementation\n throw new AssertionError(\"ExpectPlatform implementation not found\");\n }\n\n @ExpectPlatform\n public static boolean isClient() {\n throw new AssertionError();\n }\n}\nKeep each platform implementation in the same Java package as the common\n@ExpectPlatform class. Only the source set changes between common/,\nfabric/, and neoforge/.
Implement in fabric/.../platform/PlatformHelperImpl.java:
package com.example.mymod.platform;\n\nimport net.fabricmc.loader.api.FabricLoader;\n\n// Class name must match: <common class name>Impl\npublic class PlatformHelperImpl {\n\n public static boolean isModLoaded(String modId) {\n return FabricLoader.getInstance().isModLoaded(modId);\n }\n\n public static boolean isClient() {\n return FabricLoader.getInstance().getEnvironmentType() ==\n net.fabricmc.api.EnvType.CLIENT;\n }\n}\nImplement in neoforge/.../platform/PlatformHelperImpl.java:
package com.example.mymod.platform;\n\nimport net.neoforged.fml.ModList;\nimport net.neoforged.fml.loading.FMLEnvironment;\n\npublic class PlatformHelperImpl {\n\n public static boolean isModLoaded(String modId) {\n return ModList.get().isLoaded(modId);\n }\n\n public static boolean isClient() {\n return FMLEnvironment.dist.isClient();\n }\n}\nfabric/.../MyModFabric.javapackage com.example.mymod.fabric;\n\nimport com.example.mymod.MyMod;\nimport net.fabricmc.api.ModInitializer;\n\npublic class MyModFabric implements ModInitializer {\n @Override\n public void onInitialize() {\n MyMod.init();\n }\n}\nfabric/.../resources/fabric.mod.jsonThis retained-1.21.11 metadata example follows the minimum dependencies in the\nupstream Architectury 1.21.11 branch.\nKeep the generated project's exact ranges when they are stricter.
\n{\n \"schemaVersion\": 1,\n \"id\": \"mymod\",\n \"version\": \"${version}\",\n \"name\": \"My Mod\",\n \"description\": \"A multiloader example mod\",\n \"license\": \"MIT\",\n \"environment\": \"*\",\n \"entrypoints\": {\n \"main\": [\"com.example.mymod.fabric.MyModFabric\"]\n },\n \"depends\": {\n \"fabricloader\": \">=0.18.2\",\n \"fabric-api\": \">=0.139.4+1.21.11\",\n \"architectury\": \">=19.0\",\n \"minecraft\": \"~1.21.11\"\n }\n}\nneoforge/.../MyModNeoForge.javapackage com.example.mymod.neoforge;\n\nimport com.example.mymod.MyMod;\nimport net.neoforged.bus.api.IEventBus;\nimport net.neoforged.fml.common.Mod;\n\n@Mod(MyMod.MOD_ID)\npublic class MyModNeoForge {\n public MyModNeoForge(IEventBus modEventBus) {\n MyMod.init();\n }\n}\nneoforge/.../resources/META-INF/neoforge.mods.tomlmodLoader = \"javafml\"\nloaderVersion = \"[1,)\"\nlicense = \"MIT\"\n\n[[mods]]\nmodId = \"mymod\"\nversion = \"${file.jarVersion}\"\ndisplayName = \"My Mod\"\ndescription = \"A multiloader example mod\"\n\n[[dependencies.mymod]]\nmodId = \"neoforge\"\ntype = \"required\"\nversionRange = \"[21.11,)\"\nordering = \"NONE\"\nside = \"BOTH\"\n\n[[dependencies.mymod]]\nmodId = \"minecraft\"\ntype = \"required\"\nversionRange = \"[1.21.11,1.22)\"\nordering = \"NONE\"\nside = \"BOTH\"\n# Build both JARs simultaneously\n./gradlew build\n\n# Inspect the project's actual outputs. Generated templates choose their own\n# archive base name and version convention:\nfind fabric/build/libs neoforge/build/libs -maxdepth 1 -type f -name '*.jar' \\\n ! -name '*-sources.jar' ! -name '*-dev.jar' ! -name '*-javadoc.jar'\n\n# Run in dev environment\n./gradlew :fabric:runClient\n./gradlew :neoforge:runClient\n./gradlew :neoforge:runServer\n\n# Datagen (if applicable)\n./gradlew :neoforge:runData\n| Pitfall | \nSolution | \n
|---|---|
Using net.neoforged.* / net.fabricmc.* in common/ | \nOnly use vanilla MC and Architectury APIs in common | \n
Direct field access on DeferredRegister (NeoForge style) in common | \nUse Architectury's DeferredRegister | \n
| Constructing a 26.2 item without a registry key | \nCreate its ResourceKey<Item> and call Item.Properties#setId before new Item | \n
Forgetting @ExpectPlatform throws AssertionError at runtime | \nBoth fabric/ and neoforge/ must have matching same-package *Impl classes | \n
| Assets duplicated in fabric/ and neoforge/ | \nKeep assets in common/src/main/resources/assets/ | \n
| A common Mixin imports a loader API or targets one loader's side | \nPut it in that platform subproject; loader-neutral Mixins may be common when both generated platform configurations include them | \n
| Accessing world/registry on mod init thread | \nUse mod bus events for setup; never access world on init | \n