Skip to content

20 registries ​

一句话定位:给"游戏内容"建立一张统一的表——每个条目有唯一的名字和数字 ID,并负责让客户端与服务端的数字 ID 对得上。

项值
模块 idregistries
Mavennet.ornithemc.osl-gen2:registries:0.4.0+mc14w27a-mc17w46a
端双端
依赖ploceus.dependOslModule('registries', '0.24.0')
依赖的 OSL 模块core, entrypoints, lifecycle-events, executors, networking, networking-impl

本模块提供三件事:注册表框架(Registry 及配套接口,可用来登记你自己的一类内容)、命名与资源键(ResourceKey / NamespacedIdentifier,给每个条目一个稳定名字)、以及数字 ID 同步(SyncedRegistries,让客户端与服务端、存档与当前游戏对同一个内容使用同一个数字 ID)。blocks、items、biomes、entities 等模块都是在它之上包装原版注册表的薄壳。

事件 ​

RegistryEvents ​

Reference: net.ornithemc.osl.registries.api.RegistryEvents

作用:注册表生命周期的三个时间点。你在这里建自己的注册表、往里注册条目,或赶在"冻结"之前做最后一次写入。

需要:只在 mod 的 entrypoint(ModInitializer / init 入口)里静态注册回调,不要在游戏跑起来之后补注册——事件在启动阶段就触发完了。

返回:无。三个字段都是 Event<Runnable>,用 register(() -> { ... }) 挂一个无参回调。

成员作用需要(参数 / 前置条件)返回
INIT_REGISTRIES游戏启动时、原版注册表装载完之后、原版 bootstrap 运行与注册表冻结之前触发;创建注册表(Registries.registerSimple 等)应当写在这里每个进程只在首次 Bootstrap.init() 时触发一次无(void)
BOOTSTRAP_REGISTRIES注册表装载完之后、真正调用各注册表的 bootstrap 之前触发同上;注意原版 bootstrap 可能因类加载而提前跑过无(void)
REGISTRIES_FROZEN所有注册表已被引导、冻结并通过校验之后触发此时再往注册表写东西会抛 IllegalStateException(注册表已冻结)无(void)

触发顺序(据实现):INIT_REGISTRIES → 原版 Bootstrap.init() → BOOTSTRAP_REGISTRIES → 各注册表的 Bootstrap#init → 冻结全部注册表 → 校验(有注册表引导后仍为空则抛 IllegalStateException)→ REGISTRIES_FROZEN。

java
RegistryEvents.INIT_REGISTRIES.register(() -> {
    // 自定义注册表只在这一刻创建
    Registries.registerSimple(RegistryKeys.from("cookie_recipe"), CookieRecipes::init);
});

注册表核心 ​

Registry ​

Reference: net.ornithemc.osl.registries.api.registry.Registry

作用:一张"某类内容的全部已知条目"的表。每个条目同时拥有一个唯一的数字 ID 和一个唯一的 namespaced ID,因此注册表天然是序列化(存档、网络包)的基础。实现类由 OSL 提供(包装原版注册表的实现,或纯 Java 实现),mod 作者不要自己实现这个接口。

需要:通过 Registries 创建(自定义内容),或直接用各模块给你的现成实例(BlockRegistry.REGISTRY、ItemRegistry.REGISTRY 等)。注册必须在注册表冻结之前完成。

返回:查询类方法按名字 / ID / 对象三者互查,详见下表;写操作在冻结后一律抛 IllegalStateException。

