Skip to content

QZyme/Besson-Tools / skill

besson-tutorials

Verified

北山Besson Minecraft 模组开发教程 — 中文,覆盖 Fabric 1.20.1/1.21.X/26.1、Forge 1.20.1、NeoForge 1.21.1/26.1

北山Besson Minecraft 模组开发教程

站点: Tomorrow-Land · 作者: BeiShan_Besson B站: @北山Besson GitHub: BeiShanair 交流频道: pd09376785 · 爱发电: https://afdian.com/a/bessonair

所有教程均采用 CC BY-NC-SA 4.0 许可

最后与站点同步校验: 2026-11-07(文章总数 217:章节 212 + 独立文章 4 + 总汇页 1)

使用本技能时,用户提到的需求对应到下方具体的教程系列和章节,可以直接输出对应的链接和指引。


🎯 快速路由(先定位,再动手)

你的需求建议路线说明
第一次写模组 / 入门A(Fabric 1.20.1)或 C(Forge 1.20.1),从 #1 起1.20.1 中文资料最全、生态最稳,先跑通再加功能
在 1.21.1 上开发 / NeoForgeD(NeoForge 1.21.1),从 #1 起(环境搭建在 #3)NeoForge 是 1.21.1 主流;D#6 网络、D#33 流体等是进阶重点
追最新版 26.1 / 26.2E(Fabric 26.1,已开 30 篇:#1~#8、#22~#43);F(NeoForge 26.1)站内未开JDK 25;NeoForge 26.1 官方 2026-03 已适配,可对照官方文档
网络包 / 渲染 / 粒子 / GUI 等专题C#39-44 / D#39-44 对应章节 + 对应系列前 15 章基础专题章依赖注册、事件、数据生成基础
从 1.20.1 迁移到 1.21.1先 A 前 15 章打底,再转 D;重点读各系列「环境/迁移」章见下方迁移指南;包名/事件/注册方式差异最大
查具体标题/API 关键词用 besson_tutorial_lookup(先搜再做,最多 1-3 条)系列字母 + 版本 + 主题词组合检索最准
要正文/代码细节用 besson_tutorial_fetch 抓正文(按 query 自动解析)正文含代码块;一次只抓 1-2 篇
列某系列全部章节用 besson_tutorial_series(含缺号与日期)先看缺号,避免白找

通用原则:先搜索定位 → 再抓正文 → 再动手写代码;跨版本先 besson_tutorial_compare + besson_tutorial_env。

🧭 版本与环境矩阵

MC 版本LoaderJDK构建插件mod 清单主类入口注册方式事件系统
1.20.1Fabric17fabric-loomfabric.mod.jsonModInitializerRegistry.register + 静态字段fabric-events
1.20.1Forge17ForgeGradlemods.toml@Mod + IEventBusDeferredRegister + RegisterEvent@SubscribeEvent
1.21.XFabric21fabric-loomfabric.mod.jsonModInitializerRegistry.register + 静态字段fabric-events
1.21.1NeoForge21NeoGradle / ModDevGradleneoforge.mods.toml@Mod + IEventBusDeferredRegister(DeferredHolder)@SubscribeEvent
26.1Fabric25fabric-loomfabric.mod.jsonModInitializer(API 收缩期,以 E 系列为准)Registry.registerfabric-events
26.1NeoForge25NeoGradle / ModDevGradleneoforge.mods.toml@Mod + IEventBusDeferredRegister@SubscribeEvent

要点:

  • JDK 严格对应:1.20.1=17、1.21.x=21、26.1=25。装错 JDK 会在 Gradle 构建时类版本报错。
  • 数据生成(datagen):Forge/NeoForge 用 GatherDataEvent,Fabric 用 FabricDataGenerator;生成后记得复制到 src 目录。
  • 官方 GitHub 仓库(模板):A/B/C 用 TutorialMod-1.20.1;D 用 Tutorial-Mod-1.21.1-NeoForge;E 用 Tutorial-Mod-26.1-Fab;F 待开(Tutorial-Mod-26.1-Neo 已建但站内无教程)。

🔁 版本迁移指南(1.20.1 → 1.21.x → 26.1)

Forge → NeoForge(同为 1.20.1/1.21.1)

  1. 包名:net.minecraftforge.* → net.neoforged.*(@Mod、@EventBusSubscriber 所在包变化)。
  2. mod 清单:META-INF/mods.toml → META-INF/neoforge.mods.toml(挂载字段版本号)。
  3. 构建:ForgeGradle → NeoGradle 或 ModDevGradle;Gradle 插件版本与 MC 版本对齐。
  4. 注册:DeferredRegister 语义不变(Fabric 路由用项目自带的 Flamgop 风格注册器时注意迁移到官方方式或 Architectury)。

1.20.1 → 1.21.1(Fabric 内升级)

  • Loom 与 Yarn 映射升级;部分 API(如 Recipe/DataComponents)在 1.21 后变化,按 B 系列章节操作。
  • Fabric 事件回调注册方式不变,但部分类名迁移,以 B 系列对应章节为准。

1.21.1 → 26.1

  • JDK 21 → 25;构建工具链同步升级(Loom/NeoGradle 版本)。
  • 26.1 处于 API 收缩期,先以 E 系列(Fabric 26.1,30 篇已开:#1~#8、#22~#43)为参照,F 系列开更后以 F 为准。
  • 迁移最稳的路径:保留 1.20.1 项目 → 跑通 A 前 15 章 → 新建 1.21.1 工程(D)复刻 → 再上 26.1。

章节锚点:A#51 recipeType、A#52 rei、A#53 网络包、A#54 精炼炉(等级系统)、A#55 罐装机(流体);B#51 recipeType、B#52 rei、B#53 网络包;D#4 方块/物品注册、D#6 网络、D#33 流体。

🧪 标准开发工作流(每次动手都按此顺序)

  1. 环境自检(对应各系列「环境/搭建」章):JDK 版本、Gradle 同步、IDE 运行 runClient。
  2. 设计:先查生态(JEI/REI/EMI、AE2、Create)是否已有现成 API,避免重复造轮子。
  3. 编码:注册(物品/方块/实体/流体)→ 数据生成(模型/配方/标签)→ 资源(贴图/语言文件)。
  4. 运行:gradlew runClient 验证;模组加载失败先看 latest.log 第 10 行起。
  5. 调试:网络包问题用日志打印方向与 handler 线程;渲染问题检查 RenderType。
  6. 发布:Gradle build → mods 文件夹确认 jar 内含 fabric.mod.json/mods.toml。
  7. 验证新环境:换 JDK/版本组合时先跑 besson_tutorial_env 生成清单,再按清单执行。

⚠️ 高频坑点 Top 10

  1. 注册早于启动顺序 → 静态字段初始化时机错,进游戏空指针。
  2. fabric.mod.json/neoforge.mods.toml 的 loader 或版本字段写错 → 游戏不加载模组。
  3. 资源文件没放进 assets/<modid>/ → 模型/贴图全紫黑。
  4. datagen 生成文件后没拷回 src/main/resources → 游戏里内容缺失。
  5. 网络包 handler 在非主线程改世界 → 随机崩溃(必须切主线程处理)。
  6. 事件订阅类忘注册(Forge/NeoForge 的 @Mod 事件总线 / Fabric 回调)→ 逻辑不触发。
  7. 流体/渲染的 RenderType 或模型 JSON 不匹配 → 方块透明/不渲染。
  8. 维度注册顺序错(worldgen 注册器、DimensionType 依赖顺序)→ 传送门进不去。
  9. REI/JEI 插件未注册 → 在配方查看器里看不到新机器/配方。
  10. Mixin 在开发环境用 Yarn 名、打包后要混淆映射名 → 线上失效(用 loom 的 remap 流程)。

📚 生态速查

  • JEI / REI / EMI:配方查看器集成,B、C、D 系列各有专章(recipeType、rei 插件)。
  • AE2 / Create:大型模组 API 对接时先 besson_tutorial_lookup 检索「AE2」「Create」相关章节。
  • Architectury:多 Loader 工程用 Architectury 抽象;站内暂无专章,可对照官方文档 + 系列 B/D 差异。
  • Mixin:核心注入技术,A/B 系列的进阶章节 + 各版本 mixin 配置差异;注意映射(Yarn/官方)差异。

🆘 常见问题(FAQ)

  • 站点总汇页(/2099/12/31/sum/)列表滞后? 正常。以实际文章为准(工具 besson_tutorial_index 的 dataHealth 校验 202 章)。
  • C#22-27、D#13-24 找不到? 本站未发布,非遗漏。B 无 #54(编号跳号)。F 系列(NeoForge 26.1)尚未开更。
  • 最新版本状态:MC 26.2(26.1.1/26.1.2 已发,26.3 快照中);Fabric Loader 0.19.3;NeoForge 26.1 于 2026-03 适配。
  • 工具返回空? 先跑 besson_tutorial_index 看 dataHealth:totalChapters=190 且中文正常 = 数据正常;0 或乱码 = 文件编码损坏,重新安装技能包。
  • 想离线用? 索引是预制的(index_data.json/内嵌),只有 fetch 抓正文需要联网。

🛠 工具链(DSH 插件 / MCP,9 工具)

工具用途何时用
besson_tutorial_lookup关键词检索章节(可传 series/loader/mcVersion 按工程优先)每次动手前先搜
besson_tutorial_index系列/版本/数据健康总览会话开始、排查空结果
besson_tutorial_series列系列全部章节/单章规划学习顺序、查缺号
besson_tutorial_fetch抓一篇文章正文要代码细节时抓 1-2 篇
besson_tutorial_plan按目标生成学习路线(可传 path 让工程自动定系列,如传工程目录路径)新手/进阶/迁移/26.1
besson_tutorial_compare两系列工程/API 差异对比跨版本/跨 Loader 前
besson_tutorial_env环境搭建清单与命令新建工程/换 JDK 前
besson_mod_project本地模组工程体检(加载器/版本/清单/主类)接手旧工程、排查加载失败
besson_mod_scaffold生成工程骨架(gradle/主类/清单)
besson_mod_mapping中文 ↔ 官方映射名对照
besson_mod_migrate跨系列迁移清单(构建/清单/注册/事件差异)升级 MC 版本或换加载器

插件与 MCP 两套实现能力一致;插件随 DSH 预设(besson-tools 行)常驻,MCP 适合接入其他客户端(Claude Desktop/Cursor 等)。

工程优先:调用 besson_tutorial_lookup / besson_tutorial_plan 时传 path(工程目录)或 series,结果会按你的 loader 与 MC 版本优先排序;不传则按目标词推断。

🧰 模组开发辅助(v2.3.0)

除了教学检索,按“开发流程”使用工具链:

阶段动作工具
接手/体检识别工程加载器、MC 版本、Java 工具链、mod 清单、主类入口,输出问题清单besson_mod_project(path 传工程根目录)
选版本按目标选系列并确认缺号/进度besson_tutorial_plan → besson_tutorial_env
迁移输出分步迁移清单(构建→清单→映射→注册→事件→数据生成)besson_mod_migrate(from/to 传系列字母)
动手搜索 → 抓正文 → 按章节实现besson_tutorial_lookup → besson_tutorial_fetch
验收编译报错先对照常见坑与系列差异besson_tutorial_compare + 坑点清单

注意:besson_mod_project 只读取本地文件,不会修改工程;besson_mod_migrate 给的是清单与章节链接,具体代码以章程为准。

📋 教程系列总览

#系列MC 版本Loader章节数状态
AFabric 长线教程计划1.20.1Fabric#1~#55🚧 更新中
BFabric 长线教程计划1.21.XFabric#1~#56✅ 完整
CForge 长线教程计划1.20.1Forge#1~#21、#28~#44🚧 进行中
DNeoForge 长线教程计划1.21.1NeoForge#1~#12、#25~#44🚧 进行中
EFabric 教程计划26.1Fabric#1~#8、#22~#43🆕 新开
FNeoForge 教程计划26.1NeoForge—⏳ 待开

⚠️ 章节编号有跳号: 站点按章节号编号,但存在未发布的空缺章节 (Forge 1.20.1 缺 #22~#27;NeoForge 1.21.1 缺 #13~#24;Fabric 1.21.X 本站无 #54;Fabric 26.1(E)缺 #9~#21)。 如用户提到的章节号落在空缺区间,说明该章节尚未发布,建议推荐相邻章节或提示等待更新。

🌐 社区对照与版本现状(2026-10-03 官方源核实)

本节为对教程站内容的独立核对与建议,来源:Mojang 官方版本清单(piston-meta version manifest v2)、Fabric 官方元数据(meta.fabricmc.net)、NeoForge 官网新闻、Forge 下载页。

① 各版本对应 Java 版本(官方版本清单 javaVersion 字段核实,与教程站写法一致):

MC 版本Java官方运行时组件
1.20.1Java 17java-runtime-gamma
1.21 / 1.21.1Java 21java-runtime-delta
26.1(含 26.1.1 / 26.1.2)Java 25java-runtime-epsilon

② 生态现状(影响选型的事实):

  • 当前 Minecraft 最新正式版为 26.2(26.1.1、26.1.2 补丁已发布,26.3 快照开发中)。教程站主线仍是 26.1,尚未覆盖 26.2 —— 用户若问 26.2 内容,站点暂无对应教程,建议沿用 26.1 教程原理或提示等待。
  • Fabric Loader 当前稳定版为 0.19.3(meta.fabricmc.net 可见,1.20.1 与 26.1 均用此 Loader),技能版本矩阵中“≥0.15”的旧表述已过时。
  • NeoForge 官方已于 2026-03-24 宣布 MC 26.1 适配,但作者 F 系列仍标注“待开” —— 需要 NeoForge 26.1 教程的用户可关注作者后续更新(GitHub 已有 Tutorial-Mod-26.1-Neo 占位仓库)。
  • Forge 官网下载页已列入 26.1/26.2,但作者 Forge 系列只写了 1.20.1。

③ 选系列建议(按用户目标推荐):

用户目标推荐系列说明
完整跟一遍、最稳定B Fabric 1.21.X(56 章)唯一标“完整”的系列
最新版本E Fabric 26.1(20 章)Java 25,内容最新
1.20.1 生态 + 深度内容A Fabric 1.20.1(55 章)含网络包/机器等进阶章节
NeoForge 路线D NeoForge 1.21.1(32 章)1.21.1 是目前 NeoForge 主流
Forge 路线C Forge 1.20.1注意 #22~#27 缺失

④ 站点已知问题汇总(引用时注意纠正):

  • 教程总汇页(sum)部分章节列表滞后:26.1 与粒子部分仍显示“等待开行”、NeoForge 只列到 #12,以实际文章为准。
  • D39 矿物的世界生成,站点页面标题误标为“1.20.1”,实为 1.21.1。
  • 各系列章节号存在空缺:Forge C 缺 #22~#27;NeoForge D 缺 #13~#24;Fabric B 无 #54;Fabric A 的 “S1/S2 补充”实际为 #51/#52。

📄 其他独立文章

标题链接
📖 开篇(博客第一篇文章)→
❓ FAQ(常见问题,全版本通用)→
🟢 前言 1.20 Fabric 长线教程计划→
🐍 Python × Minecraft 粒子特效教程→

A — Fabric 1.20.1 长线教程计划

Loader: Fabric · MC 版本: 1.20.1 · 章节: #1~#55(#51/#52 原称“补充”章节)

#标题链接
1开发环境配置→
2第一个物品→
3创造模式物品栏→
4第一个方块→
5战利品列表→
6配方→
7数据生成→
8食物→
9燃料→
10Tags·标签→
11Jar打包→
12建材类方块→
13DeepSeek IDEA部署→
14工具→
15自定义工具→
16工具信息→
17盔甲→
18全套盔甲效果→
19马铠→
20作物→
21多方块作物→
22村民交易→
23自定义村民→
24声音事件→
25音乐唱片→
26Blockbench模型→
27方块朝向→
28沙发类方块→
29可坐实体→
30光源方块→
31床→
32柱类方块→
33栅栏类方块→
34储物类方块→
35流体→
36木头→
37Gradle配置文件→
38告示牌→
39船→
40树→
41树的世界生成→
42花 & 盆栽花→
43花的世界生成→
44矿物的世界生成→
45耐久合成→
46生物群系→
47结构→
48维度 & 传送门→
49GeckoLib→
50矿机→
51自定义配方类型(原“补充S1”)→
52REI(原“补充S2”)→
53网络包初步→
54精炼炉→
55罐装机→

B — Fabric 1.21.X 长线教程计划

Loader: Fabric · MC 版本: 1.21.X · 章节: #1~#56(本站无 #54)

#标题链接
1开发环境配置→
2第一个物品→
2-1关于1.21.2中物品的注册→
3物品栏→
4第一个方块→
5战利品列表→
6配方→
7数据生成→
8食物→
9Mixin→
10燃烧物→
11探矿器(进阶物品)→
12Tag→
13提示信息→
142D -> 3D(Mixin)→
15建筑类方块→
15-1特殊渲染→
16自定义工具→
17自定义盔甲→
18全套盔甲效果→
19头饰(盔甲衍生案例)→
20作物→
21多方块作物→
22修改战利品列表(非数据包)→
23自定义交易→
24自定义村民→
25自定义声音→
26音乐唱片→
27流体→
28马铠→
29箱子(方块实体)→
30Jar构建→
31方块实体2→
32自定义配方类型→
33REI→
34自定义物品和方块→
35方块朝向(方块状态)→
36可连接方块→
37木头→
38告示牌→
39船→
40树→
41树的世界生成→
42花 & 盆栽花→
43花的世界生成→
44矿物的世界生成→
45耐久合成(配方剩余)→
46锻造台耐久合成(Mixin)→
47生物实体→
48生物实体动画→
49攻击型生物实体→
50生物群系→
51自定义粒子→
52自定义结构→
53维度&传送门→
55附魔→
56升级到1.21.2→

C — Forge 1.20.1 长线教程计划

Loader: Forge · MC 版本: 1.20.1 · 章节: #1~#21、#28~#44(缺 #22~#27)

#标题链接
1开发环境配置→
2第一个物品→
3创造模式物品栏→
4第一个方块→
5战利品列表→
6配方→
7数据生成→
8食物→
9燃料→
10探矿器→
11Tags→
12Jar打包→
13建材类方块→
14工具→
15斧 + 镐(进阶工具)→
16工具信息→
17盔甲→
18全套盔甲增益→
19作物→
20多方块作物→
21村民交易→
28座椅→
29光源方块→
30床→
31柱类方块→
32栅栏类方块→
33流体→
34木头→
35树→
36树的世界生成→
37花 & 盆栽花→
38花的世界生成→
39矿物的世界生成→
40告示牌→
41船→
42结构→
43生物群系→
44维度 & 传送门→

D — NeoForge 1.21.1 长线教程计划

Loader: NeoForge · MC 版本: 1.21.1 · 章节: #1~#12、#25~#44(缺 #13~#24)

#标题链接
1开发环境配置→
2第一个物品→
3创造模式物品栏→
4第一个方块→
5战利品列表→
6配方→
7数据生成→
8食物→
9燃料→
10探矿器→
11Tags→
12Jar打包→
25Blockbench模型→
26方块朝向→
27沙发类方块→
28座椅→
29光源方块→
30床→
31柱类方块→
32栅栏类方块→
33流体→
34木头→
35树→
36树的世界生成→
37花 & 盆栽花→
38花的世界生成→
39矿物的世界生成(站点标题误标为1.20.1,实为1.21.1)→
40告示牌→
41船→
42结构→
43生物群系→
44维度 & 传送门→

E — Fabric 26.1 教程计划

Loader: Fabric · MC 版本: 26.1(自 26.1 起 Minecraft 使用 Java 25)· 章节: #1~#8、#22~#43(缺 #9~#21)

#标题链接
1开发环境配置→
2第一个物品→
3创造模式物品栏→
4第一个方块→
5战利品列表→
6配方→
7数据生成→
8食物→
22自定义交易→
23自定义村民→
24自定义声音→
25音乐唱片→
26Blockbench模型→
27方块朝向→
28沙发类方块→
29座椅→
30光源方块→
31床→
32柱类方块→
33栅栏类方块→
34流体→
35木头→
36树→
37树的世界生成→
38花 & 盆栽花→
39花的世界生成→
40矿物的世界生成→
41结构→
42生物群系→
43维度 & 传送门→

F — NeoForge 26.1 教程计划

Loader: NeoForge · MC 版本: 26.1

⏳ 等待开行(站点「教程总集」页面同样标注为等待开行)


其他资源

GitHub 源码仓库

注意:原 TutorialMod-1.20.1-Fabric 仓库已重命名为 TutorialMod-1.20.1(旧链接会 404)。

标签索引

FA工具

ℹ️ 提示:站点自带的「教程总汇」页面(sum)部分章节列表更新滞后(如 26.1 与粒子部分仍显示“等待开行”、NeoForge 只列到 #12), 以上表格已按站点实际发布的文章核对(2026-10-03),并以实际文章为准。

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall