用户:MashKJo/1.21.1模组开发教程/3.注册

Minecraft中充满了各种游戏元素：物品（Item）、方块（Block）、实体（Entity）、附魔（Enchantment）等等，为了方便地统筹与管理这些游戏元素，注册表（Registry）应运而生。

需要注意的是，注册进注册表的都是游戏对象的类型，即享元对象。如“64个苹果”是一种游戏对象（其实就是ItemStack），而“苹果”是它的类型，即为需要注册进物品注册表的对象。

理解了这一点，我们就可以开始了。

固有注册表与可写注册表

“

游戏内有几十种注册表，它们分别都有不同的作用。这些注册表中，可以分为2类：
固有注册表（Built-in Registry）：游戏硬编码的注册表，内部数据无法通过任何方式修改。这些注册表在各个世界中都通用。
可写注册表（Writable Registry）：游戏读取世界中的数据包获得这些注册表的信息，游戏代码内部并不存在这些注册表的数据。这些注册表与世界绑定，根据世界不同数据也有可能不同。

”

——注册表 - 中文 Minecraft Wiki

显而易见，我们在代码层面能直接操作并添加新元素的，就是固有注册表；至于可写注册表，我们应该以数据包的形式添加新元素。

所有固有注册表都能在BuiltInRegistries类中找到；而对于可写注册表，由于它会随着世界的不同而变动，因此你需要一个Level上下文，通过该Level对象获取一个RegistryAccess：

• 对于服务端世界，请调用ServerLevel#registryAccess。
• 对于客户端世界，请调用Minecraft.getInstance().getConnection().registryAccess()。

请注意：只有当你的客户端实际进入了一个世界（本地存档/远程服务器）的时候，它才会返回一个有效的值，否则会直接报NPE。

而且不同于固有注册表，并非所有可写注册表都会同步所有数据至客户端，请格外注意这一点。

之后，我们就可以调用方法#registryOrThrow来获取我们想要的注册表了，注意到其要求的唯一参数的类型是ResourceKey<? extends Registry<? extends E>>，这个实际上就是确定我们到底想要哪个注册项的注册表——体现为第二层泛型参数。实际上所有注册表都需要这么一个ResourceKey<Registry<?>>（注册表资源键，Registry Resource Key），用于标识它对应的注册项类型。所有注册表资源键（包括固有注册表和可写注册表）都可以在Registries类下找到。

ResourceKey和ResourceLocation

ResourceKey分为两个部分：registryName和location，二者均为ResourceLocation。registryName我们暂且不做过多探讨，读者只需知道所有ResourceKey<Registry<?>>的registryName均为minecraft:root；location则代表该ResourceKey在这一registryName下的“唯一标识符”——是的，别被“location”“ResourceLocation”这种字眼蒙在鼓里了。

ResourceLocation分为两个String：namespace和path，转换成字符串形式即为<namespace>:<path>。默认的namespace即为minecraft，你在模组中自定义ResourceLocation的时候，该用的namespace就是你自己的模组的MODID了。

你可以通过ResourceLocation.fromNamespaceAndPath(namespace, path)来构造出一个ResourceLocation。特别地，如果你想指定namespace为默认值minecraft，可以直接调用#withDefaultNamespace。

ResourceLocation意为“资源路径”，它当然有指代一个具体资源文件的作用——具体地说，一个字符串形式为namespace:path的ResourceLocation实际上在通常情况下，代表一个位于路径assets/namespace/path的资源文件；例如，minecraft:textures/item/apple.png则代表路径为assets/minecraft/textures/item/apple.png的一个文件——即苹果的纹理文件。

当然，上面讲的只是一般的通用情况，实际应用中，Minecraft相关代码基本都会对ResourceLocation做一些中间处理，由此你可以根据当前的代码上下文，省略文件后缀名乃至一部分中间路径。因此读者遇到这种情况时，如果拿不准，最好先看看Minecraft的代码是怎么处理这个ResourceLocation的。

而当ResourceLocation应用于一个ResourceKey的location时，它则是起到“作为唯一标识符”的作用了。例如，物品注册表的资源键的location即为minecraft:item。也正因为这个用途，ResourceLocation在Yarn映射表中的名称为“Identifier”。

遍历注册表

使用for-each循环即可。

注册对象

注册对象资源键

没错，所有注册对象也同样需要一个ResourceKey<?>，以便于在注册表中查找它们。注册对象资源键的泛型参数即为注册对象的类型，如Item、Block等；其registryName为对应注册表资源键的location，而注册对象资源键的location，即为喜闻乐见的通常意义上的“注册名”了，如minecraft:apple、minecraft:barrier等。

ResourceKey<?> key = ResourceKey.create(resourceKey, location);
    //一般是通过这个方式得到某个注册对象的资源键，resourceKey即为注册对象对应注册表的ResouceKey。
    //从这里可以看出，ResourceKey在某种程度上有点“继承”的概念。

另外，ResourceKey是有内部缓存的，也就是说我们可以用==运算符来比较2个ResourceKey。

通过注册对象资源键，我们可以便捷地在注册表中查询注册对象。

Holder

在实际代码中，注册对象多数情况下并非直接出现的，而是被一层Holder<?>包裹起来，如在涉及到有关附魔对象的代码时，一般出现的都是Holder<Enchantment>而非直接的Enchantment。

我们可以直接用Holder#value来获取封装起来的值，也可以通过Holder#direct、Registry#wrapAsHolder、Registry#getHolderOrThrow来获取一个Holder。注意：Holder#direct获取的实际上是一个实现了Holder<?>的record：Holder.Direct，正如其名，我们直接把一个注册对象传入进去，直接包装成一个Holder，对value()的调用时机没有任何限制。然而还存在另一个实现类：Holder.Reference，后两者获取的实际类型便是它，牵扯到注册表的一些机制，它是有点类似于惰性加载的（但加载的时机实际不受Modder控制），所以过早地（指在RegisterEvent发布前）调用它的value()（即forward reference）方法会导致NPE崩游戏，且会提示Trying to access unbounded value...。通过调用#kind可以知道一个Holder的实际类型。

Holder的意义在于更好地对注册对象进行管理，如：判断其是否属于某个标签（Tag）。