成员作用需要(参数 / 前置条件)返回
identifier()这个注册表自身的 ID(如 minecraft:block)—NamespacedIdentifier
get(int id)按数字 ID 查条目id ≥ 0;未注册的 ID 返回 null(纯 Java 实现下越界会抛 IndexOutOfBoundsException)T 或 null
get(ResourceKey key) / get(NamespacedIdentifier id)按名字查条目实际以 key.identifier() 为准(资源键的注册表部分不做校验)T;未命中返回 null
getId(T value)查条目对应的数字 ID条目须已注册int;未注册返回 -1
getKey(T value) / getIdentifier(T value)查条目对应的资源键 / 名字同上ResourceKey<T> / NamespacedIdentifier;未注册返回 null
keySet() / identifierSet()全部资源键 / 全部名字—Set(是否为底层实时视图取决于实现)
freeze()冻结注册表,之后禁止再写入通常在启动阶段由 OSL 调用;defaulted 注册表要求默认值已注册,否则抛 IllegalStateException注册表自身(便于链式调用)
register(Registry registry, ResourceKey key, V value)静态工具:往指定注册表注册一个条目注册表可写;名字与 ID 都不能重复,对象不能重复注册注册后的 value;冲突时抛 IllegalStateException
register(Registry registry, NamespacedIdentifier id, V value)静态工具:按名字注册(内部合成资源键)同上同上
register(Registry registry, int id, ResourceKey key, V value)(已废弃,请改用不带 id 的重载) 手动指定数字 ID 注册同上同上
register(Registry registry, int id, NamespacedIdentifier identifier, V value)(已废弃,请改用不带 id 的重载)同上同上
Registry.Bootstrap#init()嵌套接口:注册表的"引导"回调,在冻结前统一调用,是往注册表里填内容的最后机会由 Registries.registerSimple / registerDefaulted 传入无(void)
java
public static final Registry<CookieRecipe> COOKIE_RECIPE =
    Registries.registerSimple(RegistryKeys.from("cookie_recipe"), CookieRecipes::init);

// 在 CookieRecipes 的静态初始化里填内容
Registry.register(COOKIE_RECIPE, NamespacedIdentifiers.from("example", "chocolate_chip"), new ChocolateChipRecipe());

WritableRegistry ​

Reference: net.ornithemc.osl.registries.api.registry.WritableRegistry

作用:Registry 的"可写"版本,多出两个注册方法。OSL 内部用它实现冻结逻辑;你只有在需要"通用地"接收一个可写注册表(例如写工具方法)时才会碰到它。

需要:拿到一个实际可写的注册表实例(Registries.registerSimple 的返回值实现了它);冻结后调用会抛 IllegalStateException。

返回:注册后的条目。

成员作用需要(参数 / 前置条件)返回
register(ResourceKey key, V value)自动分配下一个数字 ID 并注册未冻结;名字/ID/对象都不重复value
register(int id, ResourceKey key, V value)(已废弃,请改用 register(ResourceKey, Object)) 指定数字 ID 注册同上value

DefaultedRegistry ​

Reference: net.ornithemc.osl.registries.api.registry.DefaultedRegistry

作用:带"默认值"的注册表:查不到任何东西时返回默认条目,而不是 null。原版的方块注册表就是这种(默认是空气),因此 BlockRegistry.REGISTRY 的类型是 DefaultedRegistry<Block>。

需要:用 Registries.registerDefaulted 创建时给出默认值的名字,并务必在冻结前把该名字的条目注册进去,否则冻结会抛 IllegalStateException。

返回:查询方法在未命中时回落到默认值(据实现,getId / getKey / getIdentifier 也会回落到默认条目的 ID / 键 / 名字)。

成员作用需要(参数 / 前置条件)返回
getDefaultIdentifier()默认条目的名字—NamespacedIdentifier

资源键与命名 ​

命名规则总结(来自 core 模块的 NamespacedIdentifier / NamespacedIdentifiers):一个名字写成 namespace:path,缺省命名空间是 minecraft。

  • 命名空间:非空,只允许 a-z、0-9、-、_、.;一般用你的 mod id。
  • 路径:非空,额外允许 /(用于分组,例如 example:food/cookie);不允许大写字母和空格,推荐 snake_case。
  • 不合法时构造/解析会抛运行时异常 NamespacedIdentifierException(解析失败则是 NamespacedIdentifierParseException)。
  • 资源键 = 注册表名 + 条目名两段,两段各自都要满足上述规则;因此同一个条目名可以安全地出现在不同注册表里。

ResourceKey ​

Reference: net.ornithemc.osl.registries.api.registry.ResourceKey

作用:条目的"全限定名"——由"所属注册表 + 注册表内名字"两段组成,例如 (minecraft:block, minecraft:stone)。序列化、跨版本对齐、IdMapper 的重映射都以它为键。

