注意：本页假定你没有任何编写模组的经验。但是，你应该先会一点 Java 语言以使用 Minecraft（参见“前提”段落）。如果你是从其他模组加载器（如 Forge）来的，可以直接阅读 introduction。

本文档是给模组编写的初学者使用的，比如还不知道 ``BlockState`` 和 ``BlockPos`` 的玩家。如果你有编写数据包的经验并想要将技巧提升到更高水平，或者需要学习面向对象的语言并开启一个有趣的项目，那么本文档适合你。首先从你需要了解的几个概念开始：

- 你必须知道代码编写的基础。如果你从没接触过代码，你应该先知道如何使用代码。这里所说的基础，包括变量、函数、类和方法等，以及一些面向对象的概念，如继承、多态、类型强转。要是不知道，先搜索。 - 你应该要有一些编程语言的经验，例如 Java、C、C++ 和 C#。Java 的语法和 C 系列的比较类似。 - 熟悉 Java 的语法，例如 lambda 方法、泛型（你应该知道这些是什么），以及一些语法糖，这些语法应该会在学习的时候一并遇到。 - 你必须知道如何使用 Internet 查找问题与答案，以及如何在网络论坛或者群里提问求助。

模组编写（Modding）是指的往程序的源代码里面增添或者修改内容，这个程序就是指的 Minecraft。你制作的所有模组都需要增添或者修改内容。

Fabric 是一系列用于编写 Minecraft 模组的工具，包括：

• Fabric Loader– 往基于 Java 的游戏（如 Minecraft）加载修改后的代码的框架。
• Fabric Loom，用于使用 Fabric 编写模组的构建系统
• Fabric 的 语言模块 允许你使用其他的 JVM 语言（例如 Kotlin 或 Scala）来编写你的模组。注意：建议初学者还是先从 Java 开始，因为 Minecraft 就是用这种语言编写的，Java 也是最容易寻求帮助的。
• Fabric API– 一系列能让添加或修改 Minecraft 共同特性更简单的工具。
• Fabric Installer– 将 Fabric Loader 安装到最终用户的 Minecraft 安装的工具。

为了更好的理解 Minecraft 的代码干了什么，当你使用 Fabric 进行模组编写时，你有机会接触到 Minecraft 的源代码。由于 Java 是编译型语言，我们需要反编译来获得我们能够读懂的代码。这一过程会将它从 Java 字节码转变为人类可读的 Java 源代码。然而，为了阻止盗版，Mojang 混淆 了 Minecraft 的代码。这意味着代码中所有的类、方法和字段的名称是随机的。你可以通过 zip 解压工具中打开 Minecraft 的 .jar 文件亲眼看到这一点 —— 所有的文件都会以类似 abc.class 的形式出现。此外，我们无法保证两个版本同一个对象拥有相同的名称 —— 可能上个版本还是 abc，下个版本就是 adb 了。所以这使得在不知道对象名称的情况下修改游戏十分困难，因为我们无法知道不同变量的作用。为了解决这个问题，Fabric 使用了一套映射工具来给所有东西起一个人类可读的名称。

• 中介映射器是一个程序，它将会给予 Minecraft 源码中所有被混淆的对象一个名称，类似 “field_10832” 和 “method_12991()”。关键的是，这个程序将总是给予一个对象相同的名称，所以一个在不同版本之间没有变化的方法将总是会拥有相同的中介名称。

• yarn 是反混淆过程中的最后一步。Yarn 是一个自由的、开源的社区驱动的 Minecraft 中所有方法和类的名称库。当你看 Minecraft 的源代码时，对于任何类、变量或方法，描述其作用的名称都是由 Yarn 编写的。社区中会有人分析并决定为其命名。每次有新的更新或快照出现时，社区就会开始工作，梳理代码，看看有哪些新的对象需要命名。¹⁾

但是，在反编译的 Minecraft 代码库中，并不是所有的对象都被 Yarn 映射了 —— 有时你会看到一些变量仍然有中介名称。如果你弄清楚了它们的作用，你可以为 Yarn 贡献一个名称²⁾。查看 mappings 页面，了解更多关于使用和贡献映射的信息。

Minecraft: Java Edition is a huge project, with years and years of code built on top of each other. It can seem chaotic (because it is), but there are a few key concepts that are (mostly) consistent across the board.

Most “features” (things you might want to add) in the game (blocks, items, screens, entities, chunk generators, etc.) are loaded into Registries when the game is loaded. For example, each Item has a single static instance that is initialized when the game starts, and is put into the item registry. The game uses that instance to determine the properties that ItemStacks (the memory representation of the items you can hold in your inventory) of that item have. If you add something to the game, you probably have to register it. There are exceptions to this rule, however: some features in Minecraft are data-driven, meaning that they can be defined purely in terms of data (as opposed to code). If you've ever wondered why datapacks can add some things but not others, this is why: datapacks can only add data-driven content. Some examples of data-driven content in Minecraft include biomes, textures, *some* chunk generators, and crafting recipes. When a world with a datapack is loaded, the game automatically adds these features to a special transient registry only used while that world is loaded. If you've developed datapacks before, you can integrate datapacks into your mods very easily, which makes some content easier to create. You can even add your own data-drivable content that other people can make datapacks for using Codecs.

Minecraft's processing is split between two threads, commonly called “sides”: the server side, and the client side. The client always runs on a player's computer and handles rendering and input. The server can run either on its own as a dedicated server (what you probably think of as a “Minecraft server”), or, in singleplayer, on the player's computer along with the client as an integrated server. The server handles everything the client doesn't– inventories, the world itself, et cetera. The client and server must agree on certain things: what blocks are in the world, what is inside chests, player position, etc. Since these are handled by the server, it dictates to the client what these values should be, and the client displays them to the person playing the game. Anything handled by the client does not have to be told to the server at all– this includes what blocks and entities look like (resource packs), and how to draw the world (shaders). This is the distinction between clientside mods (like shaders), serverside mods (like those that run minigames), and both-sided mods (those that add things like machines or new blocks and items). It is important to not call client-only code (i.e., relating to rendering) on the server, and server-only code on the client. This is the purpose of the ubiquitous world.isClient() checks that you often see in Minecraft modding.

Once you've achieved the prerequisites and have read this document, it's time to get started! Check out the introduction to learn about the ins and outs of Fabric as a platform, read the setup document to set up an IDE to mod Minecraft, and then head to the items tutorial to add your first item!