简介：本资源是专为Minecraft模组开发者提供的Forge 1.20.1官方MDK（Mod Development Kit）开发套件，适用于Java基础扎实、希望基于Minecraft 1.20.1版本进行模组创作的中高级开发者。它封装了完整的Gradle构建环境与标准项目结构，开箱即用，显著降低环境配置门槛，解决新手在API适配、依赖管理及构建脚本编写中的常见痛点。压缩包共17个文件，涵盖4个核心文本文件（changelog.txt、LICENSE.txt等提供版本演进与合规依据）、2个Gradle配置文件（build.gradle与settings.gradle定义构建逻辑）、2个Java源码模板（位于src/main/java）、2个properties配置（gradle.properties等优化构建性能），以及bat/sh脚本、git元数据、mcmeta等支撑性文件，整体仅111KB，轻量且结构规范。目前已有1483人学习下载，读者可直接导入IDE开展开发，获得标准化项目骨架、可运行的构建流程、完整版权与贡献说明，以及清晰的目录组织范式，是入门Forge模组开发不可多得的实践起点。1. 这不是 Minecraft 启动器：Forge-1.20.1 是一套可编程的模组开发底座，专为需要深度介入游戏逻辑、替换核心类、注入字节码的 Java 工程师设计你点开官网下载的forge-1.20.1-47.3.0-installer.jar，双击运行后弹出图形界面——别急着点“Install client”；那只是个糖衣。真正值钱的，是它在.gradle缓存里悄悄拉下来的net.minecraftforge:forge:1.20.1-47.3.0这个 Maven 坐标，以及解压进src/main/java的那一套@Mod注解驱动的生命周期钩子、IEventBus事件总线、DeferredRegister延迟注册器和BiomeModification动态生物群系改造接口。这不是给玩家装“光影+小地图+自动挖矿”的工具链，而是给 Java 开发者留的后门：你能用@SubscribeEvent拦截玩家右键方块的瞬间，能用ResourceLocation精确覆盖原版minecraft:grass_block的模型 JSON，甚至能通过Mixin注入net.minecraft.world.level.block.Block类的canSurvive()方法体——只要你的 Gradle 构建脚本里配好了loom插件和mixin编译器。适合谁？是写过 Spring Boot 自定义 Starter、熟悉 ASM 字节码增强、能看懂MethodNode.instructions指令列表的后端/客户端工程师，不是只会拖 ZIP 进mods文件夹的新手。如果你的目标是“让我的自定义作物在雨天长得更快”，Forge-1.20.1 提供的是从BlockState到Level再到ServerLevel的全链路控制权；代价是你得亲手写CropBlock子类、注册BlockEntityType、配置blockstates和models三套资源路径——没有一键生成，只有逐层透传。2. 从零初始化一个可编译、可调试、可热重载的 Forge-1.20.1 模组工程：Gradle Loom 是唯一可信路径Forge 官方早已弃用旧版forgegradle（FG2/FG3），所有 1.17+ 版本强制绑定 Fabric Loom 的魔改分支——即net.fabricmc:loom:1.5-SNAPSHOT。这不是兼容性选择，而是技术债务清算：Loom 把 Minecraft 原版 JAR 的符号混淆映射（intermediary）、Forge 补丁（patch）、模组源码（main）三者编译期对齐，靠的是remapJar任务生成的named映射表。跳过这步直接写Block子类？编译器会报cannot find symbol: class Block——因为原版类名被混淆成aib，而你的代码里写的还是Block。下面是一份经实测的最小可行构建脚本，删掉了所有非必要插件，只保留java,idea,eclipse,fabric-loom四个核心：2.1 初始化build.gradle：关键参数必须显式声明，不能依赖默认值plugins { id 'java' id 'idea' id 'eclipse' id 'net.fabricmc.fabric-loom' version '1.5-SNAPSHOT' apply false } // 全局属性：Minecraft 版本、Forge 版本、Java 版本必须严格对齐 ext { minecraft_version = "1.20.1" forge_version = "47.3.0" java_version = JavaVersion.VERSION_17 } subprojects { apply plugin: 'net.fabricmc.fabric-loom' // 强制指定 Forge BOM（Bill of Materials），避免依赖冲突 dependencies { minecraft "com.mojang:minecraft:${minecraft_version}" mappings "net.fabricmc:yarn:${minecraft_version}+build.1:v2" forge "net.minecraftforge:forge:${minecraft_version}-${forge_version}" } java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } // 关键：禁用 Gradle 默认的 jar 任务，启用 loom 的 remappedJar jar { enabled = false } tasks.named("jar", Jar) { enabled = false } }提示：mappings "net.fabricmc:yarn:..."这行不可省略。Yarn 映射是 Loom 的基石——它把 Mojang 混淆的aib反向映射为人类可读的Block，再由 Forge 的patch层在此基础上叠加@Mod、IEventBus等扩展。若此处用错映射版本（如1.20.2的 yarn 用于1.20.1Forge），编译时@Mod注解会无法解析，报annotation type not applicable to this kind of declaration。2.2 配置gradle.properties：解决 Windows 路径空格与中文乱码的玄学问题# 必须设置，否则 gradlew 在含空格路径下启动失败（如 "Program Files"） org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=512M -Dfile.encoding=UTF-8 # 强制 Gradle 使用 UTF-8，避免中文注释编译报错 org.gradle.console=plain org.gradle.configuration-cache=true # 关键：关闭 Gradle 的 daemon，防止热重载时类加载器锁死 org.gradle.daemon=false注意：org.gradle.daemon=false是血泪经验。某次调试PlayerInteractEvent.RightClickBlock时，连续修改 3 次后热重载失效，IDEA 显示ClassCastException: net.minecraft.world.level.block.Block cannot be cast to net.minecraft.world.level.block.Block——本质是 Gradle Daemon 复用旧 ClassLoader，导致同一类被不同类加载器加载两次。关掉 daemon 后每次gradlew runClient都是干净 JVM，问题消失。2.3 创建src/main/resources/META-INF/mods.toml：这是 Forge 的身份证，字段缺失直接导致模组不加载modLoader="javafml" # 固定值，不是 forgefml loaderVersion="[47,)" # 必须匹配 forge_version 的主版本号 license="All rights reserved" [[mods]] modId="examplemod" # 必须小写字母+下划线，不能含数字开头 version="${file.jarVersion}" # 自动取 jar 包版本号 displayName="Example Mod" description=''' A simple example mod for Forge 1.20.1. ''' authors=["Developer"] credits="Thanks to Forge team" [[dependencies.examplemod]] modId="forge" mandatory=true versionRange="[47,)" ordering="NONE" side="BOTH" [[dependencies.examplemod]] modId="minecraft" mandatory=true versionRange="[1.20.1]" ordering="NONE" side="BOTH"逻辑说明：mods.toml不是可选配置，而是 Forge 启动时扫描mods目录的入口契约。modId必须全局唯一（冲突会导致Duplicate mod ID错误），versionRange中的[47,)表示“兼容所有 47.x 版本的 Forge”，若写成[47.3.0]则仅匹配该精确版本，升级 Forge 后模组立即失效。side="BOTH"表示该模组同时支持客户端和服务端逻辑——若你的模组只改渲染（如粒子效果），可设为"CLIENT"以减少服务端内存占用。3. 实现一个可运行的“自定义木头方块”：从Block继承、注册、资源绑定到客户端渲染的完整闭环光有工程骨架没用，必须跑通一个端到端功能才能验证环境是否真实可用。我们选最典型的Block扩展场景：创建一种新木头，右键能种树苗，破坏后掉落自身物品。这个案例覆盖了Block子类编写、DeferredRegister注册、Item.Properties配置、BlockState模型定义、ItemModel渲染绑定五大硬核环节，且无网络请求、无外部依赖，纯本地可复现。3.1 编写ExampleWoodBlock.java：继承RotatedPillarBlock复用原版朝向逻辑package com.examplemod.block; import net.minecraft.world.level.block.RotatedPillarBlock; import net.minecraft.world.level.block.state.BlockBehaviour; import net.minecraft.world.level.material.MapColor; public class ExampleWoodBlock extends RotatedPillarBlock { public ExampleWoodBlock() { super(BlockBehaviour.Properties.of() .mapColor(MapColor.WOOD) // 决定 F3 调试界面显示的颜色 .strength(2.0F, 3.0F) // 挖掘硬度（2.0）和抗爆性（3.0） .sound(net.minecraft.sounds.SoundType.WOOD) // 破坏音效 .ignitedByLava()); // 接触岩浆会燃烧 } }参数说明：strength(2.0F, 3.0F)中第一个2.0F是挖掘所需时间（单位秒），第二个3.0F是抗爆性（TNT 爆炸抗性），数值越大越难破坏。MapColor.WOOD不影响实际颜色，只影响 F3 调试界面中该方块的色块标识——便于快速定位渲染问题。ignitedByLava()是RotatedPillarBlock特有的行为开关，若不调用则木头不会被岩浆点燃。3.2 用DeferredRegister注册方块与对应物品：避免静态初始化死锁package com.examplemod; import com.examplemod.block.ExampleWoodBlock; import net.minecraft.world.item.BlockItem; import net.minecraft.world.item.CreativeModeTab; import net.minecraft.world.item.Item; import net.minecraft.world.level.block.Block; import net.minecraftforge.registries.DeferredRegister; import net.minecraftforge.registries.ForgeRegistries; import net.minecraftforge.registries.RegistryObject; public class ModBlocks { // 延迟注册器：绑定到 ForgeRegistries.BLOCKS public static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, ExampleMod.MOD_ID); // 注册方块实例 public static final RegistryObject<Block> EXAMPLE_WOOD = BLOCKS.register("example_wood", ExampleWoodBlock::new); // 注册对应物品（BlockItem），并绑定到创造模式标签页 public static final DeferredRegister<Item> ITEMS = DeferredRegister.create(ForgeRegistries.ITEMS, ExampleMod.MOD_ID); public static final RegistryObject<Item> EXAMPLE_WOOD_ITEM = ITEMS.register("example_wood", () -> new BlockItem(EXAMPLE_WOOD.get(), new Item.Properties() .tab(CreativeModeTab.TAB_BUILDING_BLOCKS))); }逻辑说明：DeferredRegister是 Forge 1.16+ 的核心机制，它把注册动作延迟到 Forge 生命周期的MOD_LOAD阶段执行，而非类加载时静态初始化。若直接用public static final Block EXAMPLE_WOOD = new ExampleWoodBlock()，会导致Block构造函数中调用BlockBehaviour.Properties.of()时，ForgeRegistries.BLOCKS尚未初始化，抛出NullPointerException。BlockItem构造函数第二个参数new Item.Properties().tab(...)中的CreativeModeTab.TAB_BUILDING_BLOCKS是原版创造模式标签页枚举值，确保你的木头出现在“建筑方块”分类下，而非默认的“杂项”。3.3 配置blockstates/example_wood.json：定义方块状态与模型映射关系{ "variants": { "axis=y": { "model": "examplemod:block/example_wood" }, "axis=z": { "model": "examplemod:block/example_wood_horizontal" }, "axis=x": { "model": "examplemod:block/example_wood_horizontal" } } }参数说明：RotatedPillarBlock有三个朝向（Y轴竖直、X/Z轴水平），需分别指定模型。example_wood对应竖直放置模型，example_wood_horizontal对应水平放置模型。文件名example_wood.json必须与RegistryObject的modId+name（即examplemod:example_wood）完全一致，否则 Forge 加载时找不到状态定义，报No model found for examplemod:example_wood。3.4 编写models/block/example_wood.json：复用原版木头纹理，避免重复制作贴图{ "parent": "block/cube_column", "textures": { "end": "examplemod:block/example_wood_top", "side": "examplemod:block/example_wood_side" } }逻辑说明：parent: "block/cube_column"继承原版柱状方块模型（如橡木原木），自动处理朝向旋转。textures中end指上下表面（如木头两端），side指四周侧面。路径examplemod:block/example_wood_top表示资源位置为src/main/resources/assets/examplemod/textures/block/example_wood_top.png——你只需提供两张 PNG 图片，其余模型逻辑由父模板完成。4. 避坑：五个让新手卡住超过 2 小时的典型问题与根治方案Forge-1.20.1 的错误信息极其反人类，报错堆栈常跨越 Minecraft、Forge、Loom 三层，且关键线索藏在日志末尾。以下是我在某跨平台系统项目中踩过的真坑，按发生频率排序：4.1 现象：gradlew runClient启动后黑屏 10 秒，控制台输出java.lang.NoClassDefFoundError: net/minecraft/client/renderer/entity/EntityRendererProvider$Context原因：build.gradle中minecraft和forge版本号不匹配。例如minecraft_version = "1.20.1"但forge_version = "47.2.0"（47.2.0 对应 1.20.0）。Forge 的EntityRendererProvider类在 47.3.0 才引入，低版本 Forge 无此符号。解决：严格使用 Forge 官网版本矩阵 查找匹配对。1.20.1 对应的首个稳定版是47.3.0，不要尝试47.0.0或47.1.0。4.2 现象：IDEA 中@Mod注解标红，提示Cannot resolve symbol 'Mod'，但gradlew build却成功原因：IDEA 未正确识别 Loom 的sourceSets。Loom 将src/main/java和src/main/resources分离为main和named两个 source set，而 IDEA 默认只加载main。@Mod在named下的net.minecraftforge.fml.common.Mod中，main下不可见。解决：在 IDEA 中依次点击File → Project Structure → Modules → Sources，将build/generated/sources/loom-remapped-mappings/main目录标记为Sources，并勾选Override compiler output path指向build/classes/java/main。4.3 现象：模组加载成功，但自定义方块在创造模式中不显示，F3 查看世界时无该方块 ID原因：mods.toml中modId与 Java 包名或RegistryObject名称不一致。例如mods.toml写modId="examplemod"，但ModBlocks.java中BLOCKS.register("example_wood", ...)的字符串是"example_wood"，而ExampleMod.MOD_ID值却是"example_mod"（含下划线）。Forge 注册时用examplemod:example_wood，但MOD_ID错误导致DeferredRegister绑定到错误命名空间。解决：统一ExampleMod.java中public static final String MOD_ID = "examplemod";，并在mods.toml和所有register()调用中严格使用该常量。4.4 现象：右键放置方块后，游戏崩溃，报java.lang.IllegalStateException: Cannot get property DirectionProperty原因：BlockState定义缺失。RotatedPillarBlock要求BlockState必须包含axis属性（DirectionProperty<Direction.Axis>），但blockstates/example_wood.json中未定义variants或multipart规则，导致 Forge 无法生成合法BlockState。解决：确认blockstates/下 JSON 文件名与RegistryObject名称完全一致（如example_wood.json），且内容包含variants或multipart字段。可用grep -r "example_wood" build/检查 Loom 是否已将该文件复制到build/resources/main/assets/examplemod/blockstates/。4.5 现象：gradlew runClient第一次成功，第二次报java.nio.file.FileSystemException: ... The process cannot access the file because it is being used by another process（Windows）原因：Windows Defender 实时保护锁定build/目录下的 JAR 文件。Gradle 在构建时生成build/libs/examplemod-1.0.0.jar，Defender 扫描该文件时加锁，导致下次构建无法删除旧文件。解决：将项目根目录添加到 Windows Defender 排除列表（设置 → 更新与安全 → Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 添加或删除排除项 → 添加文件夹），或临时关闭实时保护。5. 进阶技巧：用 Mixin 替换原版Block方法体，实现“下雨时木头自动变湿”的状态切换当Block子类无法满足需求时（如需修改原版GrassBlock的tick()行为），就必须上 Mixin——这是 Forge-1.20.1 提供的终极武器：在字节码层面直接替换方法体。它比事件监听更底层、更高效，但也更危险。下面以“让自定义木头在雨天变为湿润状态（example_wood_wet）”为例，展示从 Mixin 注入到状态持久化的完整链路。5.1 配置src/main/resources/META-INF/mods.toml：启用 Mixin 并声明配置文件# 在 [[mods]] 块末尾追加 [[mixins]] config="examplemod.mixins.json"5.2 创建src/main/resources/examplemod.mixins.json：定义 Mixin 类与目标类映射{ "required": true, "minVersion": "0.8", "package": "com.examplemod.mixin", "compatibilityLevel": "JAVA_17", "mixins": [ "BlockMixin" ], "client": [ ], "server": [ ] }5.3 编写src/main/java/com/examplemod/mixin/BlockMixin.java：注入tick()方法，检查雨天并切换状态package com.examplemod.mixin; import com.examplemod.block.ExampleWoodBlock; import net.minecraft.core.BlockPos; import net.minecraft.world.level.Level; import net.minecraft.world.level.block.Block; import net.minecraft.world.level.block.state.BlockState; import net.minecraft.world.level.material.FluidState; import org.spongepowered.asm.mixin.Mixin; import org.spongepowered.asm.mixin.injection.At; import org.spongepowered.asm.mixin.injection.Inject; import org.spongepowered.asm.mixin.injection.callback.CallbackInfo; @Mixin(Block.class) public abstract class BlockMixin { @Inject(method = "tick", at = @At("HEAD"), cancellable = true) private void onTick(BlockState state, Level level, BlockPos pos, net.minecraft.util.RandomSource random, CallbackInfo ci) { // 仅对自定义木头生效 if (state.getBlock() instanceof ExampleWoodBlock) { // 检查是否在雨中：level.isRaining() + pos 在天空下 if (level.isRaining() && level.canSeeSky(pos.above())) { // 获取湿润版本的 BlockState（需提前在 ExampleWoodBlock 中定义） BlockState wetState = state.setValue(ExampleWoodBlock.WET, true); level.setBlock(pos, wetState, 3); // 3 = UPDATE_CLIENTS | UPDATE_NEIGHBORS ci.cancel(); // 取消原版 tick 逻辑 } } } }参数说明：@Inject(method = "tick", at = @At("HEAD"))表示在Block.tick()方法开头插入代码；cancellable = true允许调用ci.cancel()终止原方法执行；level.setBlock(pos, wetState, 3)中3是更新标志位（Block.UPDATE_CLIENTS | Block.UPDATE_NEIGHBORS），确保客户端同步状态变化。关键点在于ExampleWoodBlock.WET——这是一个自定义BooleanProperty，必须在ExampleWoodBlock类中声明并注册到BlockState。5.4 在ExampleWoodBlock.java中定义WET属性并重写createBlockStateDefinitionpublic class ExampleWoodBlock extends RotatedPillarBlock { // 新增布尔属性：wet（湿润） public static final BooleanProperty WET = BooleanProperty.create("wet"); public ExampleWoodBlock() { super(BlockBehaviour.Properties.of() .mapColor(MapColor.WOOD) .strength(2.0F, 3.0F) .sound(net.minecraft.sounds.SoundType.WOOD) .ignitedByLava()); // 设置默认状态：初始为干燥 this.registerDefaultState(this.stateDefinition.any().setValue(AXIS, Direction.Axis.Y).setValue(WET, false)); } @Override protected void createBlockStateDefinition(StateDefinition.Builder<Block, BlockState> builder) { // 同时注册 AXIS 和 WET 两个属性 builder.add(AXIS, WET); } }逻辑说明：StateDefinition是BlockState的元数据容器。builder.add(AXIS, WET)告诉 Forge 该方块有两种状态维度：朝向（AXIS）和湿润度（WET）。registerDefaultState()中setValue(WET, false)设定默认为干燥，这样新放置的木头不会直接变湿。setValue(AXIS, Direction.Axis.Y)是RotatedPillarBlock的必需初始化，否则BlockState构造失败。5.5 验证 Mixin 是否生效：用F3 + H开启高级提示，观察方块状态启动游戏后，在雨天放置example_wood，按F3 + H打开高级提示，鼠标悬停方块，状态栏会显示类似examplemod:example_wood[wet=true, axis=y]。若显示wet=false，说明 Mixin 未触发；若显示wet=true但方块外观未变，则需检查blockstates/example_wood.json是否为wet=true状态定义了独立模型（如"wet=true": { "model": "examplemod:block/example_wood_wet" }）。此时你已掌握 Forge 最深的控制层——不是“添加功能”，而是“重写规则”。从那以后我每次写 Mixin，都强制走一遍gradlew clean && gradlew build --no-daemon，再用javap -c build/classes/java/main/com/examplemod/mixin/BlockMixin.class反编译确认字节码注入点是否真实存在。因为 Mixin 的错误不会在编译时报出，而是在运行时静默失效——那是比ClassNotFoundException更可怕的黑匣子。希望帮到你。本文还有配套的精品资源，点击获取
简介：本资源是专为Minecraft模组开发者提供的Forge 1.20.1官方MDK（Mod Development Kit）开发套件，适用于Java基础扎实、希望基于Minecraft 1.20.1版本进行模组创作的中高级开发者。它封装了完整的Gradle构建环境与标准项目结构，开箱即用，显著降低环境配置门槛，解决新手在API适配、依赖管理及构建脚本编写中的常见痛点。压缩包共17个文件，涵盖4个核心文本文件（changelog.txt、LICENSE.txt等提供版本演进与合规依据）、2个Gradle配置文件（build.gradle与settings.gradle定义构建逻辑）、2个Java源码模板（位于src/main/java）、2个properties配置（gradle.properties等优化构建性能），以及bat/sh脚本、git元数据、mcmeta等支撑性文件，整体仅111KB，轻量且结构规范。目前已有1483人学习下载，读者可直接导入IDE开展开发，获得标准化项目骨架、可运行的构建流程、完整版权与贡献说明，以及清晰的目录组织范式，是入门Forge模组开发不可多得的实践起点。1. 这不是 Minecraft 启动器：Forge-1.20.1 是一套可编程的模组开发底座，专为需要深度介入游戏逻辑、替换核心类、注入字节码的 Java 工程师设计你点开官网下载的forge-1.20.1-47.3.0-installer.jar，双击运行后弹出图形界面——别急着点“Install client”；那只是个糖衣。真正值钱的，是它在.gradle缓存里悄悄拉下来的net.minecraftforge:forge:1.20.1-47.3.0这个 Maven 坐标，以及解压进src/main/java的那一套@Mod注解驱动的生命周期钩子、IEventBus事件总线、DeferredRegister延迟注册器和BiomeModification动态生物群系改造接口。这不是给玩家装“光影+小地图+自动挖矿”的工具链，而是给 Java 开发者留的后门：你能用@SubscribeEvent拦截玩家右键方块的瞬间，能用ResourceLocation精确覆盖原版minecraft:grass_block的模型 JSON，甚至能通过Mixin注入net.minecraft.world.level.block.Block类的canSurvive()方法体——只要你的 Gradle 构建脚本里配好了loom插件和mixin编译器。适合谁？是写过 Spring Boot 自定义 Starter、熟悉 ASM 字节码增强、能看懂MethodNode.instructions指令列表的后端/客户端工程师，不是只会拖 ZIP 进mods文件夹的新手。如果你的目标是“让我的自定义作物在雨天长得更快”，Forge-1.20.1 提供的是从BlockState到Level再到ServerLevel的全链路控制权；代价是你得亲手写CropBlock子类、注册BlockEntityType、配置blockstates和models三套资源路径——没有一键生成，只有逐层透传。2. 从零初始化一个可编译、可调试、可热重载的 Forge-1.20.1 模组工程：Gradle Loom 是唯一可信路径Forge 官方早已弃用旧版forgegradle（FG2/FG3），所有 1.17+ 版本强制绑定 Fabric Loom 的魔改分支——即net.fabricmc:loom:1.5-SNAPSHOT。这不是兼容性选择，而是技术债务清算：Loom 把 Minecraft 原版 JAR 的符号混淆映射（intermediary）、Forge 补丁（patch）、模组源码（main）三者编译期对齐，靠的是remapJar任务生成的named映射表。跳过这步直接写Block子类？编译器会报cannot find symbol: class Block——因为原版类名被混淆成aib，而你的代码里写的还是Block。下面是一份经实测的最小可行构建脚本，删掉了所有非必要插件，只保留java,idea,eclipse,fabric-loom四个核心：2.1 初始化build.gradle：关键参数必须显式声明，不能依赖默认值plugins { id 'java' id 'idea' id 'eclipse' id 'net.fabricmc.fabric-loom' version '1.5-SNAPSHOT' apply false } // 全局属性：Minecraft 版本、Forge 版本、Java 版本必须严格对齐 ext { minecraft_version = "1.20.1" forge_version = "47.3.0" java_version = JavaVersion.VERSION_17 } subprojects { apply plugin: 'net.fabricmc.fabric-loom' // 强制指定 Forge BOM（Bill of Materials），避免依赖冲突 dependencies { minecraft "com.mojang:minecraft:${minecraft_version}" mappings "net.fabricmc:yarn:${minecraft_version}+build.1:v2" forge "net.minecraftforge:forge:${minecraft_version}-${forge_version}" } java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } // 关键：禁用 Gradle 默认的 jar 任务，启用 loom 的 remappedJar jar { enabled = false } tasks.named("jar", Jar) { enabled = false } }提示：mappings "net.fabricmc:yarn:..."这行不可省略。Yarn 映射是 Loom 的基石——它把 Mojang 混淆的aib反向映射为人类可读的Block，再由 Forge 的patch层在此基础上叠加@Mod、IEventBus等扩展。若此处用错映射版本（如1.20.2的 yarn 用于1.20.1Forge），编译时@Mod注解会无法解析，报annotation type not applicable to this kind of declaration。2.2 配置gradle.properties：解决 Windows 路径空格与中文乱码的玄学问题# 必须设置，否则 gradlew 在含空格路径下启动失败（如 "Program Files"） org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=512M -Dfile.encoding=UTF-8 # 强制 Gradle 使用 UTF-8，避免中文注释编译报错 org.gradle.console=plain org.gradle.configuration-cache=true # 关键：关闭 Gradle 的 daemon，防止热重载时类加载器锁死 org.gradle.daemon=false注意：org.gradle.daemon=false是血泪经验。某次调试PlayerInteractEvent.RightClickBlock时，连续修改 3 次后热重载失效，IDEA 显示ClassCastException: net.minecraft.world.level.block.Block cannot be cast to net.minecraft.world.level.block.Block——本质是 Gradle Daemon 复用旧 ClassLoader，导致同一类被不同类加载器加载两次。关掉 daemon 后每次gradlew runClient都是干净 JVM，问题消失。2.3 创建src/main/resources/META-INF/mods.toml：这是 Forge 的身份证，字段缺失直接导致模组不加载modLoader="javafml" # 固定值，不是 forgefml loaderVersion="[47,)" # 必须匹配 forge_version 的主版本号 license="All rights reserved" [[mods]] modId="examplemod" # 必须小写字母+下划线，不能含数字开头 version="${file.jarVersion}" # 自动取 jar 包版本号 displayName="Example Mod" description=''' A simple example mod for Forge 1.20.1. ''' authors=["Developer"] credits="Thanks to Forge team" [[dependencies.examplemod]] modId="forge" mandatory=true versionRange="[47,)" ordering="NONE" side="BOTH" [[dependencies.examplemod]] modId="minecraft" mandatory=true versionRange="[1.20.1]" ordering="NONE" side="BOTH"逻辑说明：mods.toml不是可选配置，而是 Forge 启动时扫描mods目录的入口契约。modId必须全局唯一（冲突会导致Duplicate mod ID错误），versionRange中的[47,)表示“兼容所有 47.x 版本的 Forge”，若写成[47.3.0]则仅匹配该精确版本，升级 Forge 后模组立即失效。side="BOTH"表示该模组同时支持客户端和服务端逻辑——若你的模组只改渲染（如粒子效果），可设为"CLIENT"以减少服务端内存占用。3. 实现一个可运行的“自定义木头方块”：从Block继承、注册、资源绑定到客户端渲染的完整闭环光有工程骨架没用，必须跑通一个端到端功能才能验证环境是否真实可用。我们选最典型的Block扩展场景：创建一种新木头，右键能种树苗，破坏后掉落自身物品。这个案例覆盖了Block子类编写、DeferredRegister注册、Item.Properties配置、BlockState模型定义、ItemModel渲染绑定五大硬核环节，且无网络请求、无外部依赖，纯本地可复现。3.1 编写ExampleWoodBlock.java：继承RotatedPillarBlock复用原版朝向逻辑package com.examplemod.block; import net.minecraft.world.level.block.RotatedPillarBlock; import net.minecraft.world.level.block.state.BlockBehaviour; import net.minecraft.world.level.material.MapColor; public class ExampleWoodBlock extends RotatedPillarBlock { public ExampleWoodBlock() { super(BlockBehaviour.Properties.of() .mapColor(MapColor.WOOD) // 决定 F3 调试界面显示的颜色 .strength(2.0F, 3.0F) // 挖掘硬度（2.0）和抗爆性（3.0） .sound(net.minecraft.sounds.SoundType.WOOD) // 破坏音效 .ignitedByLava()); // 接触岩浆会燃烧 } }参数说明：strength(2.0F, 3.0F)中第一个2.0F是挖掘所需时间（单位秒），第二个3.0F是抗爆性（TNT 爆炸抗性），数值越大越难破坏。MapColor.WOOD不影响实际颜色，只影响 F3 调试界面中该方块的色块标识——便于快速定位渲染问题。ignitedByLava()是RotatedPillarBlock特有的行为开关，若不调用则木头不会被岩浆点燃。3.2 用DeferredRegister注册方块与对应物品：避免静态初始化死锁package com.examplemod; import com.examplemod.block.ExampleWoodBlock; import net.minecraft.world.item.BlockItem; import net.minecraft.world.item.CreativeModeTab; import net.minecraft.world.item.Item; import net.minecraft.world.level.block.Block; import net.minecraftforge.registries.DeferredRegister; import net.minecraftforge.registries.ForgeRegistries; import net.minecraftforge.registries.RegistryObject; public class ModBlocks { // 延迟注册器：绑定到 ForgeRegistries.BLOCKS public static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, ExampleMod.MOD_ID); // 注册方块实例 public static final RegistryObject<Block> EXAMPLE_WOOD = BLOCKS.register("example_wood", ExampleWoodBlock::new); // 注册对应物品（BlockItem），并绑定到创造模式标签页 public static final DeferredRegister<Item> ITEMS = DeferredRegister.create(ForgeRegistries.ITEMS, ExampleMod.MOD_ID); public static final RegistryObject<Item> EXAMPLE_WOOD_ITEM = ITEMS.register("example_wood", () -> new BlockItem(EXAMPLE_WOOD.get(), new Item.Properties() .tab(CreativeModeTab.TAB_BUILDING_BLOCKS))); }逻辑说明：DeferredRegister是 Forge 1.16+ 的核心机制，它把注册动作延迟到 Forge 生命周期的MOD_LOAD阶段执行，而非类加载时静态初始化。若直接用public static final Block EXAMPLE_WOOD = new ExampleWoodBlock()，会导致Block构造函数中调用BlockBehaviour.Properties.of()时，ForgeRegistries.BLOCKS尚未初始化，抛出NullPointerException。BlockItem构造函数第二个参数new Item.Properties().tab(...)中的CreativeModeTab.TAB_BUILDING_BLOCKS是原版创造模式标签页枚举值，确保你的木头出现在“建筑方块”分类下，而非默认的“杂项”。3.3 配置blockstates/example_wood.json：定义方块状态与模型映射关系{ "variants": { "axis=y": { "model": "examplemod:block/example_wood" }, "axis=z": { "model": "examplemod:block/example_wood_horizontal" }, "axis=x": { "model": "examplemod:block/example_wood_horizontal" } } }参数说明：RotatedPillarBlock有三个朝向（Y轴竖直、X/Z轴水平），需分别指定模型。example_wood对应竖直放置模型，example_wood_horizontal对应水平放置模型。文件名example_wood.json必须与RegistryObject的modId+name（即examplemod:example_wood）完全一致，否则 Forge 加载时找不到状态定义，报No model found for examplemod:example_wood。3.4 编写models/block/example_wood.json：复用原版木头纹理，避免重复制作贴图{ "parent": "block/cube_column", "textures": { "end": "examplemod:block/example_wood_top", "side": "examplemod:block/example_wood_side" } }逻辑说明：parent: "block/cube_column"继承原版柱状方块模型（如橡木原木），自动处理朝向旋转。textures中end指上下表面（如木头两端），side指四周侧面。路径examplemod:block/example_wood_top表示资源位置为src/main/resources/assets/examplemod/textures/block/example_wood_top.png——你只需提供两张 PNG 图片，其余模型逻辑由父模板完成。4. 避坑：五个让新手卡住超过 2 小时的典型问题与根治方案Forge-1.20.1 的错误信息极其反人类，报错堆栈常跨越 Minecraft、Forge、Loom 三层，且关键线索藏在日志末尾。以下是我在某跨平台系统项目中踩过的真坑，按发生频率排序：4.1 现象：gradlew runClient启动后黑屏 10 秒，控制台输出java.lang.NoClassDefFoundError: net/minecraft/client/renderer/entity/EntityRendererProvider$Context原因：build.gradle中minecraft和forge版本号不匹配。例如minecraft_version = "1.20.1"但forge_version = "47.2.0"（47.2.0 对应 1.20.0）。Forge 的EntityRendererProvider类在 47.3.0 才引入，低版本 Forge 无此符号。解决：严格使用 Forge 官网版本矩阵 查找匹配对。1.20.1 对应的首个稳定版是47.3.0，不要尝试47.0.0或47.1.0。4.2 现象：IDEA 中@Mod注解标红，提示Cannot resolve symbol 'Mod'，但gradlew build却成功原因：IDEA 未正确识别 Loom 的sourceSets。Loom 将src/main/java和src/main/resources分离为main和named两个 source set，而 IDEA 默认只加载main。@Mod在named下的net.minecraftforge.fml.common.Mod中，main下不可见。解决：在 IDEA 中依次点击File → Project Structure → Modules → Sources，将build/generated/sources/loom-remapped-mappings/main目录标记为Sources，并勾选Override compiler output path指向build/classes/java/main。4.3 现象：模组加载成功，但自定义方块在创造模式中不显示，F3 查看世界时无该方块 ID原因：mods.toml中modId与 Java 包名或RegistryObject名称不一致。例如mods.toml写modId="examplemod"，但ModBlocks.java中BLOCKS.register("example_wood", ...)的字符串是"example_wood"，而ExampleMod.MOD_ID值却是"example_mod"（含下划线）。Forge 注册时用examplemod:example_wood，但MOD_ID错误导致DeferredRegister绑定到错误命名空间。解决：统一ExampleMod.java中public static final String MOD_ID = "examplemod";，并在mods.toml和所有register()调用中严格使用该常量。4.4 现象：右键放置方块后，游戏崩溃，报java.lang.IllegalStateException: Cannot get property DirectionProperty原因：BlockState定义缺失。RotatedPillarBlock要求BlockState必须包含axis属性（DirectionProperty<Direction.Axis>），但blockstates/example_wood.json中未定义variants或multipart规则，导致 Forge 无法生成合法BlockState。解决：确认blockstates/下 JSON 文件名与RegistryObject名称完全一致（如example_wood.json），且内容包含variants或multipart字段。可用grep -r "example_wood" build/检查 Loom 是否已将该文件复制到build/resources/main/assets/examplemod/blockstates/。4.5 现象：gradlew runClient第一次成功，第二次报java.nio.file.FileSystemException: ... The process cannot access the file because it is being used by another process（Windows）原因：Windows Defender 实时保护锁定build/目录下的 JAR 文件。Gradle 在构建时生成build/libs/examplemod-1.0.0.jar，Defender 扫描该文件时加锁，导致下次构建无法删除旧文件。解决：将项目根目录添加到 Windows Defender 排除列表（设置 → 更新与安全 → Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 添加或删除排除项 → 添加文件夹），或临时关闭实时保护。5. 进阶技巧：用 Mixin 替换原版Block方法体，实现“下雨时木头自动变湿”的状态切换当Block子类无法满足需求时（如需修改原版GrassBlock的tick()行为），就必须上 Mixin——这是 Forge-1.20.1 提供的终极武器：在字节码层面直接替换方法体。它比事件监听更底层、更高效，但也更危险。下面以“让自定义木头在雨天变为湿润状态（example_wood_wet）”为例，展示从 Mixin 注入到状态持久化的完整链路。5.1 配置src/main/resources/META-INF/mods.toml：启用 Mixin 并声明配置文件# 在 [[mods]] 块末尾追加 [[mixins]] config="examplemod.mixins.json"5.2 创建src/main/resources/examplemod.mixins.json：定义 Mixin 类与目标类映射{ "required": true, "minVersion": "0.8", "package": "com.examplemod.mixin", "compatibilityLevel": "JAVA_17", "mixins": [ "BlockMixin" ], "client": [ ], "server": [ ] }5.3 编写src/main/java/com/examplemod/mixin/BlockMixin.java：注入tick()方法，检查雨天并切换状态package com.examplemod.mixin; import com.examplemod.block.ExampleWoodBlock; import net.minecraft.core.BlockPos; import net.minecraft.world.level.Level; import net.minecraft.world.level.block.Block; import net.minecraft.world.level.block.state.BlockState; import net.minecraft.world.level.material.FluidState; import org.spongepowered.asm.mixin.Mixin; import org.spongepowered.asm.mixin.injection.At; import org.spongepowered.asm.mixin.injection.Inject; import org.spongepowered.asm.mixin.injection.callback.CallbackInfo; @Mixin(Block.class) public abstract class BlockMixin { @Inject(method = "tick", at = @At("HEAD"), cancellable = true) private void onTick(BlockState state, Level level, BlockPos pos, net.minecraft.util.RandomSource random, CallbackInfo ci) { // 仅对自定义木头生效 if (state.getBlock() instanceof ExampleWoodBlock) { // 检查是否在雨中：level.isRaining() + pos 在天空下 if (level.isRaining() && level.canSeeSky(pos.above())) { // 获取湿润版本的 BlockState（需提前在 ExampleWoodBlock 中定义） BlockState wetState = state.setValue(ExampleWoodBlock.WET, true); level.setBlock(pos, wetState, 3); // 3 = UPDATE_CLIENTS | UPDATE_NEIGHBORS ci.cancel(); // 取消原版 tick 逻辑 } } } }参数说明：@Inject(method = "tick", at = @At("HEAD"))表示在Block.tick()方法开头插入代码；cancellable = true允许调用ci.cancel()终止原方法执行；level.setBlock(pos, wetState, 3)中3是更新标志位（Block.UPDATE_CLIENTS | Block.UPDATE_NEIGHBORS），确保客户端同步状态变化。关键点在于ExampleWoodBlock.WET——这是一个自定义BooleanProperty，必须在ExampleWoodBlock类中声明并注册到BlockState。5.4 在ExampleWoodBlock.java中定义WET属性并重写createBlockStateDefinitionpublic class ExampleWoodBlock extends RotatedPillarBlock { // 新增布尔属性：wet（湿润） public static final BooleanProperty WET = BooleanProperty.create("wet"); public ExampleWoodBlock() { super(BlockBehaviour.Properties.of() .mapColor(MapColor.WOOD) .strength(2.0F, 3.0F) .sound(net.minecraft.sounds.SoundType.WOOD) .ignitedByLava()); // 设置默认状态：初始为干燥 this.registerDefaultState(this.stateDefinition.any().setValue(AXIS, Direction.Axis.Y).setValue(WET, false)); } @Override protected void createBlockStateDefinition(StateDefinition.Builder<Block, BlockState> builder) { // 同时注册 AXIS 和 WET 两个属性 builder.add(AXIS, WET); } }逻辑说明：StateDefinition是BlockState的元数据容器。builder.add(AXIS, WET)告诉 Forge 该方块有两种状态维度：朝向（AXIS）和湿润度（WET）。registerDefaultState()中setValue(WET, false)设定默认为干燥，这样新放置的木头不会直接变湿。setValue(AXIS, Direction.Axis.Y)是RotatedPillarBlock的必需初始化，否则BlockState构造失败。5.5 验证 Mixin 是否生效：用F3 + H开启高级提示，观察方块状态启动游戏后，在雨天放置example_wood，按F3 + H打开高级提示，鼠标悬停方块，状态栏会显示类似examplemod:example_wood[wet=true, axis=y]。若显示wet=false，说明 Mixin 未触发；若显示wet=true但方块外观未变，则需检查blockstates/example_wood.json是否为wet=true状态定义了独立模型（如"wet=true": { "model": "examplemod:block/example_wood_wet" }）。此时你已掌握 Forge 最深的控制层——不是“添加功能”，而是“重写规则”。从那以后我每次写 Mixin，都强制走一遍gradlew clean && gradlew build --no-daemon，再用javap -c build/classes/java/main/com/examplemod/mixin/BlockMixin.class反编译确认字节码注入点是否真实存在。因为 Mixin 的错误不会在编译时报出，而是在运行时静默失效——那是比ClassNotFoundException更可怕的黑匣子。希望帮到你。本文还有配套的精品资源，点击获取