需要:用 ResourceKeys / RegistryKeys 创建;两段都必须是合法的 NamespacedIdentifier(命名空间只允许 [a-z0-9-._],路径额外允许 /,均不能为空;不合法时抛运行时异常 NamespacedIdentifierException)。缺省命名空间是 minecraft。

返回:两个只读访问器。

成员作用需要(参数 / 前置条件)返回
registry()所属注册表的 ID—NamespacedIdentifier
identifier()条目在注册表内的名字—NamespacedIdentifier

ResourceKeys ​

Reference: net.ornithemc.osl.registries.api.registry.ResourceKeys

作用:资源键工厂。所有重载都做了实例缓存:同样的(注册表, 名字)组合拿到的永远是同一个对象,可以直接用 == 或 equals 比较。

需要:参数必须是合法 NamespacedIdentifier;参数顺序不要搞混(注册表在前、条目名在后)。

返回:ResourceKey 实例。

成员作用需要(参数 / 前置条件)返回
from(NamespacedIdentifier identifier)为"名为 identifier 的注册表"造键据实现,注册表部分取根注册表 minecraft:root,条目部分取 identifierResourceKey<T>
from(ResourceKey registry, NamespacedIdentifier identifier)为注册表 registry 里的条目 identifier 造键registry 是该注册表的键ResourceKey<T>
from(NamespacedIdentifier registry, NamespacedIdentifier identifier)同上,但注册表用名字给出—ResourceKey<T>

RegistryKeys ​

Reference: net.ornithemc.osl.registries.api.registry.RegistryKeys

作用:常用注册表的键常量,以及"造注册表键"的快捷方法。写自定义内容时给 Registries.registerSimple 传的就是这种键。

需要:from(String) 使用缺省命名空间 minecraft(想用自己的命名空间请用 from(NamespacedIdentifier))。

返回:注册表键(ResourceKey<Registry<T>>)。

成员作用需要(参数 / 前置条件)返回
BLOCK / ITEM / BIOME方块 / 物品 / 生物群系注册表的键(minecraft:block 等)—ResourceKey<Registry<...>>
BLOCK_ENTITY_TYPE / ENTITY_TYPE方块实体类型 / 实体类型注册表的键1.12.2 上这两个常量声明为裸 ResourceKey(泛型参数在源码里被注掉了),赋值给带泛型的变量需要强转裸 ResourceKey
from(String identifier)用缺省命名空间造注册表键identifier 需符合路径字符规则ResourceKey<Registry<T>>
from(NamespacedIdentifier identifier)用给定名字造注册表键同上ResourceKey<Registry<T>>

LegacyStringIds ​

Reference: net.ornithemc.osl.registries.api.registry.LegacyStringIds

作用:在"老式 PascalCase 字符串 ID"和 namespaced ID 之间转换。原版早期系统(实体名、统计、数据修复)用的就是老式 ID,而 mod 内容没有硬编码对照表,所以这里是通用转换规则,不做词序调整。

需要:只做机械转换,不保证与原版的特殊改名一致(例如原版 LavaSlime 实际对应 minecraft:magma_cube,这类改名是硬编码表,不在本方法能力范围内)。

返回:转换结果字符串 / NamespacedIdentifier。

成员作用需要(参数 / 前置条件)返回
fromIdentifier(NamespacedIdentifier identifier)namespaced ID → 老式 ID—String,形如 TntMinecart(minecraft 命名空间会被省略)或 example.ChocolateChipCookie
fromIdentifier(String namespace, String identifier)同上,分段传入下划线被去掉、每个词首字母大写String
toIdentifier(String id)老式 ID → namespaced ID含 . 时前半段当命名空间,否则用 minecraft;大写字母转小写并在词间插 _,连续大写不插(MinecartTNT → minecraft:minecart_tnt)NamespacedIdentifier

注册表的创建与查找 ​

Registries ​

Reference: net.ornithemc.osl.registries.api.registry.Registries

作用:根注册表("存放所有注册表的注册表")以及创建注册表的工厂。一个注册表就是"一类内容"的容器;注册表本身也被注册,因此可以用键查找。

需要:在 RegistryEvents.INIT_REGISTRIES 的监听器里调用;键不能和已有注册表重名;注册表标识在创建时就固定,之后不能改。

返回:新建的注册表实例(已自动登记到根注册表,其 Bootstrap 会在冻结前被调用一次)。

