索引类型

数据 API 通常会涉及到大量拥有特定含义的数据。在较早的 Minecraft 版本中,某些诸如 1 这样的数字在特定上下文中有着特定含义,比如说在 /give 命令中代表一块石头。在不断的版本迭代后,Minecraft 不再使用这样的数字,而是使用 minecraft:stone 等(含有命名空间的)标识符,使其更有可读性。两大问题随之而来:

  1. 这些数据如何存储,如何重新加载?
  2. 到底有哪些算得上数据?

Sponge 使用了一种基于索引类型( CatalogType )的机制以尝试解决这些问题。

CatalogType 引入了两个天才般的设计。

Sponge 首先为其设计了 CatalogType#getId() 方法,以方便开发者获取(与之相对应的)唯一标识符,从而将其存储到配置文件中,也可通过 GameRegistry#getType(Class, String) 方法还原。实际上你通常不需要亲力亲为,因为你大可让 Sponge 帮你完成 序列化对象 的相关操作。

唯一标识符有时可读性不佳,因此 Sponge 为 CatalogType 设计了另一个方法用于获取可读性较强的名称。你甚至可以检查你的索引类型是否同时是 Translatable 接口的子类型,从而为使用不同语言的玩家提供针对性的名称。

获取索引类型的实例

通过 GameRegistry 类的 GameRegistry#getAllOf(Class) 方法,你可以获取同一索引类型下的所有 CatalogType 类型的实例。这个类同时还提供了一些和 CatalogType 有关的其他方法,甚至还提供了若干方法,用于获取包括但不限于和数据 API 有关的绝大部分类型的生成器。你还可以通过这个类获取其他相关的东西,比如说 VillagerRegistry 和配方等。

在命令中使用索引类型

在和 插件命令 相关的章节中,和 CatalogType 相关的用法已有涉及。只要使用 catalogedElement 就可以在命令中支持针对特定索引类型的所有实例的自动补全。请参阅 参数解析 这一部分以了解更多。

直接获取索引类型的实例

如果开发者不想通过字符串等方式间接获得 CatalogType 的话,比如说在使用默认值等场合,开发者实际上还可以直接引用特定值。不管是 Minecraft 本身还是 Sponge,其代码都提供了直接引用静态字段这一方式。你通常可以在相应的索引类型上找到 CatalogedBy 注解,从而根据其参数值找到相应的静态字段。如果没有找到的话,请检查其父类型及子类型。不过,如果一个索引类型本身包含有太多实例,或者实例本身可以动态增减,那么相应的类可能不会存在。所有可用的索引类型可以在 CatalogTypes 类找到。

警告

不要在自己的代码中使用静态字段直接引用它们,因为这些存储索引类型实例的静态字段往往会在游戏启动时初始化,因此在初始化前往往还只是某个不可用的值。使用这种不可用的值往往会导致代码抛出异常,从而增大修复代码错误的难度。