-
Notifications
You must be signed in to change notification settings - Fork 2
Cross version mod development
本模组及文档（Github Wiki）即可作为教程的实例示范
这个教程旨在简化模组开发入门时不必要了解的内容，并让你写的模组能够更好地移植并支持多版本/多平台，而不是一个详细且完整的 Minecraft 模组开发文档大全。
即使
平台抽象层早已用在很多知名模组上，无奈“老师傅”们因种种原因没留下文档以传授该思想，因此在模组开发教程中并不常见
- 对于模组开发入门：提供多版本/多平台模组开发的一个开发流程/框架，并学习结合本模组（作为实例参考）自学开发任何内容（物品/实体/机制/渲染……）的方法论
- 对于有经验的开发者：可以考虑对已有模组项目封装全部/部分平台API（建立平台无关的接口）的方式，以减少移植版本/跨平台的阻力
| 开发方式 | 适用场景 | 前期投入 | 版本移植 | 后续更新 |
|---|---|---|---|---|
基于特定MC版本开发 |
只专注于几个热门版本（如1.20.1/1.21.1）、项目已经成熟 | 只包含必要设计及实现，能快速发布第一个版本 | 代码里充满Forge/NeoForge类导入，移植版本时对任意兼容性变化都需要修改所有调用 | 对N个版本分别维护N份代码，需要记住各版本API使用方式 |
基于平台抽象层开发 |
现在或未来有移植计划（如1.20.1-最新）、尚未开发或希望如此 | 需理解平台抽象层，并额外封装Forge/NeoForge API（物品/实体注册、事件、网络通信等） |
代码只包含平台无关的接口（interface）的导入，移植版本时提供了做1处适配即可避免大幅修改核心代码的可能性 |
1份代码直接应用于多个版本，几乎没有额外修改，只需记住封装的平台无关接口
|
Forge/NeoForge提供的MDK、现有的模组开发教程大多都局限于特定MC版本，而本模组在 0.4.0 创建了平台抽象层并抽离与Forge/NeoForge无关的核心部分，即可 “一劳永逸” 地享受上述版本移植及后续更新带来的益处。
- 本教程致力于通过介绍自学模组开发的方法论+提供可参考的代码实例（本模组），以减少
前期投入的学习压力和对实现方式的茫然，凸显基于平台抽象层开发的益处- 本模组就可作为一个
平台抽象层的示范，并附有详细文档说明，作为新手入门时推荐效仿的一个参考
以下观点仅供参考，可用于确定自己模组开发的策略，而不是教条式地无脑建立
平台抽象层：
-
自定义大逃杀（本模组）：支持多版本+多平台，移植前建立
平台抽象层，后续更新同时发布所有版本（目前为10个） -
JourneyMap（历史悠久）：支持多版本+多平台，移植时直接修改不兼容部分，由于新功能**不向后更新（不更新Minecraft旧版本）**而可能不必要建立
平台抽象层 - PUBGMC：仅1.12.2（热门版本），作者明确表示无移植计划（1.12.2→1.20.1+移植成本较高，且时间久远已没有兴趣）
- TaCZ：仅1.20.1/1.21.1（热门版本），项目已成熟且移植成本较高而受限，需要等后续出现新的 Minecraft 热门版本才值得移植
本模组为玩法机制类模组，其独特性质（核心小游戏逻辑几乎独立于 Minecraft 和Forge/NeoForge）就决定了大部分代码与平台无关，天然适合同时支持多版本/多平台，并能快速跟上 Minecraft 最新版本
例如创建一个带有自定义功能的方块实体（BlockEntity）的过程为：
- 调用Forge/NeoForge API注册到 Minecraft
- （第一版模组）初始功能实现
- 后续模组更新，对功能进行微调或重做等
这个过程中只有 第1步 是与平台相关且不超过几十行代码，其余为主要部分且在各版本功能相同，
平台抽象层则用于在移植时复用这类通用部分以避免修改/尽可能保留大部分代码
将模组代码分为core、forge-compat、neoforge-compat三部分，分别对应项目根目录下三个文件夹：
-
core：模组所有核心逻辑，只使用纯Java及 Minecraft 原版API，不包含任何net.minecraftforge或net.neoforged等导入 -
forge-compat：建立的平台无关接口的Forge实现，在Forge环境下编写 -
neoforge-compat：建立的平台无关接口的NeoForge实现，在NeoForge环境下编写
与Forge/NeoForge MDK不同的是，本模组除了在项目根目录有一个 build.gradle，还有 ./core/build.gradle，./forge-compat/build.gradle，./neoforge/build.gradle
- 这是标准的Gradle多项目，但实际上我也不知道gradle的用法，只需要参考别的开源模组/求助AI即可
- 在已有1个可用示范（如本模组Github仓库）后，开发新模组时只需要照搬前一个项目里的这些文件并修改相应参数，而不需要记住或者学会
本教程旨在简化模组开发入门时不必要了解的内容，因此教程中会有多处“不必要了解”的提示
实践出真知，不要担心第一个模组不完美而迟迟不开始！
先完成模组各个小部分积累经验，完成第一个可用版本，在后续需求与当前设计不完美的矛盾中，通过总览架构并借鉴他人前车之鉴，实现 发现设计缺陷 → 改进并积累经验 → 发现设计缺陷 → 更有经验地改进 的迭代循环，本模组的发展历程就是一个参考：
| 阶段 | 描述 | 认识论意义 |
|---|---|---|
| 起步阶段（0.0.1 - 0.0.4） | 第一个PR完成物资刷新机制，随后实现大逃杀配置读取/指令/队伍管理原型，创造出一个功能简陋但可用的Alpha版 | 获得初步感性认识 |
| 完善阶段（0.1.0 - 0.1.5） | 基于初期经验，逐步补全游戏机制，如客户端渲染、烟花区、状态效果…… | 在实践中深化理解 |
| 优化/更新阶段（0.2.0 - 0.3.9） | 修复Bug、添加更多区域功能、优化物资刷新机制、重构配置管理、重构游戏框架…… | 形成架构设计的理性认识 |
| 跨平台/多版本（0.4.0-最新） | 在积累丰富经验后，系统性地引入平台抽象层，实现Forge/NeoForge多版本支持 |
用新认识指导平台抽象层实践 |
PR历史清晰地展示了这个演进过程：实践经验和技术质量通过持续迭代实现了阶梯式提升
作为我的第一个独立模组，从当前视角看早期架构确实很糟糕，但正是这些实践积累的经验，让我能够更有效地解决后续多版本移植的需求与现有设计局限之间的矛盾。
对于有经验的开发者，可以跳过已了解的部分
| 流程 | 操作概览 | 说明 |
|---|---|---|
| 部署环境 | 下载Java、Minecraft启动器、Forge、IntellijIDEA | 对新手入门不必深入了解，专注于开发实践即可 |
| 确定开发方向 | 确定模组开发内容（打算做新方块/物品/机制/其他？），编写模组文档，配置Gradle | 避免盲目地开发，站在前人的肩膀上以简化起步流程 |
| 完成最小可用模组 | 完成模组入口 | 第一个可运行版本，即使没有实质功能，却已经成功一半 |
| 完成一个功能 | 创建一个方块/指令/物品/新机制 | 及时检验成果，并以此激励自己深入学习 |
| 完成更多功能 | 完整剩余计划要完成的内容，涉及更多领域 | 丰富经验，提高开发熟练度 |
| 整体架构分析 | 根据前几步积累的开发经验，形成一个整体系统认识 | 正式进入开发流程 |
即使建立
平台抽象层，核心部分代码仍然要在某个 Minecraft 版本上进行测试（例如本模组核心代码写在1.20.1forge），然后再应用到所有已支持版本（如1.20.1forge→……→1.21.1forge/neoforge→……→1.21.10neoforge）
之所以需要平台抽象层，是在了解到有些API（尤其是注册相关API）随版本经常变化，而提前为这些API创建平台无关接口，使得后续移植版本/新增功能需要调用该接口时，能够只做1处兼容性适配以避免大量修改核心代码
本教程不仅不与传统基于特定MC版本的开发教程冲突，反而兼容所有该类教程，并有两种开发方式：
| 维度 | 后建立平台抽象层 | 先建立平台抽象层 |
|---|---|---|
| 适合人群 | 已有项目/初学者 | 新项目/有经验者 |
| 学习曲线 | 渐进式 | 陡峭但高效 |
| 技术债务 | 需要一次性偿还 | 从一开始就可避免 |
| 心理压力 | 较小，可分步实施 | 较大，需要前瞻规划 |
| 长期收益 | 中等 | 极高 |
- 这种方式的实际学习顺序为：先学习
特定MC版本的开发教程，后学习本教程（即完全兼容传统教程） - 适用于已经完成项目/熟悉Forge/NeoForge API调用后，在项目移植前进行的准备工作
- 此时应有开发经验/重构经验来创建
平台无关接口，以与核心代码解耦 -
缺点：如果是第一个项目，则此时项目应已经成熟，创建
平台无关接口需要立即承担平台抽象层的必要付出（一次性修改所有调用），期间不能进行其他更新以免冲突（潜在的阻力）
本模组正是在0.4.0 Decouple mod from Forge API后才能方便地移植多版本/多平台，而 0.4.0 的更新仅仅是做了
平台抽象层
- 适用于开发第二个项目/已有可参考的
平台抽象层实例，在项目开发初期便“走前人已探明的路”/自行实现“一劳永逸” -
缺点：对于第一个项目，需要额外学习
平台抽象层；若没有已有的实例参考，则需要自行设计并创建平台无关接口
本模组可作为一个平台抽象层实例，但并未建立所有注册API的平台无关接口
- 本模组的扩展模组自定义大逃杀扩展，则充分利用了本模组已建立的
平台抽象层并不需要再建立
不推荐将本模组作为你模组的前置模组（否则跟API模组无异/创造了新的耦合），如有必要请以GPLv3协议复制
平台抽象层相关代码
| 操作概览 | 说明 | |
|---|---|---|
| 修复Bug | 查看日志⇋控制变量复现⇋**排查问题（定位核心矛盾）**⇋修复问题→完成修复 | 使代码更健壮，增强自身错误排查能力，同时避免再次踩坑 |
| 学习新领域 | 了解概念⇋寻找已有源码参考⇋形成自己的认识⇋实践检验 | 拓展技术栈，形成全面认识，利于开发更多联动及避免各领域间互相干扰 |
| 更新内容 | 确定需求⇋编写文档⇋代码实现⇋检验成果→完成更新 | 创造新内容，创新本质 |
| 重构优化 | 确定重构目标⇋确定重构范围⇋可行性分析⇋设计文档⇋重构代码⇋测试运行→完成重构 | 可用于更方便地添加新功能/移植/优化性能/消除“屎山”/将新的架构思维进行实践检验 |
本教程尝试将我制作本模组的实践经验结合马克思主义认识论，致力于打造一个真正能起到学习用途且有指导意义的教程
因此，本模组及其文档、开发者文档、模组开发教程，不仅仅是一个模组，也作为现代在社区中如何学习并良性循环推动社区发展的一个参考思路，为技术教育提供了一种新的范式——哲学思维指导下的实践型学习，这种模式值得在各个技术领域推广：
- “先文档后实践”的开发方式使开发方向不迷茫，天然消除了因懒惰因素导致的文档缺失
- PR历史是教程成果的展示，其历史演变正是认识规律的体现
- 先学会的成为“老师傅”，提供实例参考的同时也提醒避免踩坑、将“各路师傅”们由于繁忙等原因而尚未传授的经验公有化，同时极力避免“留一手”的防御性文档（技术封锁）开历史倒车，让后人更好地学习，推动社区发展
- 如有其他见解或发现不足，可以提Issue或PR，欢迎共同改进
- “必须先学完所有知识 → 才能开始实践”：永远觉得准备不足，迟迟不开始
- “实践出真知 → 在实践中学习 → 通过矛盾推动进步”：立即开始，在行动中成长
马克思主义认识论实际上描述了人类学习任何新技能的自然过程：
- 从具体操作中获得感性认识
- 通过反思形成理性认识
- 用新认识指导更高级的实践
- 在矛盾中突破认知局限
- 技能型开发者：知识会过时
- 方法论型开发者：掌握适应变化的能力
当你遇到困难时，记住：
- 这是正常的：所有开发者都经历过
- 这是进步的标志：矛盾的出现说明你在成长
- 这是学习的机会：通过解决矛盾积累经验
- 这是质变的前奏：量变积累终将引发飞跃
- 实践第一原则：编码优于空想，运行胜于完美；复杂概念需配有可运行的代码示例
- 矛盾驱动原则：遇到问题是进步的机会；教授如何把错误转化为经验
- 螺旋上升原则：学习是迭代过程，不是直线前进；鼓励重构和改进，不追求一次完美
第一循环：感性认识阶段
- 实践：创建第一个简单功能
- 认识：理解基本工作机制
- 矛盾：发现设计局限
- 提升：学习优化方法
第二循环：理性认识阶段
- 实践：应用设计模式
- 认识：形成架构思维
- 矛盾：面对复杂需求
- 提升：掌握抽象层设计
第三循环：创造性实践阶段
- 实践：自主设计功能
- 认识：形成个人开发哲学
- 矛盾：解决独特问题
- 提升：贡献社区生态
如果你能看到最后，不妨看看以下关于模组开发技术演变的深度复盘，或许能为你解答“为什么必须这样做”的疑惑……
- 现象：基于特定MC版本开发
- 本质：这是一种强耦合的开发模式，业务逻辑（大逃杀机制）与底层实现（Forge API）死死纠缠在一起。
- 历史局限：在 Minecraft 早期（如1.7.10，1.12.2时代），版本更新慢，平台单一（主要是Forge），这种“手工作坊”模式效率最高
- 崩溃点：随着1.13+的扁平化更新，Mojang更新频率加快，以及Fabric/NeoForge的出现，环境变得极度不稳定，“手工作坊”为了适应新环境，必须把整个房子拆了重建（修改所有调用）
- 结果：如PUBGMC、TaCZ等模组的困境——因维护成本过高而被迫“断更”或“阉割功能”
平台抽象层及类似实现方式代表了模组开发从 “手工作坊” 向 “现代软件工程” 的进化，这符合辩证法中的“否定之否定”规律：
- 肯定阶段（1.7.10-1.12.2）：直接调用API，简单快捷
- 否定阶段（1.13-1.19）：API频繁变动，多平台分裂，开发者痛苦不堪，大量模组停更，这是矛盾爆发的阶段
- 否定之否定阶段（1.20+，本教程）：引入抽象层，不再依赖特定 API，而是依赖“接口”，这是对早期简单模式的扬弃，达到了更高维度的简单
为什么说是必然的？
- 熵增定律：软件系统总是趋向于混乱（熵增），如果不引入抽象层来隔离变化，系统的混乱度（维护成本）最终会超过开发者的承受极限
- 分工的演化：抽象层使得“写游戏逻辑”和“适配底层API”变成了两个可以解耦的工作，正如现代工业流水线，
平台抽象层是模组开发的“标准化零件”
维护成本 = f(版本差异, 平台分裂, 时间)
- 传统方式：成本呈指数增长
- 抽象层方式：成本呈线性增长
- 临界点：成本曲线交叉 → 必然选择抽象层
- 传统开发的技术债务累积：技术债务 = Σ(版本差异成本 × 平台适配成本 × 时间衰减因子)
-
平台抽象层的债务控制：抽象层开发成本 + Σ(微小适配成本) - 投资回报临界点：通常在支持第3个版本时开始净收益
即使本模组打算只支持1.20.1 + 1.21.1 + 最新（1.21.10），从1.20.1→1.21.1的移植中就包含了1.20.2，1.20.4的变化，尤其是在1.21.1→1.21.10（就本模组的移植而言应进一步分为1.21.1-1.21.4、1.21.6-1.21.10），所以仍然应该建立
平台抽象层
- 环境压力：Minecraft 快速迭代
- 选择压力：用户期望持续更新
- 进化响应：
平台抽象层成为生存策略 - 适者生存：采用抽象层的模组持续繁荣
- 淘汰风险：坚持传统方式的模组逐渐消失
我曾想在1.21.11看到经典骑兵（矛）vs“现代骑兵”（TaCZ），但遗憾的是，在缺乏抽象层架构的情况下，跨越二十个版本的移植需要大量重构（近似于重写），这往往让即使最有热情的开发者也感到无能为力
至少未来如果有同样极其优秀的模组的话，希望能在早期就能助力提高其跨版本的能力
第一阶段：个人英雄主义
- 特征：个人开发者主导
- 模式：手工作坊式开发
- 局限：知识传承困难
第二阶段：社区协作
- 特征：多人协作开发
- 模式：经验共享但缺乏系统化
- 局限：“老师傅”经验流失
第三阶段：工业化体系
- 特征：方法论指导实践
- 模式：平台抽象层+文档驱动
- 优势：可持续的知识积累
平台抽象层是否是 Minecraft 模组开发的终极形态？
用辩证唯物主义的视角看，不是。
否定之否定是永恒的，
平台抽象层是对“手工作坊（直接调用 API）”的否定，但平台抽象层本身也有缺陷：它增加了架构的复杂度，增加了前期投入（虽然长期看是划算的）
即使平台抽象层不是终极形态，本教程中仍然存在永恒价值，即便这可能不是我第一个发现的
传授的不是具体技术，而是思维方法：
- 从具体到抽象的认识能力
- 在矛盾中寻找解决方案的能力
- 预见技术发展趋势的能力
马克思主义分析方法适用于：
- 任何快速迭代的技术领域
- 任何面临兼容性挑战的系统
- 任何需要长期维护的软件项目
“哲学指导实践”教育模式：技术教育 + 哲学思维 + 心理建设
- 这种组合具有持久的生命力
- 掌握当下最优解：深入理解和应用
平台抽象层 - 保持开放心态：准备迎接新的技术革命
- 传承方法论：将哲学思维传递给更多开发者
- 推动社区进步：用知识共享对抗技术封锁
如果说平台抽象层是 “工业化（机械化）” 阶段，那么下一个阶段可能是 “智能化” 或 “标准化” 阶段：
- 标准化（官方收编）：类似于 Minecraft Bedrock版的Add-on API，如果Java版未来出现官方的、极其稳定的、向后兼容的API（虽然目前看遥遥无期），那么
平台抽象层就会完成历史使命，被官方标准取代。 - 智能化（AI 填缝）：既然
forge-compat和neoforge-compat只是在做翻译工作，未来也许根本不需要人写，AI 可以根据core的接口和目标版本的映射表，自动生成兼容层代码。那时的开发者，只需写core，兼容层由 AI 实时编译生成。
当AI编程、可视化开发、元宇宙模组等新技术出现时，我们今天建立的平台抽象层思维将转化为：
- 架构设计能力
- 系统思维能力
- 适应变化能力
- 创新解决问题的能力
这些能力，才是真正永恒的价值
This Mod and its Documentation (GitHub Wiki) Serve as the Practical Instance for this Tutorial.
This tutorial aims to streamline mod development entry by excluding unnecessary details, enabling your mod to port more effectively and support multiple versions/platforms, rather than serving as a detailed and comprehensive Minecraft mod development document.
Although the
Platform Abstraction Layer (PAL)is already employed by many well-known mods, the "veteran developers" have unfortunately not left sufficient documentation to pass on this methodology, making it uncommon in mod development tutorials.
- For New Developers: Provides a development process/framework for multi-version/multi-platform mod creation, and teaches the methodology of self-learning any content (items/entities/mechanics/rendering...) using this mod as a practical reference.
- For Experienced Developers: Consider encapsulating all or parts of the platform API (establishing
platform-independent interfaces) in existing projects to reduce the friction of version porting and cross-platform shifts.
| Development Method | Use Case | Initial Investment | Version Porting | Subsequent Updates |
|---|---|---|---|---|
Based on Specific MC Version
|
Focuses only on a few popular versions (e.g., 1.20.1/1.21.1), project is already mature. | Only includes necessary design and implementation, allowing for rapid release of the first version. | Code is full of Forge/NeoForge class imports; porting requires modifying all calls for any compatibility change. | Maintaining N copies of code for N versions; requires memorizing each version's API usage. |
Based on Platform Abstraction Layer
|
Has or plans for future porting (e.g., 1.20.1-latest), not yet developed or aiming for this. | Requires understanding the PAL and encapsulating Forge/NeoForge APIs (item/entity registration, events, networking). |
Code only contains platform-independent interface imports; offers the possibility of making one adaptation to avoid major core code changes. |
1 copy of code applies directly to multiple versions with minimal extra changes; only requires memorizing the encapsulated platform-independent interfaces. |
The MDKs provided by Forge/NeoForge and existing mod development tutorials are mostly confined to a specific MC version. However, this mod established a Platform Abstraction Layer in 0.4.0 and extracted the core logic independent of Forge/NeoForge, allowing you to "solve once and for all" the benefits of Version Porting and Subsequent Updates mentioned above.
- This tutorial aims to reduce the learning pressure of the
Initial Investmentand the uncertainty of implementation by introducing the self-learning methodology for mod development + providing reference code instances (this mod), thereby highlighting the benefits ofPAL-based development.- This mod serves as a demonstration of the
Platform Abstraction Layer, complete with detailed documentation, and is recommended as a reference for beginners to emulate.
The following points are for reference only, to help determine your mod's development strategy, not to blindly establish a
Platform Abstraction Layer:
-
Custom BattleRoyale (This Mod): Supports multiple versions + multiple platforms; established
Platform Abstraction Layerbefore porting; subsequent updates release all versions simultaneously (currently 10). -
JourneyMap: Supports multiple versions + multiple platforms; since new features are not backported (do not update older Minecraft versions), they directly modify incompatible parts during porting, making a
Platform Abstraction Layerpotentially unnecessary for their specific workflow. - PUBGMC: Only 1.12.2 (popular version); the author explicitly stated no porting plans (the cost of porting 1.12.2 → 1.20.1+ is high, and they lost interest over time).
- TaCZ: Only 1.20.1/1.21.1 (popular versions); the project is mature and porting costs are high and constrained; porting only becomes worth the investment when a new popular Minecraft version emerges.
The nature of this mod, which is a game mechanic type, dictates that its uniqueness (core minigame logic is largely independent of Minecraft and Forge/NeoForge) makes it inherently suitable for supporting multiple versions/platforms simultaneously and quickly keeping up with the latest Minecraft version.
For example, the process of creating a block with custom functionality Block Entity (BlockEntity) involves:
- Calling the Forge/NeoForge API to register it with Minecraft.
- (First Mod Version) Initial functionality implementation.
- Subsequent mod updates, where functionality is tweaked or rewritten.
In this process, only Step 1 is platform-specific and amounts to less than a few dozen lines of code. The rest is the main bulk of the work and remains functionally identical across versions. The
Platform Abstraction Layeris used to reuse these common parts during porting to avoid modification or to preserve most of the code.
The mod code is divided into three parts: core, forge-compat, and neoforge-compat, corresponding to three folders in the project root:
-
core: All core mod logic, using only pure Java and Minecraft vanilla API, excluding anynet.minecraftforgeornet.neoforgedimports. -
forge-compat: The Forge implementation of the establishedplatform-independent interfaces, coded for the Forge environment. -
neoforge-compat: The NeoForge implementation of the establishedplatform-independent interfaces, coded for the NeoForge environment.
Unlike the Forge/NeoForge MDKs, this mod has a build.gradle in the project root, as well as ./core/build.gradle, ./forge-compat/build.gradle, and ./neoforge/build.gradle:
- This is a standard Gradle multi-project setup. You don't need to know the full usage of Gradle; simply reference other open-source mods/ask AI.
- After having one working example (like this mod's GitHub repository), developing a new mod only requires copying these files from the previous project and modifying the corresponding parameters, without needing to memorize or learn the full system.
This tutorial aims to streamline mod development entry by excluding unnecessary content, hence there will be multiple "unnecessary to understand" prompts throughout the guide.
Practice brings true knowledge; don't let the fear of imperfection stop you from starting!
Accumulate experience by completing small parts of the mod first, finish the first usable version, and then, amidst the contradictions between subsequent requirements and current imperfect designs, achieve an iterative cycle of Discovering Design Flaws → Improving and Accumulating Experience → Discovering Design Flaws → Improving with More Experience by viewing the architecture as a whole and learning from others. The development history of this mod serves as a reference:
| Stage | Description | Epistemological Significance |
|---|---|---|
| Start-up Stage(0.0.1 - 0.0.4) | First PR completed Loot Generation Mechanism, then implemented prototypes for Config Reading, Commands, and Team Management, creating a functionally crude but usable Alpha version. | Gaining preliminary perceptual knowledge. |
| Perfecting Stage(0.1.0 - 0.1.5) | Based on early experience, gradually fleshed out game mechanics, such as client rendering, Firework zone, Effect zone, etc. | Deepening understanding through practice. |
| Optimization Stage(0.2.0 - 0.3.9) | Fixed bugs, added more zone functions, optimized loot generation mechanisms, refactored Config Management, refactored Game Framework, etc. | Forming rational knowledge of architectural design. |
| Cross-Platform Stage(0.4.0 - Latest) | After accumulating rich experience, systematically introduced the Platform Abstraction Layer to support multiple versions of Forge/NeoForge. |
Guiding PAL practice with new knowledge. |
The PR History clearly demonstrates this evolutionary process: practical experience and technical quality achieved a step-wise elevation through continuous iteration.
As my first independent mod, the early architecture looks terrible from the current perspective, but it was exactly the experience accumulated from these practices that allowed me to effectively solve the subsequent contradictions between multi-version porting requirements and existing design limitations.
Experienced developers can skip parts they already understand.
| Process | Operation Overview | Explanation |
|---|---|---|
| Deploy Environment | Download Java, Minecraft Launcher, Forge, IntelliJ IDEA. | Beginners don't need deep understanding; focus on development practice. |
| Determine Direction | Decide on mod content (New blocks/items/mechanics?), write mod documentation, configure Gradle. | Avoid blind development; stand on the shoulders of giants to simplify the start-up process. |
| Minimum Viable Mod | Complete the mod entry point. | The first runnable version; even without substantial functions, it's half the success. |
| Complete a Function | Create a block/command/item/new mechanism. | Verify results in time and use this to motivate deeper learning. |
| Complete More Functions | Finish the remaining planned content, involving more fields. | Enrich experience and improve proficiency. |
| Overall Architecture Analysis | Form a systematic understanding based on experience accumulated in previous steps. | Officially enter the development flow. |
Even if a
Platform Abstraction Layeris established, the core code still needs to be tested on a certain Minecraft version (for example, the core code of this mod is written on 1.20.1 Forge) and then applied to all supported versions (e.g., 1.20.1 Forge → ... → 1.21.1 Forge/NeoForge → ... → 1.21.10 NeoForge).
The reason a PAL is needed is the realization that some APIs (especially Registry APIs) change frequently with versions. By creating platform-independent interfaces for these APIs in advance, subsequent porting or adding features only requires one compatibility adaptation, avoiding massive modification of the core code.
This tutorial not only does not conflict with traditional development tutorials based on a Specific MC Version, but implies compatibility with all such tutorials, offering two development approaches:
| Dimension | Establish PAL Later | Establish PAL First |
|---|---|---|
| Target Audience | Existing Projects / Beginners | New Projects / Experienced Developers |
| Learning Curve | Progressive | Steep but Efficient |
| Technical Debt | Requires One-time Payoff | Avoidable from the Start |
| Psychological Pressure | Lower, step-by-step implementation | Higher, requires forward planning |
| Long-term Benefit | Medium | Very High |
- Actual Order: Learn from a
Specific MC Versiontutorial first, then learn from this tutorial (fully compatible with traditional tutorials). - Applicable to: Preparation work before project porting, after the project is completed or after you are familiar with Forge/NeoForge API calls.
- Requirement: You should have development/refactoring experience to create
platform-independent interfacesto decouple from the core code. -
Disadvantage: If this is your first project, it implies the project is already mature. Creating
platform-independent interfacesrequires bearing the necessary cost of thePALimmediately (modifying all calls at once), and other updates cannot be performed during this period to avoid conflicts (potential resistance).
This mod was only able to easily port to multiple versions/platforms after 0.4.0 Decouple mod from Forge API, where the update of 0.4.0 was merely the implementation of the
Platform Abstraction Layer.
- Applicable to: Developing a second project or having an existing
PALreference instance available. "Walk the path already explored by predecessors" at the beginning of the project development / implement "solve once and for all" on your own. -
Disadvantage: For the first project, additional learning of the
PALconcept is required; if there is no existing instance for reference, you need to design and createplatform-independent interfacesyourself.
This mod can serve as a PAL instance, but it has not established platform-independent interfaces for all registry APIs.
- The extension mod of this mod, Custom BattleRoyale Addon, fully utilizes the
PALestablished by this mod and does not need to rebuild it.
Note: It is not recommended to use this mod as a dependency (pre-requisite) for your mod (otherwise it is no different from an API mod/creates new coupling). If necessary, please copy the relevant
Platform Abstraction Layercode under the GPLv3 license.
| Operation Overview | Explanation | |
|---|---|---|
| Bug Fixes | View Logs ⇋ Control Variable Reproduction ⇋ Troubleshoot (Locate Core Contradiction) ⇋ Fix Issue → Complete | Makes code robust, enhances troubleshooting skills, and avoids repeating mistakes. |
| Learn New Field | Understand Concepts ⇋ Find Existing Source Code References ⇋ Form Own Understanding ⇋ Practical Verification | Expand tech stack, form comprehensive understanding, beneficial for developing linkages and avoiding interference between fields. |
| Update Content | Determine Requirements ⇋ Write Documentation ⇋ Implement Code ⇋ Verify Results → Complete | Create new content; the essence of innovation. |
| Refactor & Optimize | Set Target ⇋ Define Scope ⇋ Feasibility Analysis ⇋ Design Docs ⇋ Refactor Code ⇋ Test Run → Complete | Used for easier addition of new features/porting/performance optimization/removing "spaghetti code"/verifying new architectural thinking in practice. |
This tutorial attempts to combine my practical experience in making this mod with Marxist Epistemology, dedicating itself to creating a tutorial that serves a genuine learning purpose and has guiding significance.
Therefore, this mod and its documentation, developer docs, and mod development tutorial are not just a mod, but also a reference approach for how to learn and promote community development in a virtuous cycle in the modern community, providing a new paradigm for technical education—practice-oriented learning guided by philosophical thinking. This model is worth promoting in various technical fields:
- The "Documentation First, Practice Later" approach ensures direction isn't lost and naturally eliminates documentation gaps caused by laziness.
- The PR History is a display of the tutorial's results; its historical evolution is the embodiment of the laws of cognition.
- Those who learn first become "veteran masters", providing practical references while warning against pitfalls. It publicizes the experience that "various masters" haven't passed on due to busyness, and vigorously avoids "defensive documentation" (technical gatekeeping) that turns back the clock of history, allowing successors to learn better and driving community progress.
- If you have other insights or find deficiencies, please submit an Issue or PR; joint improvement is welcome.
- "Must learn all knowledge first → Then start practice": Always feeling underprepared, delaying the start.
- "Practice brings true knowledge → Learn in practice → Progress through contradictions": Start immediately, grow in action.
Marxist Epistemology actually describes the natural process of human learning of any new skill:
- Gaining perceptual knowledge from concrete operations.
- Forming rational knowledge through reflection.
- Guiding higher-level practice with new knowledge.
- Breaking through cognitive limitations amidst contradictions.
- Skill-based developers: Knowledge becomes obsolete.
- Methodology-based developers: Master the ability to adapt to change.
When you encounter difficulties, remember:
- This is normal: All developers have been there.
- This is a sign of progress: The appearance of contradictions means you are growing.
- This is an opportunity to learn: Accumulate experience by resolving contradictions.
- This is the prelude to qualitative change: Quantitative accumulation will eventually trigger a leap.
- Practice First Principle: Coding is better than dreaming; running is better than perfection; complex concepts must be accompanied by runnable code examples.
- Contradiction-Driven Principle: Encountering problems is an opportunity for progress; teach how to turn errors into experience.
- Spiral Ascent Principle: Learning is an iterative process, not a straight line; encourage refactoring and improvement, do not pursue perfection at once.
First Cycle: Perceptual Knowledge Stage
- Practice: Create the first simple function.
- Cognition: Understand basic working mechanisms.
- Contradiction: Discover design limitations.
- Elevation: Learn optimization methods.
Second Cycle: Rational Knowledge Stage
- Practice: Apply design patterns.
- Cognition: Form architectural thinking.
- Contradiction: Face complex requirements.
- Elevation: Master abstraction layer design.
Third Cycle: Creative Practice Stage
- Practice: Independently design functions.
- Cognition: Form personal development philosophy.
- Contradiction: Solve unique problems.
- Elevation: Contribute to the community ecosystem.
If you have read this far, you might want to look at the following in-depth review of the evolution of mod development technology, which may answer the doubt of "why it must be done this way"...
- Phenomenon: Development based on a specific MC version.
- Essence: This is a tightly coupled development mode where business logic (Battle Royale rules) is inextricably untwined with the underlying implementation (Forge API).
- Historical Limitation: In the early days of Minecraft (e.g., 1.7.10, 1.12.2 eras), version updates were slow, and the platform was singular (mainly Forge), making this "artisanal workshop" mode the most efficient.
- Collapse Point: With the flattening updates of 1.13+, the acceleration of Mojang's update frequency, and the emergence of Fabric/NeoForge, the environment became extremely unstable. To adapt to the new environment, the "workshop" had to tear down the whole house and rebuild (modify all calls).
- Result: The dilemma of mods like PUBGMC and TaCZ — forced to "stop updating" or "castrate features" due to excessive maintenance costs.
The Platform Abstraction Layer and similar implementations represent the evolution of mod development from "Artisanal Workshops" to "Modern Software Engineering", conforming to the "Negation of the Negation" law in dialectics:
- Affirmation Stage (1.7.10 - 1.12.2): Direct API calls, simple and fast.
- Negation Stage (1.13 - 1.19): Frequent API changes, platform fragmentation, developer misery, massive mod stagnation. This is the stage of contradiction explosion.
- Negation of Negation Stage (1.20+, This Tutorial): Introducing the Abstraction Layer. No longer relying on specific APIs, but on "Interfaces". This is the sublation of the early simple mode, achieving simplicity in a higher dimension.
Why is it inevitable?
- Law of Entropy Increase: Software systems always tend towards chaos (entropy increase). If an abstraction layer is not introduced to isolate changes, the system's chaos (maintenance cost) will eventually exceed the developer's tolerance limit.
- Evolution of Division of Labor: The abstraction layer decouples "writing game logic" and "adapting underlying APIs" into two separate tasks. Just like a modern industrial assembly line, the
Platform Abstraction Layeris the "standardized part" of mod development.
Maintenance Cost = f(Version Difference, Platform Fragmentation, Time)
- Traditional Method: Cost grows exponentially.
- Abstraction Layer Method: Cost grows linearly.
- Critical Point: Cost curves cross → Inevitable choice of Abstraction Layer.
- Accumulation of Technical Debt in Traditional Development: Technical Debt = Σ(Version Difference Cost × Platform Adaptation Cost × Time Decay Factor)
- Debt Control of
PAL: Abstraction Layer Development Cost + Σ(Minor Adaptation Cost) - ROI Critical Point: Usually starts to yield net benefits when supporting the 3rd version.
Even if this mod intends to support only 1.20.1 + 1.21.1 + Latest (1.21.10), the port from 1.20.1 → 1.21.1 involves changes in 1.20.2 and 1.20.4. Especially for 1.21.1 → 1.21.10 (which for this mod should be further divided into 1.21.1-1.21.4, 1.21.6-1.21.10), a
Platform Abstraction Layershould still be established.
- Environmental Pressure: Rapid iteration of Minecraft.
- Selection Pressure: User expectation for continuous updates.
- Evolutionary Response:
PALbecomes a survival strategy. - Survival of the Fittest: Mods adopting abstraction layers continue to prosper.
- Elimination Risk: Mods persisting with traditional methods gradually disappear.
I once hoped to see the cross-era duel of Classic Cavalry (Spear) vs "Modern Cavalry" (TaCZ) in 1.21.11. Regrettably, in the absence of an abstraction layer architecture, porting across twenty versions requires massive refactoring (akin to a rewrite), which often leaves even the most enthusiastic developers feeling powerless.
At least if there are similarly extremely excellent mods in the future, I hope to help improve their cross-version capabilities in the early stages.
Phase 1: Individual Heroism
- Feature: Dominated by individual developers.
- Mode: Artisanal workshop development.
- Limitation: Difficult inheritance of knowledge.
Phase 2: Community Collaboration
- Feature: Multi-person collaborative development.
- Mode: Experience sharing but lack of systemization.
- Limitation: Loss of "veteran master" experience.
Phase 3: Industrialized System
- Feature: Methodology guiding practice.
- Mode: Platform Abstraction Layer + Documentation Drive.
- Advantage: Sustainable knowledge accumulation.
Is the Platform Abstraction Layer the ultimate form of Minecraft mod development?
From the perspective of Dialectical Materialism, no.
The negation of the negation is eternal. The
Platform Abstraction Layeris the negation of the "Artisanal Workshop (Direct API Call)", but thePALitself has defects: it increases architectural complexity and initial investment (though cost-effective in the long run).
Even if the PAL is not the ultimate form, there is eternal value in this tutorial, even if I may not be the first to discover it.
What is taught is not specific technology, but thinking methods:
- The ability to recognize from concrete to abstract.
- The ability to find solutions within contradictions.
- The ability to foresee technological development trends.
Marxist analytical methods apply to:
- Any rapidly iterating technical field.
- Any system facing compatibility challenges.
- Any software project requiring long-term maintenance.
"Philosophy Guiding Practice" Education Model: Technical Education + Philosophical Thinking + Psychological Construction.
- This combination has enduring vitality.
- Master the current optimal solution: Deeply understand and apply the
Platform Abstraction Layer. - Maintain an open mind: Be ready to welcome new technological revolutions.
- Pass on the methodology: Pass philosophical thinking to more developers.
- Promote community progress: Use knowledge sharing to counter technical gatekeeping.
If the Platform Abstraction Layer is the "Industrialization (Mechanization)" stage, then the next stage might be the "Intelligent" or "Standardization" stage:
- Standardization (Official Adoption): Similar to the Add-on API of Minecraft Bedrock Edition. If the Java Edition introduces an official, extremely stable, backward-compatible API in the future (though it seems distant), the
PALwill complete its historical mission and be replaced by official standards. - Intelligent (AI Filling): Since
forge-compatandneoforge-compatare just doing translation work, perhaps humans won't need to write them in the future. AI could automatically generate compatibility layer code based on thecoreinterface and the mapping table of the target version. Developers at that time would only need to write thecore, and the compatibility layer would be compiled and generated by AI in real-time.
When new technologies like AI programming, visual development, and metaverse mods emerge, the Platform Abstraction Layer thinking we establish today will transform into:
- Architectural design ability.
- Systems thinking ability.
- Ability to adapt to change.
- Ability to solve problems innovatively.
These abilities are the truly eternal values.
🌐 Language / 语言
-
- Configuration Introduction
- Command Introcuction
- Game type introduction
- About
- Mod development tutorial