成员作用需要(参数 / 前置条件)返回
REGISTRY根注册表,持有所有已注册的注册表只读用途;不要往里乱塞东西Registry<? extends Registry<?>>
get(ResourceKey key)按键查注册表实际以 key.identifier() 在根注册表里查找Registry<T>;不存在返回 null
registerSimple(ResourceKey key, Registry.Bootstrap bootstrap)创建一个普通(可写、无默认值)注册表名字不与已有注册表冲突;bootstrap 不能为 null(引导时会调用 init())新建的 Registry<T>
registerDefaulted(ResourceKey key, NamespacedIdentifier defaultIdentifier, Registry.Bootstrap bootstrap)创建一个带默认值的注册表同上;默认条目必须在冻结前注册,否则冻结抛 IllegalStateException新建的 DefaultedRegistry<T>

引导阶段的失败行为(据实现):某个 Bootstrap#init() 抛异常会被包装成 IllegalStateException("error while bootstrapping registry ...", cause);引导结束后仍为空的注册表(keySet() 为空)会让启动直接失败,抛 IllegalStateException("Registry ... is empty after bootstrap!")。

通用数字 ID 映射 ​

IdMap ​

Reference: net.ornithemc.osl.registries.api.registry.IdMap

作用:一个简单的双向 int ↔ 对象 映射,可以手动分配 ID,也可以自动分配(取当前最大 ID + 1)。它是"轻量版注册表",适合给不需要完整注册表语义的内部结构编号。1.12.2 上 OSL 自身没有使用它(旧版本的 blockstates 用得多),但作为公开工具保留。

需要:ID 必须 ≥ 0;ID 唯一,但对象唯一性不保证(同一个对象可以挂多个 ID,此时 getId 返回其中任意一个)。

返回:见下表;查不到时 getId 返回 -1、get 返回 null。

成员作用需要(参数 / 前置条件)返回
put(T value)用下一个可用 ID 放入对象—传入的对象
put(T value, int id)用指定 ID 放入对象id ≥ 0,否则抛 IllegalArgumentException传入的对象
getId(T value)查对象的 ID—int;不存在返回 -1
get(int id)查 ID 对应的对象—T 或 null
has(T value)是否登记过该对象—boolean
iterator()遍历所有对象(按 ID)实现自 IterableIterator<T>
clear()清空并重置 ID 计数—无(void)

ID 同步(Registry Sync) ​

为什么需要:游戏用数字 ID 而不是名字来序列化内容(存档更小、网络包更省)。这些 ID 是自动分配的,通常就是"注册顺序"。也就是说,同一个 mod 包在服务端和客户端、在两个不同的存档里,可能拿到不同的 ID。一旦不一致,客户端就会把"石头"读成别的方块、把物品 ID 指错,轻则错乱,重则崩溃或写坏存档。

OSL 做了什么:给注册表算出一张"老 ID → 新 ID"的对照表,然后把每个注册表的数字 ID 重排成目标端(服务端 / 存档)的 ID,并且把所有"以数字 ID 为下标或键"的结构(统计数组、方块状态表、模型缓存、实体名列表等)一起搬移。玩家登录时服务端把对照表发给客户端(走 networking 的自定义通道),客户端应用后与服务器保持一致;断开多人连接时回滚;单人游戏与存档则通过存档目录里的 registry_mappings.dat 持久化。

mod 作者通常要不要关心:多数情况下不用。blocks / items / biomes / entities 这四个模块已经在 INIT_REGISTRIES 阶段替你把对应注册表登记进了同步,并挂好了内置的 mapper / fixer。只有以下两种情况才需要你动手:① 你自己建的注册表,其数字 ID 会被写进存档或网络包;② 你自己维护了一张"以数字 ID 为下标/键"的表,需要跟着一起重排。

SyncedRegistries ​

Reference: net.ornithemc.osl.registries.api.registry.SyncedRegistries

作用:ID 同步的公开入口:声明"这个注册表要同步",并为它挂上额外的 ID 搬运工(IdMapper)与修补器(IdFixer)。

