Differences

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

--- zh_cn:tutorial:primer [2022/10/22 11:24] – created solidblock
+++ zh_cn:tutorial:primer [2025/11/11 13:04] (current) – sinoaakira
@@ Line 1: / Line 1: @@
-====== Minecraft 模组编写基础 ======
+~~REDIRECT>https://docs.fabricmc.net/zh_cn/develop/getting-started/introduction-to-fabric-and-modding~~
-//注意：本页假定你没有任何编写模组的经验。但是，你应该先会一点 Java 语言以使用 Minecraft（参见“前提”段落）。如果你是从其他模组加载器（如 Forge）来的，可以直接阅读 [[introduction]]。//
+====== Minecraft Mod 开发入门 ======
-本文档是给模组编写的初学者使用的，比如还不知道 ``BlockState`` 和 ``BlockPos`` 的玩家。如果你有编写数据包的经验并想要将技巧提升到更高水平，或者需要学习面向对象的语言并开启一个有趣的项目，那么本文档适合你。首先从你需要了解的几个概念开始：
+//注意：本文假设您没有任何 Minecraft Mod 制作经验。但是，您需要熟练掌握 Java 编程语言才能修改 Minecraft 源码 (请参阅“准备工作”部分)。如果您是从其他 Mod Loader (例如 Forge) 转到 Fabric，那么本入门指南的内容可能更适合您。//
-===== Minecraft 模组编写的前提 =====
-- 你必须知道代码编写的基础。如果你从没接触过代码，你应该先知道如何使用代码。这里所说的基础，包括变量、函数、类和方法等，以及一些面向对象的概念，如继承、多态、类型强转。要是不知道，先搜索。
+本文旨在为那些对“方块位置” (''BlockPos'')和“方块状态” (''BlockState'')一无所知的人提供 Mod 制作的入门指导。如果您有数据包制作经验并希望提升技能，或者您正在学习面向对象编程语言并希望找到一个有趣的项目来辅助学习，那么本文正适合您。
-- 你应该要有一些编程语言的经验，例如 Java、C、C++ 和 C#。Java 的语法和 C 系列的比较类似。
+首先，让我们从您需要事先了解的内容开始：
-- 熟悉 Java 的语法，例如 lambda 方法、泛型（你应该知道这些是什么），以及一些语法糖，这些语法应该会在学习的时候一并遇到。
-- 你必须知道如何使用 Internet 查找问题与答案，以及如何在网络论坛或者群里提问求助。
-===== 模组编写是什么？ =====
+===== Mod 制作是什么？=====
-模组编写（Modding）是指的往程序的源代码里面**增添**或者**修改**内容，这个程序就是指的 Minecraft。你制作的所有模组都需要增添或者修改内容。
+Mod 制作是指对程序进行**功能添加**或**修改**的过程；在本文中，该程序是 Minecraft。你制作的所有 Mod 至少都会进行其中一项操作。
-===== Fabric 是什么？ =====
+===== Fabric 是什么？=====
-Fabric 是一系列用于编写 Minecraft 模组的工具，包括：
+Fabric 是一套工具集，可以方便地制作 Fabric Mod 对 Minecraft 进行修改。这些工具包括：
-  * **Fabric Loader**-- 往基于 Java 的游戏（如 Minecraft）加载修改后的代码的框架。
+  * **Fabric Loader**-- 一个用于将修改后的代码加载到基于 Java 的游戏 (例如 Minecraft) 中的框架。
-  * **Fabric Loom**，用于使用 Fabric 编写模组的构建系统
+  * **Fabric Loom**-- 一个专为使用 Fabric 进行 Mod 制作而设计的构建系统。
-  * Fabric 的 **语言模块** 允许你使用其他的 JVM 语言（例如 Kotlin 或 Scala）来编写你的模组。注意：建议初学者还是先从 Java 开始，因为 Minecraft 就是用这种语言编写的，Java 也是最容易寻求帮助的。
+  * Fabric 的 **编程语言模块** 允许你使用其他 JVM 语言 (例如 Kotlin 或 Scala) 来编写你的 Mod。注意：建议初学者从 Java 入手，因为 Minecraft 就是用 Java 编写的，而且 Java 也是最容易找到相关帮助的 JVM 语言。
-  * **Fabric API**-- 一系列能让添加或修改 Minecraft 共同特性更简单的工具。
+  * **Fabric API**-- 一套可以更轻松地添加或修改某些常见 Minecraft 功能的工具。
-  * **Fabric Installer**-- 将 Fabric Loader 安装到最终用户的 Minecraft 安装的工具。
+  * **Fabric 安装程序**-- 一款可以将 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.((Note: While Mojang does publish official mappings for all Minecraft versions, the legality of using these mappings in mods could change in the future. Yarn mappings are libre for everyone to use and sufficient for most modding purposes, so you are discouraged from utilizing the official mappings.))
+为了更轻松地理解 Minecraft 的代码，当您使用 Fabric 进行 Mod 制作时，您将能够访问 Minecraft 的“源代码”。由于 Java 是一种编译型语言，我们需要先反编译代码才能阅读。这会将 Java 字节码转换为人类可读的 Java 源代码。然而，为了防止逆向工程，Mojang 以**混淆**格式分发 Minecraft。这意味着代码中的所有类、方法和变量的名称都是随机生成的。您可以用解压缩工具打开一个 Minecraft 的 .jar 文件来验证这一点——所有文件的名称都类似于 ''abc.class''。更糟糕的是，无法保证同一对象在不同版本中的名称相同——它可能在一个版本中名为 ''abc''，而在另一个版本中则可能名为 ''abd''。这将使 Mod 制作变得非常困难，因为没有名称，就很难区分不同变量的作用。为了解决这个问题，Fabric 使用了一套**映射**工具，为所有物品赋予一个易于理解的名称。((注：虽然 Mojang 为所有 Minecraft 版本发布了官方映射表，但未来在 Mod 中使用这些映射的合法性可能会发生变化。Yarn 映射表是自由的，任何人都可以使用，并且足以满足大多数 Mod 制作的需求，因此不建议使用官方映射。))
-  * 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.
+  * **Intermediary** 映射器是一个程序，它会给 Minecraft 代码中的每个对象赋予一个类似“field_10832”或“method_12991()”的名称。关键在于，这个程序始终为每个对象赋予相同的名称。因此，在不同版本之间保持不变的方法，其 Intermediary 名称也将始终保持不变。
-  * **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.
+  * **Yarn** 是反混淆过程的最后一步，它从 Intermediary 映射器的产物为 Minecraft 中的所有方法和类命名。当您查看 Minecraft 的“源代码”时，您发现的任何带有描述其功能名称的类、变量或方法都是 Yarn 生成的。Yarn 社区成员分析并决定了它们的命名。每次发布新的更新或快照版本时，社区都会着手梳理代码，看看哪些新对象需要命名。
-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.((Another note about official mappings: Do not consult the official mappings for help with Yarn mapping. This is most likely a violation of intellectual property laws-- **all Yarn mappings must be original and independent from Mojang's mappings.**)) Check out the [[mappings]] page for more information about using and contributing mappings.
+然而，并非 Minecraft 中的所有内容都已被 Yarn 映射——有时您会看到一些变量仍然使用 Intermediary 名称。如果您弄清楚了它们的作用，就可以为 Yarn 贡献一个名称。((关于官方映射的另一点说明：请勿参考官方映射来获取 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.
+Minecraft: Java Edition 是一个巨大的项目，它凝聚了多年来层层叠加的代码。它看起来可能很混乱 (因为它确实很混乱)，但有一些关键概念是 (大概) 贯穿始终的。
-=== 注册表 ===
+==== 注册表 ====
-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 ''ItemStack''s (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 中的大多数“功能” (你可能想要添加的东西，例如方块、物品、界面、实体、区块生成器等等) 会在游戏加载时加载到对应的注册表中。例如，每个物品 (''Item'') 都有一个静态实例，该实例在游戏启动时初始化并放入物品注册表中。游戏使用该实例来确定该物品的物品栈 (''ItemStack''，您背包中物品的内存表示) 的属性。**如果您向游戏中添加了内容，您很可能需要注册它。** 然而，也有例外：Minecraft 中的某些功能是**数据驱动的**，这意味着它们可以完全用数据（而不是代码）来定义。如果您曾经好奇为什么数据包可以添加某些内容而不能添加其他内容，原因就在这里：数据包只能添加数据驱动的内容。Minecraft 中数据驱动的内容包括生物群系、材质、*某些*区块生成器和合成配方。当加载包含数据包的世界时，游戏会自动将这些特性添加到仅在该世界加载期间使用的特殊临时注册表中。如果您之前开发过数据包，则可以轻松地将数据包集成到您的 Mod 中，从而简化某些内容的创建。您甚至可以添加自己的数据驱动内容，供其他人使用编解码器为其创建数据包。
-=== 端 ===
+==== 端 ====
-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.
+Minecraft 的处理分为两个线程，通常称为“端”：服务端和客户端。客户端始终运行在玩家的计算机上，负责渲染和输入。服务端可以独立运行，作为专用服务器 (可能是您印象中的“Minecraft 服务器”)，或者在单人游戏中与客户端一起运行在玩家的计算机上，作为集成服务器。服务端处理客户端不负责的所有事情——物品栏、世界本身等等。
-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.
-===== 下一步 =====
+客户端与服务端必须就某些事项达成一致：世界中有哪些方块、箱子里有什么、玩家位置等等。由于这些由服务端处理，因此服务端会将这些值告知客户端，客户端再将这些值显示给玩家。任何由客户端处理的内容都不需要告知服务端——这包括方块和实体的外观 (资源包) 以及如何绘制世界 (着色器)。这就是客户端 Mod (例如着色器)、服务端 Mod (例如运行小游戏的 Mod) 和双端 Mod (例如添加机器、新方块和新物品的 Mod) 之间的区别。
-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!
+重要的是，不要在服务端调用仅供客户端使用的代码 (即与渲染相关的代码)，也不要将仅供服务端使用的代码放在客户端。这就是你在 Minecraft Mod 中经常看到的无处不在的 ''world.isClient()'' 检查的目的。
+===== 后续步骤 =====
+完成所有准备工作并阅读本文档后，就可以开始了！请查看 [[introduction]] 了解 Fabric 平台的方方面面，阅读 [[setup]] 文档设置 IDE 以进行 Minecraft Mod 制作，然后前往 [[items]] 教程添加您的第一个物品！