Differences

This shows you the differences between two versions of the page.

--- zh_cn:tutorial:primer [2025/11/10 22:03] – sinoaakira
+++ zh_cn:tutorial:primer [2025/11/11 13:04] (current) – sinoaakira
@@ Line 1: / Line 1: @@
-====== Fabric Mod 开发教程 ======
+~~REDIRECT>https://docs.fabricmc.net/zh_cn/develop/getting-started/introduction-to-fabric-and-modding~~
-本文简要介绍一些制作 Fabric Mod 时常用的技巧。
+====== Minecraft Mod 开发入门 ======
-要制作 Minecraft Mod，您通常需要以非标准的方式与 Minecraft 的代码进行交互。
-虽然 Minecraft 对修改的兼容性越来越强，但它本身并非为 Mod 设计。
-与其他 Mod Loader 不同，Fabric Loader 不会覆盖 Minecraft 的类文件来添加更多功能。
+//注意：本文假设您没有任何 Minecraft Mod 制作经验。但是，您需要熟练掌握 Java 编程语言才能修改 Minecraft 源码 (请参阅“准备工作”部分)。如果您是从其他 Mod Loader (例如 Forge) 转到 Fabric，那么本入门指南的内容可能更适合您。//
-相反，它使用 Mixin 库注入代码。
-不过，大多数情况下您并不会直接使用这个库。
-Mixin 可能实现的很糟，不同的 Mixin 有时还会导致冲突。
-因此，Fabric API 已经为您实现了一些常用功能。
-如果 Fabric API 中没有您需要的功能，通常可以在第三方库中找到。
-几乎在所有情况下，使用 Fabric API 或第三方库都比自己实现 Mixin 更可取。
-不过有时候，您根本不需要这些。
+本文旨在为那些对“方块位置” (''BlockPos'')和“方块状态” (''BlockState'')一无所知的人提供 Mod 制作的入门指导。如果您有数据包制作经验并希望提升技能，或者您正在学习面向对象编程语言并希望找到一个有趣的项目来辅助学习，那么本文正适合您。
-虽然 Minecraft 并非为 Mod 设计，但它仍然包含许多无需任何额外修改即可使用的功能。
+首先，让我们从您需要事先了解的内容开始：
-本文将按优先顺序介绍所有可以影响 Minecraft 的方法。
+===== Mod 制作是什么？=====
+Mod 制作是指对程序进行**功能添加**或**修改**的过程；在本文中，该程序是 Minecraft。你制作的所有 Mod 至少都会进行其中一项操作。
-===== 原生 Minecraft API =====
+===== Fabric 是什么？=====
-如果 Minecraft 已经允许你做某件事，就不要重复造轮子。
+Fabric 是一套工具集，可以方便地制作 Fabric Mod 对 Minecraft 进行修改。这些工具包括：
-一个很好的例子是 `<Yarn class_2378>` 类，它允许你在不修改 Minecraft 代码的情况下添加方块和物品。
-Minecraft 也使用 JSON 数据文件来实现各种数据驱动功能。
+  * **Fabric Loader**-- 一个用于将修改后的代码加载到基于 Java 的游戏 (例如 Minecraft) 中的框架。
-您可以将 JSON 文件添加到您的模组中，这些文件随后会通过 Fabric API 注入。
+  * **Fabric Loom**-- 一个专为使用 Fabric 进行 Mod 制作而设计的构建系统。
-例如，方块模型和战利品表都是通过 JSON 文件实现的。
+  * Fabric 的 **编程语言模块** 允许你使用其他 JVM 语言 (例如 Kotlin 或 Scala) 来编写你的 Mod。注意：建议初学者从 Java 入手，因为 Minecraft 就是用 Java 编写的，而且 Java 也是最容易找到相关帮助的 JVM 语言。
+  * **Fabric API**-- 一套可以更轻松地添加或修改某些常见 Minecraft 功能的工具。
+  * **Fabric 安装程序**-- 一款可以将 Fabric Loader 安装到用户的 Minecraft 系统中的工具。
+为了更轻松地理解 Minecraft 的代码，当您使用 Fabric 进行 Mod 制作时，您将能够访问 Minecraft 的“源代码”。由于 Java 是一种编译型语言，我们需要先反编译代码才能阅读。这会将 Java 字节码转换为人类可读的 Java 源代码。然而，为了防止逆向工程，Mojang 以**混淆**格式分发 Minecraft。这意味着代码中的所有类、方法和变量的名称都是随机生成的。您可以用解压缩工具打开一个 Minecraft 的 .jar 文件来验证这一点——所有文件的名称都类似于 ''abc.class''。更糟糕的是，无法保证同一对象在不同版本中的名称相同——它可能在一个版本中名为 ''abc''，而在另一个版本中则可能名为 ''abd''。这将使 Mod 制作变得非常困难，因为没有名称，就很难区分不同变量的作用。为了解决这个问题，Fabric 使用了一套**映射**工具，为所有物品赋予一个易于理解的名称。((注：虽然 Mojang 为所有 Minecraft 版本发布了官方映射表，但未来在 Mod 中使用这些映射的合法性可能会发生变化。Yarn 映射表是自由的，任何人都可以使用，并且足以满足大多数 Mod 制作的需求，因此不建议使用官方映射。))
-===== Fabric API =====
+  * **Intermediary** 映射器是一个程序，它会给 Minecraft 代码中的每个对象赋予一个类似“field_10832”或“method_12991()”的名称。关键在于，这个程序始终为每个对象赋予相同的名称。因此，在不同版本之间保持不变的方法，其 Intermediary 名称也将始终保持不变。
+  * **Yarn** 是反混淆过程的最后一步，它从 Intermediary 映射器的产物为 Minecraft 中的所有方法和类命名。当您查看 Minecraft 的“源代码”时，您发现的任何带有描述其功能名称的类、变量或方法都是 Yarn 生成的。Yarn 社区成员分析并决定了它们的命名。每次发布新的更新或快照版本时，社区都会着手梳理代码，看看哪些新对象需要命名。
-安装到客户端后的 Fabric 本体分为两部分：
+然而，并非 Minecraft 中的所有内容都已被 Yarn 映射——有时您会看到一些变量仍然使用 Intermediary 名称。如果您弄清楚了它们的作用，就可以为 Yarn 贡献一个名称。((关于官方映射的另一点说明：请勿参考官方映射来获取 Yarn 映射方面的帮助。这很可能违反知识产权法——**所有 Yarn 映射都必须是原创的，并且独立于官方映射。**）有关使用和贡献映射的更多信息，请查看 [[mappings]] 页面。))
-  - Fabric Loader，用于加载您的 Mod 并调用 Mod 入口点。
+===== 代码结构 =====
-  - Fabric API，一个可选库，提供一些常用的实用 API。
-为了更快地将 Fabric 移植到较新的 Minecraft 版本，Fabric API 的设计有意保持相对精简。
+Minecraft: Java Edition 是一个巨大的项目，它凝聚了多年来层层叠加的代码。它看起来可能很混乱 (因为它确实很混乱)，但有一些关键概念是 (大概) 贯穿始终的。
-您可以通过查看 GitHub 上的 [[https://github.com/FabricMC/fabric|Fabric 源代码]] 来了解 Fabric API 包含哪些内容。
+==== 注册表 ====
-Fabric API 包含许多常用的事件钩子和通用工具，例如用于网络通信和渲染的工具。
+Minecraft 中的大多数“功能” (你可能想要添加的东西，例如方块、物品、界面、实体、区块生成器等等) 会在游戏加载时加载到对应的注册表中。例如，每个物品 (''Item'') 都有一个静态实例，该实例在游戏启动时初始化并放入物品注册表中。游戏使用该实例来确定该物品的物品栈 (''ItemStack''，您背包中物品的内存表示) 的属性。**如果您向游戏中添加了内容，您很可能需要注册它。** 然而，也有例外：Minecraft 中的某些功能是**数据驱动的**，这意味着它们可以完全用数据（而不是代码）来定义。如果您曾经好奇为什么数据包可以添加某些内容而不能添加其他内容，原因就在这里：数据包只能添加数据驱动的内容。Minecraft 中数据驱动的内容包括生物群系、材质、*某些*区块生成器和合成配方。当加载包含数据包的世界时，游戏会自动将这些特性添加到仅在该世界加载期间使用的特殊临时注册表中。如果您之前开发过数据包，则可以轻松地将数据包集成到您的 Mod 中，从而简化某些内容的创建。您甚至可以添加自己的数据驱动内容，供其他人使用编解码器为其创建数据包。
-===== 第三方 API =====
+==== 端 ====
-由于 Fabric API 的设计初衷是保持精简和专注，因此需要第三方 API 来弥补其功能上的不足。
+Minecraft 的处理分为两个线程，通常称为“端”：服务端和客户端。客户端始终运行在玩家的计算机上，负责渲染和输入。服务端可以独立运行，作为专用服务器 (可能是您印象中的“Minecraft 服务器”)，或者在单人游戏中与客户端一起运行在玩家的计算机上，作为集成服务器。服务端处理客户端不负责的所有事情——物品栏、世界本身等等。
-Mixin 允许任何第三方库以与 Fabric API 相同的方式影响 Minecraft 的代码。
-为了最大程度地减少冲突的可能性，您应该尽可能使用 Fabric API 和第三方 API，而不是编写自己的 Mixin。
-您可以在 Fabric Wiki 上找到一个 [[zh_cn:community:library_mods|第三方库]] 的不完整列表。
+客户端与服务端必须就某些事项达成一致：世界中有哪些方块、箱子里有什么、玩家位置等等。由于这些由服务端处理，因此服务端会将这些值告知客户端，客户端再将这些值显示给玩家。任何由客户端处理的内容都不需要告知服务端——这包括方块和实体的外观 (资源包) 以及如何绘制世界 (着色器)。这就是客户端 Mod (例如着色器)、服务端 Mod (例如运行小游戏的 Mod) 和双端 Mod (例如添加机器、新方块和新物品的 Mod) 之间的区别。
-===== Mixin =====
-最后，你可以使用 Mixin 库。
+重要的是，不要在服务端调用仅供客户端使用的代码 (即与渲染相关的代码)，也不要将仅供服务端使用的代码放在客户端。这就是你在 Minecraft Mod 中经常看到的无处不在的 ''world.isClient()'' 检查的目的。
-Mixin 是一项强大的功能，允许你修改 Minecraft 的任何代码。
-某些 Mixin 可能会导致冲突，但如果使用得当，它们是为你的 Mod 添加独特行为的关键。
-Mixin 有多种类型，大致按优先级排序如下：
+===== 后续步骤 =====
-  * 添加接口
+完成所有准备工作并阅读本文档后，就可以开始了！请查看 [[introduction]] 了解 Fabric 平台的方方面面，阅读 [[setup]] 文档设置 IDE 以进行 Minecraft Mod 制作，然后前往 [[items]] 教程添加您的第一个物品！
-  * 回调注入
-  * 重定向注入
-  * 覆盖
-这并非完整列表，而是一个简要概述。
-此处省略了一些 Mixin 类型。
-==== 添加接口 ====
-这可能是最安全的 Mixin。
-您可以向任何 Minecraft 类添加新的接口实现。
-然后，您可以通过将类强制转换为该接口来访问它。
-这不会改变类的任何属性，只会添加新的功能，因此几乎不可能发生冲突。
-需要注意的是，您注入的函数签名 (函数名 + 参数类型) 必须是唯一的。因此，如果您使用常见的参数类型，请务必给它起一个非常独特的名字。
-==== 回调注入 ====
-Mixin 允许您为现有方法以及该方法内部的特定方法调用添加回调钩子。
-它还允许您拦截并更改方法的返回值，并提前返回。
-回调注入可以叠加，因此不太可能导致 Mod 之间的冲突。
-==== 重定向注入 ====
-Mixin 允许你用自定义代码重定向目标方法中的方法调用或变量访问。
-请谨慎使用重定向，所有模块中，同一个目标调用或变量访问只能重定向一次。
-如果两个模块重定向了相同的值，就会导致冲突。
-请优先考虑回调注入。
-==== 覆盖 ====
-覆盖时务必格外小心。
-Mixin 覆盖会完全替换方法，移除所有现有代码，并可能与该方法上的其他 Mixin 冲突。
-覆盖极有可能不仅与其他模组冲突，还会与 Minecraft 本身冲突。
-您很可能不需要使用覆盖来实现您想要的功能。