需要:在 RegistryEvents.INIT_REGISTRIES 的监听器里调用(各内置模块正是这么做的)。注册表必须存在且内部可清空(OSL 自己包装/创建的注册表满足;随便传一个第三方实现会抛 IllegalArgumentException)。同一个注册表不能重复声明同步;同一个注册表下 mapper / fixer 的名字不能重复。对未同步的注册表调用 registerMapper / registerFixer 会抛 IllegalArgumentException。

返回:无(均为 void)。

成员作用需要(参数 / 前置条件)返回
register(ResourceKey registry)声明该注册表参与同步(会自动为它注册一个重排注册表本身的 mapper)注册表已用 Registries 创建/登记;未重复声明无(void);未知注册表 / 不可清空 / 重复声明抛 IllegalArgumentException
registerMapper(ResourceKey registry, NamespacedIdentifier identifier, IdMapper mapper)为已同步的注册表挂一个 ID 搬运工该注册表已 register;identifier 在该注册表下唯一(仅用于日志与去重)无(void)
registerFixer(ResourceKey registry, NamespacedIdentifier identifier, IdFixer fixer)为已同步的注册表挂一个"修 ID"回调同上无(void)
java
RegistryEvents.INIT_REGISTRIES.register(() -> {
    SyncedRegistries.register(MY_REGISTRY_KEY);
    SyncedRegistries.registerMapper(MY_REGISTRY_KEY,
        NamespacedIdentifiers.from("example", "my_table"), ArrayMapper.of(() -> MY_TABLE, a -> MY_TABLE = a));
});

RegistryMappings ​

Reference: net.ornithemc.osl.registries.api.registry.sync.RegistryMappings

作用:一张"老 ID ↔ 新 ID"对照表,OSL 在搬运时把它传给你的 mapper / fixer。表里既有按条目名查的映射,也有按老 ID 查的映射。

需要:你只读它,不要修改;映射方向请注意——remap 是"老 → 新",unmap 是"新 → 老",名字里的"新/老"以"目标端使用的新 ID"为准。

返回:int;查不到返回 -1。映射结果是负数时表示"该条目在目标端不存在",mapper 通常应据此丢弃这个下标/键。

成员作用需要(参数 / 前置条件)返回
remap(ResourceKey key)按名字取新 ID名字属于当前同步的注册表int(-1 表示未知)
remap(int id)按老 ID 取新 IDid 是本地当前 IDint(-1 表示未知)
unmap(ResourceKey key)按名字取老 ID同上int
unmap(int id)按新 ID 取老 IDid 是目标端 IDint

IdMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.IdMapper

作用:一个"会跟着 ID 一起搬家"的结构(数组、列表、以 ID 为键的 map,或存了 ID 字段的对象)。OSL 提供了 8 个实现可直接用;你也可以为自己的结构实现它。

需要:由你实现时,apply 要先把旧内容备份(否则 undo 无法还原),再按 mappings.remap(oldId) 把值搬到新下标/新键,newId < 0 的条目丢弃;undo 要在没 apply 过时安全地什么都不做。

返回:无(均为 void)。

成员作用需要(参数 / 前置条件)返回
apply(RegistryMappings mappings)按对照表把内容搬到新 ID结构当前持有的是"本地老 ID"排布无(void)
undo(RegistryMappings mappings)撤销上一次 apply,恢复原排布之前确实 apply 过(实现里用标记位判断)无(void)

IdFixer ​

Reference: net.ornithemc.osl.registries.api.registry.sync.IdFixer

作用:当 ID 可以"推导或重新生成"、用 mapper 反而多余甚至不可行时,用它做修补。典型例子:方块状态表(可以由方块 ID + metadata 重新算出来)、旧版本里存了 ID 字段的对象。

需要:在注册表被重排之后被调用;实现里要按映射后的状态重新生成内容,而不是依赖旧内容。

返回:无(void)。

成员作用需要(参数 / 前置条件)返回
apply()重新计算/修正绑定的结构绑定的注册表已经完成 ID 重排无(void)

ID 搬运工(IdMapper 的内置实现) ​

ArrayMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.ArrayMapper

作用:给"对象数组 T[],用 ID 当下标"的结构做搬移(null 视为空槽)。方块/物品的统计数组就是这种结构。

需要:数组可能为 null 或需要扩容,所以用 Supplier 取、Consumer 存,而不是直接持有数组引用(字段被替换后仍能工作)。apply 会先备份原数组,undo 用备份还原。

