1. 项目概述与开发环境搭建
作为一名长期从事Minecraft模组开发的程序员,我想分享一些关于NeoForge 1.21.1开发环境的核心知识。与传统的Forge开发相比,NeoForge在项目结构和代码组织上做了不少优化改进,这些变化对于新手开发者来说可能需要一个适应过程。
首先明确几个关键概念:MODID是模组的唯一标识符,必须全部小写且不含特殊字符;Dist枚举用于区分客户端和服务端代码;IEventBus是事件处理的核心机制。这些我们稍后都会详细展开。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 项目文件结构解析
2.1 基础目录结构
一个标准的NeoForge项目包含以下关键目录和文件:
- /.gradle:项目专用的Gradle缓存,与全局Gradle缓存分开管理
- /.idea:IntelliJ IDEA的工程配置文件(如果你使用其他IDE则不会出现)
- /build:构建过程中生成的临时文件和最终产出物
- /gradle:包含Gradle Wrapper文件,确保团队协作时Gradle版本一致
- /run:Minecraft运行时产生的所有文件(这个目录非常重要,后面会单独讲解)
- /src:源代码和资源文件的主目录
根目录下还有几个关键文件:
- build.gradle:项目构建的核心配置文件(除非你清楚自己在做什么,否则不要随意修改)
- gradle.properties:Gradle属性配置
- settings.gradle:Gradle项目设置
- gradlew和gradlew.bat:Gradle Wrapper的执行脚本(前者用于Unix-like系统,后者用于Windows)
2.2 run目录详解
run目录是Minecraft运行时的数据存储位置,包含以下重要子目录:
- /config:模组配置文件,NeoForge统一使用TOML格式替代了旧版的CFG格式
- /logs:运行日志,崩溃时还会在/crash-reports生成崩溃报告
- /mods:放置额外加载的模组文件
- /resourcepack:存放额外资源包
- /saves:游戏存档数据
- options.txt:游戏设置的本机存储
- usercache.json:玩家UUID与用户名的映射关系
提示:开发调试时经常需要查看/logs下的最新日志,建议保持控制台窗口打开状态实时查看输出。
2.3 存档文件结构解析
每个存档在/saves下都是一个独立目录,目录名即创建世界时指定的名称。存档内部结构如下:
- advancements:玩家成就进度数据
- stats:玩家统计数据记录
- playerdata:玩家个人数据(物品栏、生命值等)
- data:世界全局数据
- poi:兴趣点数据(村民职业站点等)
- region:主世界区块数据
- entities:实体数据
- DIM1和DIM-1:分别对应末地和下界维度数据
- dimensions:其他模组添加的维度数据(NeoForge新引入的结构,解决旧版ID冲突问题)
- level.dat:世界核心元数据
- session.lock:文件锁,防止多进程同时写入
Minecraft使用几种主要数据格式:
- .json:越来越广泛使用的文本格式
- .mca:区域文件格式(命名规则为r.x.z.mca,x和z是区域坐标)
- .dat:通常是NBT格式的二进制文件(类似二进制的JSON)
坐标转换关系:
- 区块坐标
