简介本资源是专为Minecraft模组开发者提供的Forge 1.20.1官方MDKMod Development Kit开发套件适用于Java基础扎实、希望基于Minecraft 1.20.1版本进行模组开发的中高级学习者与实践者。包内共17个文件涵盖构建核心gradlew.bat/gradlew、build.gradle、settings.gradle、环境配置gradle.properties、gradle-wrapper.jar、版本管理.gitignore、.gitattributes、法律与协作信息LICENSE.txt、CREDITS.txt、changelog.txt及基础项目结构src/main/java、src/main/resources完整复现标准Forge模组工程骨架。压缩包仅111KB轻量但功能完备便于快速初始化、调试与二次开发。目前已有1506人学习下载读者可直接导入IDE使用获得开箱即用的Gradle构建流程、清晰的源码组织规范、版本兼容性说明及社区授权依据是入门Forge开发与适配1.20.1生态不可或缺的起点资源。1. 这不是 Minecraft 启动器而是你本地模组开发环境的「编译开关」Forge 1.20.1 是一套可复现、可调试、可打包的 Java 构建时态系统专为需要修改游戏底层逻辑如物品合成规则、生物行为树、网络同步协议的开发者设计。它不提供开箱即用的“一键安装模组”功能也不替代客户端启动流程它的核心价值在于把minecraft-server.jar和client.jar的符号表、混淆映射、Gradle 插件链、SRG→MCP→Yarn 的三段式重映射管道全部固化进一个可版本锁定的工程骨架里。如果你正卡在「改了代码但热重载不生效」「打出来的 jar 在服务器报 NoClassDefFoundError」「想看 EntityLivingBase#onUpdate 的原始调用栈却只有 a.b.c.d 方法名」——那 Forge 1.20.1 就是你必须亲手搭起来的反混淆沙盒。它适合两类人一是高校某实验室做游戏 AI 行为仿真时需深度 hook 实体 tick 的研究生二是某公司内部工具链中需将 Minecraft 作为三维可视化底座、要求稳定对接自研物理引擎的工程师。2. 搭建 Forge 1.20.1 开发环境从空白目录到可断点调试的 client 工程Forge 1.20.1 不是传统意义上的“软件包”而是一套基于 Gradle 的构建时态系统。它不提供.exe或.dmg安装程序所有能力都藏在build.gradle、gradle.properties和src/目录结构里。这意味着你无法“双击运行 Forge”但可以精确控制每一个字节如何被注入到 Minecraft 的类加载器中。本章带你从零初始化一个可立即下断点、可修改PlayerEntity构造函数、可观察NetworkEvent分发全过程的 client 工程。2.1 初始化工程用官方模板生成可编译骨架Forge 官方已弃用旧版forge-1.20.1-installer.jar图形向导当前唯一受支持的初始化方式是通过gradle init 官方脚本模板。注意不要手动下载 forge-1.20.1.zip 解压后改名使用——该压缩包不含 Gradle Wrapper、缺失gradlew.bat、缺少gradle/wrapper/gradle-wrapper.properties中对 JDK 17 的显式约束会导致后续runClient报Unsupported class file major version 61。执行以下命令确保已安装 JDK 17非 JDK 21 或 JDK 8# 创建空目录并进入 mkdir my-forge-mod cd my-forge-mod # 使用 Forge 官方推荐的初始化脚本2023 年后维护 curl -O https://raw.githubusercontent.com/MinecraftForge/Documentation/main/docs/gettingstarted/gradle_init.sh chmod x gradle_init.sh ./gradle_init.sh --mc-version 1.20.1 --mcp-channel official --mcp-version 20230612.120549提示--mcp-channel official表示使用 Mojang 官方发布的命名映射即 MCP而非社区维护的 Yarn 映射。对于 1.20.1official是唯一能保证net.minecraft.world.level.block.Blocks等核心类名与 Mojang 发布的client.jar符号完全对齐的通道。若选yarn你将面对net/minecraft/class_2248这类混淆名调试成本陡增 3 倍以上。该脚本会生成标准 Gradle 结构build.gradle声明minecraft、forge、java插件及依赖坐标gradle.properties预设org.gradle.java.home指向 JDK 17 路径若未设后续runClient必失败src/main/java/主代码入口含默认ModClasssrc/main/resources/META-INF/mods.toml模组元信息决定是否出现在 Mods 列表、是否启用自动更新检查2.2 配置 JDK 与 Gradle 版本两个必须硬编码的参数Forge 1.20.1 强制要求 JDK 17具体为 17.0.2且 Gradle 版本必须为 8.1非 8.0、非 8.2。这两个参数若不显式锁定CI 构建或换机器后极易翻车。打开gradle/wrapper/gradle-wrapper.properties确认内容为distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.1-bin.zip networkTimeout10000 validateDistributionUrltrue zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists打开gradle.properties补全 JDK 路径Windows 用户注意路径分隔符# Linux/macOS 示例 org.gradle.java.home/usr/lib/jvm/java-17-openjdk-amd64 # Windows 示例路径含空格必须加引号 org.gradle.java.homeC:\\Program Files\\Eclipse Adoptium\\jdk-17.0.28-hotspot逻辑说明org.gradle.java.home不是建议值而是强制覆盖项。Gradle 启动时若检测到 JAVA_HOME 指向 JDK 21会直接拒绝执行runClient报错Java version is not compatible。此参数确保无论系统环境如何构建始终使用 JDK 17。2.3 编写第一个可调试模组注册自定义物品并打断点验证初始化完成后我们写一个最简模组注册一把名为debug_sword的剑其攻击时在控制台打印当前玩家坐标。重点在于让这行System.out.println可被 IDE 断点命中并看到player.getX()返回的真实 double 值。在src/main/java/com/example/myforge/MyForgeMod.java中写入package com.example.myforge; import net.minecraft.world.item.Item; import net.minecraft.world.item.SwordItem; import net.minecraft.world.item.Tier; import net.minecraft.world.item.Tiers; import net.minecraft.world.level.Level; import net.minecraftforge.common.MinecraftForge; import net.minecraftforge.event.entity.player.PlayerEvent; import net.minecraftforge.eventbus.api.IEventBus; import net.minecraftforge.fml.common.Mod; import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext; import net.minecraftforge.registries.DeferredRegister; import net.minecraftforge.registries.ForgeRegistries; import net.minecraftforge.registries.RegistryObject; Mod(myforge) public class MyForgeMod { public static final String MODID myforge; // 延迟注册物品 private static final DeferredRegisterItem ITEMS DeferredRegister.create(ForgeRegistries.ITEMS, MODID); // 定义物品对象非实例化 public static final RegistryObjectItem DEBUG_SWORD ITEMS.register(debug_sword, () - new SwordItem(Tiers.IRON, 3, -2.4F, new Item.Properties()) ); public MyForgeMod() { IEventBus modEventBus FMLJavaModLoadingContext.get().getModEventBus(); ITEMS.register(modEventBus); // 注册到事件总线 // 监听玩家攻击事件 MinecraftForge.EVENT_BUS.addListener(this::onPlayerAttack); } // 关键此处必须能下断点 private void onPlayerAttack(PlayerEvent.AttackEntityEvent event) { if (event.getEntity().getMainHandItem().is(DEBUG_SWORD.get())) { Level level event.getEntity().level(); System.out.printf([DEBUG] Player %s attacked at (%.2f, %.2f, %.2f)%n, event.getEntity().getName().getString(), event.getEntity().getX(), event.getEntity().getY(), event.getEntity().getZ() ); } } }参数说明Tiers.IRON复用原版铁质武器属性避免自定义 Tier 导致SwordItem构造失败-2.4F攻击速度修正值与原版铁剑一致防止动作异常DEBUG_SWORD.get().get()是获取实际实例的唯一安全方式直接用DEBUG_SWORD是RegistryObject对象无is()方法event.getEntity().level()必须用此方式获取 Levelevent.getLevel()在 1.20.1 中已被移除2.4 启动 client 并验证断点runClient的真实含义执行以下命令启动带调试能力的 Minecraft 客户端./gradlew runClient首次执行会触发下载minecraft-1.20.1-client.jar约 12MB下载forge-1.20.1-47.2.0_mapped_official_1.20.1.jar含 SRG→MCP 映射的库编译src/main/java下所有类启动 Minecraft自动加载myforge模组无需手动拖入 mods 文件夹此时打开 IntelliJ IDEA打开该目录File → Open → 选择my-forge-mod在onPlayerAttack方法第一行打上断点点击右上角Debug runClient需先配置好 Gradle 运行配置JDK 自动识别为gradle.properties中指定路径进入游戏手持debug_sword指令/give p myforge:debug_sword攻击任意实体你会看到断点被精准命中event.getEntity().getX()显示真实坐标值如124.375而非0.0或NaN。这证明✅ 类加载器已正确注入 Forge 的Transformers✅ MCP 映射已生效PlayerEntity的字段名与源码一致✅ 事件总线未被 Mojang 的新网络层拦截血泪经验若断点不命中请立即检查build.gradle中minecraft块是否含mappings channel: official。曾有开发者误用parchment映射导致PlayerEvent.AttackEntityEvent类根本不存在编译通过但运行时报ClassNotFoundException。3. 模组资源绑定与 assets 加载为什么你的 textures 不显示、lang 不生效Forge 1.20.1 的资源加载机制与原版高度解耦但又强依赖resources目录下的固定结构。很多新手卡在「明明写了assets/myforge/textures/item/debug_sword.png游戏里却显示紫黑方块」本质是没理解 Forge 的IResourcePack加载顺序和ResourceLocation解析规则。本章直击 assets 绑定的三个关键层文件路径规范、JSON 元数据声明、语言文件加载时机。3.1 assets 目录结构必须严格遵循assets/modid/三级嵌套Forge 不会扫描整个resources目录它只认resources/assets/modid/下的子目录。modid必须与mods.toml中modId字段完全一致区分大小写且不能含下划线以外的符号。正确结构示例以myforge为例src/main/resources/ ├── assets/ │ └── myforge/ ← 必须与 mods.toml 中 modId 一致 │ ├── models/ │ │ └── item/ │ │ └── debug_sword.json │ ├── textures/ │ │ └── item/ │ │ └── debug_sword.png │ └── lang/ │ └── en_us.json ├── data/ │ └── myforge/ │ └── recipes/ │ └── debug_sword.json └── META-INF/mods.toml注意textures/item/debug_sword.png的父目录必须是item/不能是items/或tool/。Forge 的TextureAtlas默认只扫描textures/item/、textures/block/、textures/entity/三个路径。放错位置 资源不可见。3.2 item 模型 JSONparent字段必须指向原版模型且textures键名要匹配assets/myforge/models/item/debug_sword.json内容如下{ parent: item/handheld, textures: { layer0: myforge:item/debug_sword } }关键点解析parent: item/handheld继承原版手持物品基础模型含旋转动画、光照响应。若写成minecraft:item/handheld会报Parent model not found因为 Forge 的ModelBakery默认 namespace 是minecraft前缀可省略。layer0这是ItemRenderer渲染时查找纹理的固定键名。不能写成texture或base否则纹理不绑定。myforge:item/debug_swordmyforge:是 namespaceitem/是子目录debug_sword是文件名不含.png。此字符串必须与textures/item/debug_sword.png的路径完全对应。3.3 语言文件 en_us.json键名格式必须为item.modid.name且值不能为空字符串assets/myforge/lang/en_us.json内容{ item.myforge.debug_sword: Debug Sword, item.myforge.debug_sword.desc: A sword for debugging coordinates. }⚠️ 严格规则键名必须以item.开头后接modid.name中间用英文点连接name必须与RegistryObject注册时传入的字符串完全一致即debug_sword非DebugSword或debug-sword值不能为空字符串否则游戏内显示为item.myforge.debug_sword原始键名紫字排查技巧若语言不生效在游戏中按F3 T重载资源包然后打开日志logs/latest.log搜索Failed to load language。常见原因是 JSON 语法错误多逗号、少引号或键名大小写不匹配。3.4 验证资源加载用/reload和 F3H 查看实时渲染状态启动runClient后执行以下操作验证资源是否就位按T打开聊天框输入/reload—— 此命令会重新加载所有 assets包括 textures、models、lang按F3 H开启高级提示将鼠标悬停在物品栏的debug_sword上查看 Tooltip 是否显示Debug Sword而非item.myforge.debug_sword按F3 Q打开资源包列表确认myforge出现在Active Resource Packs中且状态为Enabled若F3H显示Missing Model说明models/item/debug_sword.json路径或内容有误若 Tooltip 显示原始键名说明en_us.json未被加载或键名错误。玄学排查法删除build/resources/main/assets/myforge/全部内容仅保留lang/en_us.json再执行/reload。若 Tooltip 突然显示正确则证明models或textures路径存在硬编码错误需逐级检查assets/myforge/下的每一层目录名拼写。4. 常见问题排查五个让 90% 新手停更一周的硬核坑Forge 1.20.1 的报错信息极其隐晦同一现象可能由完全不同的底层原因导致。以下是我在某跨平台系统项目中实测整理的五大高频翻车点每条均按「现象 → 原因 → 解决」结构给出可立即执行的验证步骤。4.1 现象runClient启动后黑屏 5 秒控制台输出java.lang.NoClassDefFoundError: net/minecraft/client/renderer/entity/EntityRendererProvider$Context原因build.gradle中minecraft块未声明mappings channel: official导致EntityRendererProvider类被映射为不存在的混淆名如class_892而forge-1.20.1-47.2.0_mapped_official_1.20.1.jar期望的是EntityRendererProvider这个明文类名。解决打开build.gradle找到minecraft块确认含以下两行mappings channel: official, version: 1.20.1 accessTransformer file(src/main/resources/META-INF/accesstransformer.cfg)执行./gradlew --refresh-dependencies清理缓存后重试。4.2 现象IDEA 中PlayerEvent.AttackEntityEvent类标红提示Cannot resolve symbol AttackEntityEvent但./gradlew compileJava却能通过原因IntelliJ 未正确识别minecraft插件生成的sourceSets导致src/main/java无法关联到forge-1.20.1-47.2.0_mapped_official_1.20.1-sources.jar源码包。解决在 IDEA 中依次点击File → Project Structure → Modules → myforge → Sources确认src/main/java和src/main/resources已标记为Sources和Resources然后点击Dependencies标签页找到forge-1.20.1-47.2.0_mapped_official_1.20.1点击右侧Download sources图标云朵向下箭头。4.3 现象/give p myforge:debug_sword成功但物品栏显示为紫黑方块F3H 提示Missing Model原因assets/myforge/models/item/debug_sword.json中layer0对应的纹理路径myforge:item/debug_sword与实际 PNG 文件路径不匹配。常见错误包括PNG 文件名是debug_sword.png但 JSON 写成myforge:item/debug_sword.png多写了.png或 PNG 放在textures/items/多了一个s。解决在runClient控制台中搜索TextureAtlas关键字找到类似Failed to load texture: myforge:item/debug_sword的日志根据日志中的路径严格比对resources/assets/myforge/textures/下的实际文件路径。4.4 现象onPlayerAttack断点命中但event.getEntity().getMainHandItem().is(DEBUG_SWORD.get())始终返回false原因DEBUG_SWORD.get()获取的是注册后的Item实例但event.getEntity().getMainHandItem()返回的是ItemStack其内部item字段是Item的另一个实例因 Forge 的ItemRegistry未正确注入。根本原因是mods.toml中modId与DeferredRegister.create(..., MODID)的第二个参数不一致。解决打开mods.toml确认modIdmyforge打开MyForgeMod.java确认DeferredRegister.create(ForgeRegistries.ITEMS, MODID)中MODID值为myforge非MyForge或MYFORGE执行./gradlew clean彻底清除旧 class 后重试。4.5 现象添加SubscribeEvent方法后runClient报java.lang.IllegalStateException: Event bus is not initialized原因SubscribeEvent注解的方法必须注册到MinecraftForge.EVENT_BUS但MyForgeMod构造函数中MinecraftForge.EVENT_BUS.addListener(...)被放在ITEMS.register(modEventBus)之后而modEventBus的初始化依赖于FMLJavaModLoadingContext.get().getModEventBus()二者异步时序错乱。解决将事件监听器注册移到modEventBus注册之后且必须在super()调用后若存在父类。标准写法public MyForgeMod() { IEventBus modEventBus FMLJavaModLoadingContext.get().getModEventBus(); ITEMS.register(modEventBus); // ✅ 必须在此之后注册事件监听器 MinecraftForge.EVENT_BUS.addListener(this::onPlayerAttack); }5. 模组打包与发布生成可在任意 Forge 1.20.1 环境运行的 .jar 文件./gradlew build生成的build/libs/myforge-1.0.0.jar不能直接扔进mods/文件夹运行——它缺少META-INF/MANIFEST.MF中的关键属性、未嵌入mods.toml、且未剥离开发期依赖如slf4j-api。真正的发布包必须通过./gradlew jarreobfJar流程生成本章详解每一步的不可替代性。5.1 执行标准打包流程jar→reobfJar→remapJarForge 1.20.1 的发布包生成是三阶段流水线缺一不可# 第一阶段生成原始 jar含编译后 class resources ./gradlew jar # 第二阶段重映射将 MCP 名称转为 Mojang 官方混淆名供服务器加载 ./gradlew reobfJar # 第三阶段重映射为客户端可用名将 MCP 名称转为人类可读名供 client 加载 ./gradlew remapJar执行完毕后目标文件位于build/libs/myforge-1.0.0-1.20.1.jar←这才是可发布的最终包build/libs/myforge-1.0.0-1.20.1-sources.jar← 源码包供其他开发者引用逻辑说明reobfJar输出的 jar 是给 Minecraft 服务端用的服务端运行时使用 Mojang 混淆名remapJar输出的 jar 是给客户端用的客户端需人类可读名以支持资源绑定。两者内容相同仅 class 文件内的方法名、字段名不同。build/libs/myforge-1.0.0.jar是开发期产物无任何映射仅用于 IDE 调试。5.2 验证发布包完整性检查 MANIFEST.MF 与 mods.toml 是否嵌入用jar -tf build/libs/myforge-1.0.0-1.20.1.jar查看包内文件列表必须包含META-INF/ META-INF/MANIFEST.MF META-INF/mods.toml com/example/myforge/MyForgeMod.class assets/myforge/models/item/debug_sword.json assets/myforge/lang/en_us.json特别检查META-INF/MANIFEST.MF内容用jar -xf解压后查看Manifest-Version: 1.0 Mod-Tags: forge Mod-Display-Name: MyForge Mod Mod-Description: A debug mod for coordinate logging. Mod-Authors: dev-team Mod-Id: myforge Mod-Version: 1.0.0关键点Mod-Id必须与mods.toml中一致Mod-Display-Name会显示在 Mods 列表中若缺失Mod-IdForge 启动时会直接跳过该 jar不报错也不加载。5.3 在纯净 Forge 环境中测试脱离runClient的终极验证将build/libs/myforge-1.0.0-1.20.1.jar复制到一个全新安装的 Forge 1.20.1 客户端的mods/目录下确保该客户端未运行过runClient然后启动。验证步骤启动后进入主菜单点击Mods→ 搜索myforge确认状态为Loaded创建新世界按T输入/give p myforge:debug_sword确认物品栏出现带纹理的剑攻击猪观察聊天框是否输出[DEBUG] Player ... at (x, y, z)按F3 T重载资源确认纹理和语言未丢失若第 1 步未显示myforge说明mods.toml未正确嵌入或Mod-Id不匹配若第 2 步物品无纹理说明remapJar未执行或assets路径错误若第 3 步无输出说明EVENT_BUS未在发布包中正确注册需检查MyForgeMod构造函数是否被Mod注解正确触发。从那以后我每次提交 release 包前都强制走一遍「新建 Forge 客户端 → 拖入 jar → 启动 → /give → 攻击 → 截图日志」全流程。不是信不过 Gradle而是信不过自己某次手抖删掉的reobfJar任务。希望帮到你。本文还有配套的精品资源点击获取
简介本资源是专为Minecraft模组开发者提供的Forge 1.20.1官方MDKMod Development Kit开发套件适用于Java基础扎实、希望基于Minecraft 1.20.1版本进行模组开发的中高级学习者与实践者。包内共17个文件涵盖构建核心gradlew.bat/gradlew、build.gradle、settings.gradle、环境配置gradle.properties、gradle-wrapper.jar、版本管理.gitignore、.gitattributes、法律与协作信息LICENSE.txt、CREDITS.txt、changelog.txt及基础项目结构src/main/java、src/main/resources完整复现标准Forge模组工程骨架。压缩包仅111KB轻量但功能完备便于快速初始化、调试与二次开发。目前已有1506人学习下载读者可直接导入IDE使用获得开箱即用的Gradle构建流程、清晰的源码组织规范、版本兼容性说明及社区授权依据是入门Forge开发与适配1.20.1生态不可或缺的起点资源。1. 这不是 Minecraft 启动器而是你本地模组开发环境的「编译开关」Forge 1.20.1 是一套可复现、可调试、可打包的 Java 构建时态系统专为需要修改游戏底层逻辑如物品合成规则、生物行为树、网络同步协议的开发者设计。它不提供开箱即用的“一键安装模组”功能也不替代客户端启动流程它的核心价值在于把minecraft-server.jar和client.jar的符号表、混淆映射、Gradle 插件链、SRG→MCP→Yarn 的三段式重映射管道全部固化进一个可版本锁定的工程骨架里。如果你正卡在「改了代码但热重载不生效」「打出来的 jar 在服务器报 NoClassDefFoundError」「想看 EntityLivingBase#onUpdate 的原始调用栈却只有 a.b.c.d 方法名」——那 Forge 1.20.1 就是你必须亲手搭起来的反混淆沙盒。它适合两类人一是高校某实验室做游戏 AI 行为仿真时需深度 hook 实体 tick 的研究生二是某公司内部工具链中需将 Minecraft 作为三维可视化底座、要求稳定对接自研物理引擎的工程师。2. 搭建 Forge 1.20.1 开发环境从空白目录到可断点调试的 client 工程Forge 1.20.1 不是传统意义上的“软件包”而是一套基于 Gradle 的构建时态系统。它不提供.exe或.dmg安装程序所有能力都藏在build.gradle、gradle.properties和src/目录结构里。这意味着你无法“双击运行 Forge”但可以精确控制每一个字节如何被注入到 Minecraft 的类加载器中。本章带你从零初始化一个可立即下断点、可修改PlayerEntity构造函数、可观察NetworkEvent分发全过程的 client 工程。2.1 初始化工程用官方模板生成可编译骨架Forge 官方已弃用旧版forge-1.20.1-installer.jar图形向导当前唯一受支持的初始化方式是通过gradle init 官方脚本模板。注意不要手动下载 forge-1.20.1.zip 解压后改名使用——该压缩包不含 Gradle Wrapper、缺失gradlew.bat、缺少gradle/wrapper/gradle-wrapper.properties中对 JDK 17 的显式约束会导致后续runClient报Unsupported class file major version 61。执行以下命令确保已安装 JDK 17非 JDK 21 或 JDK 8# 创建空目录并进入 mkdir my-forge-mod cd my-forge-mod # 使用 Forge 官方推荐的初始化脚本2023 年后维护 curl -O https://raw.githubusercontent.com/MinecraftForge/Documentation/main/docs/gettingstarted/gradle_init.sh chmod x gradle_init.sh ./gradle_init.sh --mc-version 1.20.1 --mcp-channel official --mcp-version 20230612.120549提示--mcp-channel official表示使用 Mojang 官方发布的命名映射即 MCP而非社区维护的 Yarn 映射。对于 1.20.1official是唯一能保证net.minecraft.world.level.block.Blocks等核心类名与 Mojang 发布的client.jar符号完全对齐的通道。若选yarn你将面对net/minecraft/class_2248这类混淆名调试成本陡增 3 倍以上。该脚本会生成标准 Gradle 结构build.gradle声明minecraft、forge、java插件及依赖坐标gradle.properties预设org.gradle.java.home指向 JDK 17 路径若未设后续runClient必失败src/main/java/主代码入口含默认ModClasssrc/main/resources/META-INF/mods.toml模组元信息决定是否出现在 Mods 列表、是否启用自动更新检查2.2 配置 JDK 与 Gradle 版本两个必须硬编码的参数Forge 1.20.1 强制要求 JDK 17具体为 17.0.2且 Gradle 版本必须为 8.1非 8.0、非 8.2。这两个参数若不显式锁定CI 构建或换机器后极易翻车。打开gradle/wrapper/gradle-wrapper.properties确认内容为distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.1-bin.zip networkTimeout10000 validateDistributionUrltrue zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists打开gradle.properties补全 JDK 路径Windows 用户注意路径分隔符# Linux/macOS 示例 org.gradle.java.home/usr/lib/jvm/java-17-openjdk-amd64 # Windows 示例路径含空格必须加引号 org.gradle.java.homeC:\\Program Files\\Eclipse Adoptium\\jdk-17.0.28-hotspot逻辑说明org.gradle.java.home不是建议值而是强制覆盖项。Gradle 启动时若检测到 JAVA_HOME 指向 JDK 21会直接拒绝执行runClient报错Java version is not compatible。此参数确保无论系统环境如何构建始终使用 JDK 17。2.3 编写第一个可调试模组注册自定义物品并打断点验证初始化完成后我们写一个最简模组注册一把名为debug_sword的剑其攻击时在控制台打印当前玩家坐标。重点在于让这行System.out.println可被 IDE 断点命中并看到player.getX()返回的真实 double 值。在src/main/java/com/example/myforge/MyForgeMod.java中写入package com.example.myforge; import net.minecraft.world.item.Item; import net.minecraft.world.item.SwordItem; import net.minecraft.world.item.Tier; import net.minecraft.world.item.Tiers; import net.minecraft.world.level.Level; import net.minecraftforge.common.MinecraftForge; import net.minecraftforge.event.entity.player.PlayerEvent; import net.minecraftforge.eventbus.api.IEventBus; import net.minecraftforge.fml.common.Mod; import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext; import net.minecraftforge.registries.DeferredRegister; import net.minecraftforge.registries.ForgeRegistries; import net.minecraftforge.registries.RegistryObject; Mod(myforge) public class MyForgeMod { public static final String MODID myforge; // 延迟注册物品 private static final DeferredRegisterItem ITEMS DeferredRegister.create(ForgeRegistries.ITEMS, MODID); // 定义物品对象非实例化 public static final RegistryObjectItem DEBUG_SWORD ITEMS.register(debug_sword, () - new SwordItem(Tiers.IRON, 3, -2.4F, new Item.Properties()) ); public MyForgeMod() { IEventBus modEventBus FMLJavaModLoadingContext.get().getModEventBus(); ITEMS.register(modEventBus); // 注册到事件总线 // 监听玩家攻击事件 MinecraftForge.EVENT_BUS.addListener(this::onPlayerAttack); } // 关键此处必须能下断点 private void onPlayerAttack(PlayerEvent.AttackEntityEvent event) { if (event.getEntity().getMainHandItem().is(DEBUG_SWORD.get())) { Level level event.getEntity().level(); System.out.printf([DEBUG] Player %s attacked at (%.2f, %.2f, %.2f)%n, event.getEntity().getName().getString(), event.getEntity().getX(), event.getEntity().getY(), event.getEntity().getZ() ); } } }参数说明Tiers.IRON复用原版铁质武器属性避免自定义 Tier 导致SwordItem构造失败-2.4F攻击速度修正值与原版铁剑一致防止动作异常DEBUG_SWORD.get().get()是获取实际实例的唯一安全方式直接用DEBUG_SWORD是RegistryObject对象无is()方法event.getEntity().level()必须用此方式获取 Levelevent.getLevel()在 1.20.1 中已被移除2.4 启动 client 并验证断点runClient的真实含义执行以下命令启动带调试能力的 Minecraft 客户端./gradlew runClient首次执行会触发下载minecraft-1.20.1-client.jar约 12MB下载forge-1.20.1-47.2.0_mapped_official_1.20.1.jar含 SRG→MCP 映射的库编译src/main/java下所有类启动 Minecraft自动加载myforge模组无需手动拖入 mods 文件夹此时打开 IntelliJ IDEA打开该目录File → Open → 选择my-forge-mod在onPlayerAttack方法第一行打上断点点击右上角Debug runClient需先配置好 Gradle 运行配置JDK 自动识别为gradle.properties中指定路径进入游戏手持debug_sword指令/give p myforge:debug_sword攻击任意实体你会看到断点被精准命中event.getEntity().getX()显示真实坐标值如124.375而非0.0或NaN。这证明✅ 类加载器已正确注入 Forge 的Transformers✅ MCP 映射已生效PlayerEntity的字段名与源码一致✅ 事件总线未被 Mojang 的新网络层拦截血泪经验若断点不命中请立即检查build.gradle中minecraft块是否含mappings channel: official。曾有开发者误用parchment映射导致PlayerEvent.AttackEntityEvent类根本不存在编译通过但运行时报ClassNotFoundException。3. 模组资源绑定与 assets 加载为什么你的 textures 不显示、lang 不生效Forge 1.20.1 的资源加载机制与原版高度解耦但又强依赖resources目录下的固定结构。很多新手卡在「明明写了assets/myforge/textures/item/debug_sword.png游戏里却显示紫黑方块」本质是没理解 Forge 的IResourcePack加载顺序和ResourceLocation解析规则。本章直击 assets 绑定的三个关键层文件路径规范、JSON 元数据声明、语言文件加载时机。3.1 assets 目录结构必须严格遵循assets/modid/三级嵌套Forge 不会扫描整个resources目录它只认resources/assets/modid/下的子目录。modid必须与mods.toml中modId字段完全一致区分大小写且不能含下划线以外的符号。正确结构示例以myforge为例src/main/resources/ ├── assets/ │ └── myforge/ ← 必须与 mods.toml 中 modId 一致 │ ├── models/ │ │ └── item/ │ │ └── debug_sword.json │ ├── textures/ │ │ └── item/ │ │ └── debug_sword.png │ └── lang/ │ └── en_us.json ├── data/ │ └── myforge/ │ └── recipes/ │ └── debug_sword.json └── META-INF/mods.toml注意textures/item/debug_sword.png的父目录必须是item/不能是items/或tool/。Forge 的TextureAtlas默认只扫描textures/item/、textures/block/、textures/entity/三个路径。放错位置 资源不可见。3.2 item 模型 JSONparent字段必须指向原版模型且textures键名要匹配assets/myforge/models/item/debug_sword.json内容如下{ parent: item/handheld, textures: { layer0: myforge:item/debug_sword } }关键点解析parent: item/handheld继承原版手持物品基础模型含旋转动画、光照响应。若写成minecraft:item/handheld会报Parent model not found因为 Forge 的ModelBakery默认 namespace 是minecraft前缀可省略。layer0这是ItemRenderer渲染时查找纹理的固定键名。不能写成texture或base否则纹理不绑定。myforge:item/debug_swordmyforge:是 namespaceitem/是子目录debug_sword是文件名不含.png。此字符串必须与textures/item/debug_sword.png的路径完全对应。3.3 语言文件 en_us.json键名格式必须为item.modid.name且值不能为空字符串assets/myforge/lang/en_us.json内容{ item.myforge.debug_sword: Debug Sword, item.myforge.debug_sword.desc: A sword for debugging coordinates. }⚠️ 严格规则键名必须以item.开头后接modid.name中间用英文点连接name必须与RegistryObject注册时传入的字符串完全一致即debug_sword非DebugSword或debug-sword值不能为空字符串否则游戏内显示为item.myforge.debug_sword原始键名紫字排查技巧若语言不生效在游戏中按F3 T重载资源包然后打开日志logs/latest.log搜索Failed to load language。常见原因是 JSON 语法错误多逗号、少引号或键名大小写不匹配。3.4 验证资源加载用/reload和 F3H 查看实时渲染状态启动runClient后执行以下操作验证资源是否就位按T打开聊天框输入/reload—— 此命令会重新加载所有 assets包括 textures、models、lang按F3 H开启高级提示将鼠标悬停在物品栏的debug_sword上查看 Tooltip 是否显示Debug Sword而非item.myforge.debug_sword按F3 Q打开资源包列表确认myforge出现在Active Resource Packs中且状态为Enabled若F3H显示Missing Model说明models/item/debug_sword.json路径或内容有误若 Tooltip 显示原始键名说明en_us.json未被加载或键名错误。玄学排查法删除build/resources/main/assets/myforge/全部内容仅保留lang/en_us.json再执行/reload。若 Tooltip 突然显示正确则证明models或textures路径存在硬编码错误需逐级检查assets/myforge/下的每一层目录名拼写。4. 常见问题排查五个让 90% 新手停更一周的硬核坑Forge 1.20.1 的报错信息极其隐晦同一现象可能由完全不同的底层原因导致。以下是我在某跨平台系统项目中实测整理的五大高频翻车点每条均按「现象 → 原因 → 解决」结构给出可立即执行的验证步骤。4.1 现象runClient启动后黑屏 5 秒控制台输出java.lang.NoClassDefFoundError: net/minecraft/client/renderer/entity/EntityRendererProvider$Context原因build.gradle中minecraft块未声明mappings channel: official导致EntityRendererProvider类被映射为不存在的混淆名如class_892而forge-1.20.1-47.2.0_mapped_official_1.20.1.jar期望的是EntityRendererProvider这个明文类名。解决打开build.gradle找到minecraft块确认含以下两行mappings channel: official, version: 1.20.1 accessTransformer file(src/main/resources/META-INF/accesstransformer.cfg)执行./gradlew --refresh-dependencies清理缓存后重试。4.2 现象IDEA 中PlayerEvent.AttackEntityEvent类标红提示Cannot resolve symbol AttackEntityEvent但./gradlew compileJava却能通过原因IntelliJ 未正确识别minecraft插件生成的sourceSets导致src/main/java无法关联到forge-1.20.1-47.2.0_mapped_official_1.20.1-sources.jar源码包。解决在 IDEA 中依次点击File → Project Structure → Modules → myforge → Sources确认src/main/java和src/main/resources已标记为Sources和Resources然后点击Dependencies标签页找到forge-1.20.1-47.2.0_mapped_official_1.20.1点击右侧Download sources图标云朵向下箭头。4.3 现象/give p myforge:debug_sword成功但物品栏显示为紫黑方块F3H 提示Missing Model原因assets/myforge/models/item/debug_sword.json中layer0对应的纹理路径myforge:item/debug_sword与实际 PNG 文件路径不匹配。常见错误包括PNG 文件名是debug_sword.png但 JSON 写成myforge:item/debug_sword.png多写了.png或 PNG 放在textures/items/多了一个s。解决在runClient控制台中搜索TextureAtlas关键字找到类似Failed to load texture: myforge:item/debug_sword的日志根据日志中的路径严格比对resources/assets/myforge/textures/下的实际文件路径。4.4 现象onPlayerAttack断点命中但event.getEntity().getMainHandItem().is(DEBUG_SWORD.get())始终返回false原因DEBUG_SWORD.get()获取的是注册后的Item实例但event.getEntity().getMainHandItem()返回的是ItemStack其内部item字段是Item的另一个实例因 Forge 的ItemRegistry未正确注入。根本原因是mods.toml中modId与DeferredRegister.create(..., MODID)的第二个参数不一致。解决打开mods.toml确认modIdmyforge打开MyForgeMod.java确认DeferredRegister.create(ForgeRegistries.ITEMS, MODID)中MODID值为myforge非MyForge或MYFORGE执行./gradlew clean彻底清除旧 class 后重试。4.5 现象添加SubscribeEvent方法后runClient报java.lang.IllegalStateException: Event bus is not initialized原因SubscribeEvent注解的方法必须注册到MinecraftForge.EVENT_BUS但MyForgeMod构造函数中MinecraftForge.EVENT_BUS.addListener(...)被放在ITEMS.register(modEventBus)之后而modEventBus的初始化依赖于FMLJavaModLoadingContext.get().getModEventBus()二者异步时序错乱。解决将事件监听器注册移到modEventBus注册之后且必须在super()调用后若存在父类。标准写法public MyForgeMod() { IEventBus modEventBus FMLJavaModLoadingContext.get().getModEventBus(); ITEMS.register(modEventBus); // ✅ 必须在此之后注册事件监听器 MinecraftForge.EVENT_BUS.addListener(this::onPlayerAttack); }5. 模组打包与发布生成可在任意 Forge 1.20.1 环境运行的 .jar 文件./gradlew build生成的build/libs/myforge-1.0.0.jar不能直接扔进mods/文件夹运行——它缺少META-INF/MANIFEST.MF中的关键属性、未嵌入mods.toml、且未剥离开发期依赖如slf4j-api。真正的发布包必须通过./gradlew jarreobfJar流程生成本章详解每一步的不可替代性。5.1 执行标准打包流程jar→reobfJar→remapJarForge 1.20.1 的发布包生成是三阶段流水线缺一不可# 第一阶段生成原始 jar含编译后 class resources ./gradlew jar # 第二阶段重映射将 MCP 名称转为 Mojang 官方混淆名供服务器加载 ./gradlew reobfJar # 第三阶段重映射为客户端可用名将 MCP 名称转为人类可读名供 client 加载 ./gradlew remapJar执行完毕后目标文件位于build/libs/myforge-1.0.0-1.20.1.jar←这才是可发布的最终包build/libs/myforge-1.0.0-1.20.1-sources.jar← 源码包供其他开发者引用逻辑说明reobfJar输出的 jar 是给 Minecraft 服务端用的服务端运行时使用 Mojang 混淆名remapJar输出的 jar 是给客户端用的客户端需人类可读名以支持资源绑定。两者内容相同仅 class 文件内的方法名、字段名不同。build/libs/myforge-1.0.0.jar是开发期产物无任何映射仅用于 IDE 调试。5.2 验证发布包完整性检查 MANIFEST.MF 与 mods.toml 是否嵌入用jar -tf build/libs/myforge-1.0.0-1.20.1.jar查看包内文件列表必须包含META-INF/ META-INF/MANIFEST.MF META-INF/mods.toml com/example/myforge/MyForgeMod.class assets/myforge/models/item/debug_sword.json assets/myforge/lang/en_us.json特别检查META-INF/MANIFEST.MF内容用jar -xf解压后查看Manifest-Version: 1.0 Mod-Tags: forge Mod-Display-Name: MyForge Mod Mod-Description: A debug mod for coordinate logging. Mod-Authors: dev-team Mod-Id: myforge Mod-Version: 1.0.0关键点Mod-Id必须与mods.toml中一致Mod-Display-Name会显示在 Mods 列表中若缺失Mod-IdForge 启动时会直接跳过该 jar不报错也不加载。5.3 在纯净 Forge 环境中测试脱离runClient的终极验证将build/libs/myforge-1.0.0-1.20.1.jar复制到一个全新安装的 Forge 1.20.1 客户端的mods/目录下确保该客户端未运行过runClient然后启动。验证步骤启动后进入主菜单点击Mods→ 搜索myforge确认状态为Loaded创建新世界按T输入/give p myforge:debug_sword确认物品栏出现带纹理的剑攻击猪观察聊天框是否输出[DEBUG] Player ... at (x, y, z)按F3 T重载资源确认纹理和语言未丢失若第 1 步未显示myforge说明mods.toml未正确嵌入或Mod-Id不匹配若第 2 步物品无纹理说明remapJar未执行或assets路径错误若第 3 步无输出说明EVENT_BUS未在发布包中正确注册需检查MyForgeMod构造函数是否被Mod注解正确触发。从那以后我每次提交 release 包前都强制走一遍「新建 Forge 客户端 → 拖入 jar → 启动 → /give → 攻击 → 截图日志」全流程。不是信不过 Gradle而是信不过自己某次手抖删掉的reobfJar任务。希望帮到你。本文还有配套的精品资源点击获取