返回:搬移结果写回你提供的数组字段;方法本身无返回值。

成员作用需要(参数 / 前置条件)返回
of(Supplier getter, Consumer setter)用取值/存值回调包装一个数组字段getter 不能返回 nullArrayMapper
of(DynamicArray array)用 DynamicArray 包装—ArrayMapper
apply(RegistryMappings mappings)把非 null 的值从老下标搬到新下标见 IdMapper无(void)
undo(RegistryMappings mappings)还原到搬移前的数组之前 apply 过无(void)

BooleanArrayMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.BooleanArrayMapper

作用:同上,但针对 boolean[](false 当作空槽)。原版的"是否已解锁配方 / 是否已发现"之类的标记数组会用到。

需要:因为 boolean 没有 null,搬移时每个下标的值都会被复制(包括 false)。

返回:写回你提供的数组字段;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(Supplier getter, Consumer setter)包装 boolean[] 字段—BooleanArrayMapper
of(DynamicBooleanArray array)用 DynamicBooleanArray 包装—BooleanArrayMapper
apply(RegistryMappings mappings) / undo(RegistryMappings mappings)搬移 / 还原同 ArrayMapper无(void)

IntArrayMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.IntArrayMapper

作用:针对 int[](0 当作空槽)。

需要:与布尔版本一样,每个下标的值都会被复制(包括 0),所以 0 语义不是"空缺"的结构要小心。

返回:写回你提供的数组字段;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(Supplier getter, Consumer setter)包装 int[] 字段—IntArrayMapper
of(DynamicIntArray array)用 DynamicIntArray 包装—IntArrayMapper
apply(RegistryMappings mappings) / undo(RegistryMappings mappings)搬移 / 还原同 ArrayMapper无(void)

IntegerMapMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.IntegerMapMapper

作用:给 Map<Integer, T>(以 ID 为键)做搬移。apply 备份整张表,undo 用备份还原。

需要:map 必须是可清空、可写的;键必须真的是 ID(不是打包过的复合键,那种要自己写 mapper)。

返回:写回原 map;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(Map registry)包装一个 Map<Integer, ?>传入的 map 会被原地修改IntegerMapMapper
apply(RegistryMappings mappings) / undo(RegistryMappings mappings)搬移 / 还原同 IdMapper无(void)

Int2ObjectMapMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.Int2ObjectMapMapper

作用:fastutil Int2ObjectMap 版本的"以 ID 为键"搬移(物品模型缓存等用的就是它)。

需要:map 必须可清空、可写;同样会原地修改传入的 map。

返回:写回原 map;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(Int2ObjectMap registry)包装一个 fastutil map传引用,不复制Int2ObjectMapMapper
apply(RegistryMappings mappings) / undo(RegistryMappings mappings)搬移 / 还原(用备份)同 IdMapper无(void)

DynamicInt2ObjectMapMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.DynamicInt2ObjectMapMapper

作用:给"内容会随游戏进程变化"的 fastutil map 做搬移(例如资源包重载就会重建的模型缓存)。它不做备份,undo 靠反向映射当场算回去。

需要:适合内容会变的 map;因为不备份,undo 之前如果内容被大改,结果以当前内容为准。

返回:写回原 map;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(Int2ObjectMap cache)包装一个动态 map传引用,不复制DynamicInt2ObjectMapMapper
apply(RegistryMappings mappings)用 remap 把所有键换成新 ID键须是纯 ID无(void)
undo(RegistryMappings mappings)用 unmap 把键换回去之前 apply 过无(void)

ListMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.ListMapper

作用:给 List<T>(以 ID 为下标)做搬移,必要时用 null 补齐空档(例如原版的实体名列表 Entities.NAMES)。

需要:列表必须可清空、可写、允许 null 元素;null 元素视为空槽,不会被搬移。

返回:写回原 list;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(List registry)包装一个 List<?>传引用,不复制ListMapper
apply(RegistryMappings mappings) / undo(RegistryMappings mappings)搬移 / 还原(用备份)同 IdMapper无(void)

Id2ObjectBiMapMapper ​

Reference: net.ornithemc.osl.registries.api.registry.sync.Id2ObjectBiMapMapper

