注意：本页假定你没有任何编写模组的经验。但是，你应该先会一点 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 安装的工具。

To more easily understand what is going on in Minecraft's code, when you mod with Fabric, you will also have access to Minecraft's source code. Since Java is a compiled language, we need to decompile the code before it can be read. This turns it from Java bytecode into human-readable Java source code. However, to stop piracy, Mojang distributes Minecraft in obfuscated format. This means that all the classes, methods, and fields in the code have randomized names. You can see this for yourself by opening a Minecraft .jar file in a zip extractor tool– all the files have names like abc.class. And what's worse, there's no guarantee that an object will have the same name between two versions– it could be called abc in one version, and abd in the next. This would make modding really, really hard, because without names, it's hard to tell what different variables do. To fix this, Fabric uses a set of mapping tools to give everything a human-readable name.¹⁾

• the intermediary mapper is a program that gives every single object in Minecraft's code a name like “field_10832”, or “method_12991()”. Critically, this program always names each object the same thing. So a method that does not change between versions will always have the same intermediary name.
• yarn is the final step in the deobfuscation process. Yarn is a libre, open-source community-driven library of names for all the methods and classes in Minecraft. When you look at the source code for Minecraft, any class, variable, or method that has a name describing what is does was written with Yarn. Someone in the community analyzed and decided to name it that. Every time a new update or snapshot comes out, the community gets to work combing through the code to see what new objects need names.

Not everything in the Minecraft codebase is mapped with Yarn– sometimes you will see variables that still have intermediary names. If you figure out what they do, you can contribute a name for Yarn.²⁾ Check out the mappings page for more information about using and contributing 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!