作用:给原版 net.minecraft.util.Id2ObjectBiMap(ID ↔ 对象双向表)做搬移。方块状态表、生物群系变体表、方块/物品颜色表都是这种结构。

需要:Id2ObjectBiMap 允许重复值,所以不能靠遍历值来枚举全部 ID——实现里先按 ID 集合把 id → 对象 全部复制到备份表,再清空原表按对照表重建(undo 用备份还原)。

返回:写回原 map;方法无返回值。

成员作用需要(参数 / 前置条件)返回
of(Id2ObjectBiMap registry)包装一个原版双向表传引用,不复制Id2ObjectBiMapMapper
apply(RegistryMappings mappings) / undo(RegistryMappings mappings)搬移 / 还原(用备份)同 IdMapper无(void)

动态数组工具 ​

这三个类本身不参与同步,只是给上表的数组搬运工提供"字段里的数组可以被扩容/替换"的抽象:它们不保存数组引用,而是每次通过 Supplier 取、Consumer 存,所以数组字段被整体替换后依然有效。

DynamicArray ​

Reference: net.ornithemc.osl.registries.api.registry.sync.DynamicArray

作用:把"存在字段里的 T[]"包装成可按需增长的对象数组视图。

需要:getter 必须始终返回非 null 数组;写入越界下标前会自动扩容(按当前长度每次增长 50% 直到够用,因此实际容量可能大于请求值)。length() 指的是"最后一个非 null 元素的下标 + 1",不是容量。

返回:读/写/扩容结果见下表。

成员作用需要(参数 / 前置条件)返回
of(int capacity)造一个自带独立数组的实例(常用于备份)capacity ≥ 0DynamicArray<T>
of(Supplier getter, Consumer setter)包装一个真实字段getter 非空返回DynamicArray<T>
capacity() / length()当前数组长度 / 有效长度—int
get(int index) / set(int index, T value)按下标读写(不检查越界)—读到 T,set 返回被写入的值
add(int index, T value)写入并自动扩容index ≥ 0写入的值
addAll(DynamicArray array)把另一个数组的内容复制进来(从头覆盖)两个数组元素类型兼容无(void)
clear()全部填 null—无(void)
grow(int capacity)确保容量至少为 capacity—无(void)(会调用 setter 换数组)
length(T[] array) / grow(T[] array, int capacity)静态工具:算有效长度 / 扩容并返回(可能返回新数组)—int / T[]

DynamicBooleanArray ​

Reference: net.ornithemc.osl.registries.api.registry.sync.DynamicBooleanArray

作用:DynamicArray 的 boolean[] 版本(false 作空值)。

需要:无 null 概念,length() 就等于容量;clear() 会全部填 false。

返回:见下表。

成员作用需要(参数 / 前置条件)返回
of(int capacity) / of(Supplier getter, Consumer setter)造独立实例 / 包装字段同 DynamicArrayDynamicBooleanArray
capacity() / length()容量(两者相同)—int
get(int index) / set(int index, boolean value)按下标读写—boolean
add(int index, boolean value)写入并自动扩容index ≥ 0写入的值
addAll(DynamicBooleanArray array) / clear() / grow(int capacity)复制内容 / 全填 false / 扩容—无(void)
grow(boolean[] array, int capacity)静态扩容工具—boolean[]

DynamicIntArray ​

Reference: net.ornithemc.osl.registries.api.registry.sync.DynamicIntArray

作用:DynamicArray 的 int[] 版本(0 作空值)。

需要:无 null 概念,length() 等于容量;clear() 全部填 0。

返回:见下表。

成员作用需要(参数 / 前置条件)返回
of(int capacity) / of(Supplier getter, Consumer setter)造独立实例 / 包装字段同 DynamicArrayDynamicIntArray
capacity() / length()容量(两者相同)—int
get(int index) / set(int index, int value)按下标读写—int
add(int index, int value)写入并自动扩容index ≥ 0写入的值
addAll(DynamicIntArray array) / clear() / grow(int capacity)复制内容 / 全填 0 / 扩容—无(void)
grow(int[] array, int capacity)静态扩容工具—int[]

基于 Ornithe Standard Libraries 0.24.0(MC 1.12.2)源码整理