Skip to content

01 core ​

一句话定位:OSL 的底座模块——事件容器、二进制/JSON 读写包装、注册表骨架、跨版本中立 ID 与一批工具类型(坐标、方向、拓扑排序、函数式接口)。

项值
模块 idcore
Mavennet.ornithemc.osl-gen2:core:0.13.0+mc14w27a-mc1.14.4
模块版本0.13.0(libraries/core/gradle.properties)
端双端(api 只有一套,客户端/服务端通用)
依赖ploceus.dependOslModule('core', '0.13.0')

core 本身不注册任何游戏内容、不做渲染、不碰网络,它只提供其它 OSL 模块和 mod 自己反复需要的基础设施:一个不依赖 Minecraft 的极小事件容器、把 DataInputStream / DataOutputStream 与 quilt-parsers 的 JSON 读写包成"一条流 / 一个文件"的助手、一组键值注册表类型,以及若干被重写成跨版本稳定形态的工具类(原版这些类型在不同 MC 版本里名字和行为都不一样)。

模块内的分工大致是:

  • core.api.events:事件容器 Event,纯 Java,可以在任意版本、任意线程上用。
  • core.api.io / core.api.json:序列化脚手架,OSL 的 config / resource-loader / datagen 等模块都建在它上面。
  • core.api.registry:RegistryKey + Registry 的最小键值注册表;另外三个带数字 ID 的注册表已废弃。
  • core.api.util:NamespacedIdentifier(跨版本中立的 Identifier)、BlockPos、Direction、Unit、三参数函数式接口、TopoSort。

MC 1.12.2 说明:本文档描述的全部 api 都来自共享源码 libraries/core/src/main/java。1.12.2 使用的子工程 core-mc14w27a-mc1.14.4 里只有 impl/mixin(给原版 Identifier 注入扩展方法)和一个 impl 工具类,没有额外的 api 类型,所以 core 的 api 在 1.12.2 上是"全套可用、没有版本缺口"的状态。

事件:core.api.events ​

Event<T> ​

Reference: net.ornithemc.osl.core.api.events.Event<T>

作用:一个极简的事件容器。它内部只有"一个监听器 List<T> 和一个调用器 T",T 是任意函数式接口(Runnable、Consumer、Function、OSL 的 TriConsumer / TriFunction 等)。mod 的常见用法是:自己声明一个 public static final Event<...> 字段,把 register(...) 暴露给别的 mod,触发时调用 invoker().xxx(...)。因为它完全不引用 Minecraft 类型,所以不用担心版本差异,也可以在初始化早期使用。

需要:创建时用 Event.of(...) 或本节的静态工厂给出"怎么把监听器列表变成调用器";注册的监听器必须与 T 一致(只有编译期保证)。没有取消注册 / 移除监听器的 API;内部 ArrayList 没有同步,注册与触发并发执行属于未定义行为。

返回:invoker() 返回调用器对象,它每次被调用时才现场遍历当前监听器列表——所以"先取调用器、后注册监听器"依然能触发到新监听器(虽然 register 会把缓存的调用器字段置空)。

成员作用需要(参数 / 前置条件)返回
of(Function<List<T>, T> invokerFactory)自定义"监听器列表 → 调用器"的构造方式invokerFactory 在第一次 invoker() 时被调用一次,参数是事件内部的可变监听器列表,不要把它长期保存新的 Event<T>
runnable()广播型(无参、无返回)无Event<Runnable>
consumer()广播型(1 个参数)无Event<Consumer<T>>
biConsumer()广播型(2 个参数)无Event<BiConsumer<T, U>>
triConsumer()广播型(3 个参数,用 core.api.util.function.TriConsumer)无Event<TriConsumer<T, U, V>>
functionFirst() / biFunctionFirst() / triFunctionFirst()取值型:按注册顺序询问监听器,拿到第一个结果就停止监听器返回值不能是 null(见"null 语义")对应的 Event<Function/BiFunction/TriFunction>
functionFirstNonNull() / biFunctionFirstNonNull()取值型(名字带 NonNull)同上同上——源码与不带 NonNull 的版本实现完全相同
triFunctionFirstNonNull()取值型:按顺序问,跳过返回 null 的监听器无Event<TriFunction<T, U, V, R>>
functionAny() / biFunctionAny() / triFunctionAny()取值型:任意一个监听器的结果即可(Stream#findAny())同 ...First,不能返回 null对应的 Event<Function/BiFunction/TriFunction>
functionAnyNonNull() / biFunctionAnyNonNull()取值型(名字带 NonNull)同上同上——同样与不带 NonNull 的版本实现相同
triFunctionAnyNonNull()取值型:任意顺序,跳过 null无Event<TriFunction<T, U, V, R>>
register(T listener)追加一个监听器listener 非 null(不做检查)无(void)
invoker()取调用器;首次调用时用 invokerFactory 现场构造并缓存无T(调用器)

触发语义速查(重点) ​

语义工厂说明
广播、不短路runnable、consumer、biConsumer、triConsumer触发一次就把所有监听器按注册顺序跑一遍,没有返回值、无法"打断"。监听器抛异常会直接冒到触发方,其后的监听器不再执行(源码没有 try/catch)
顺序取第一个值(短路)functionFirst 系用 listeners.stream().map(...).findFirst():按注册顺序询问,命中即停
任意取一个值(短路)functionAny 系用 findAny()。源码里的流是顺序流,实际结果与 findFirst 相同,但语义上不保证顺序,不要依赖"一定是先注册的那个"
收集全部返回值—本类不提供。需要"所有监听器的结果"时自己写 Event.of(listeners -> (...) -> { ... })

null 语义(与名字不完全一致) ​

  • 只有 triFunctionFirstNonNull 与 triFunctionAnyNonNull 会真正用 filter(Objects::nonNull) 跳过返回 null 的监听器。
  • 其余所有 ...First / ...Any / ...FirstNonNull / ...AnyNonNull 都不过滤 null:它们把"第一个被问到的监听器的返回值"直接交给 findFirst() / findAny(),而这两个方法不接受 null 元素,因此若被取到的那一次返回 null,会抛 NullPointerException(哪怕后面的监听器能返回非 null)。
  • 因此写"取值型"监听器时,要么永远返回非 null,要么改用 triFunction*NonNull(3 参),要么自己用 Event.of 实现过滤。
  • 源码中若干 *NonNull 工厂的注释写的是 "Cancels after any listener returns non-null",与实现不符;以实现为准(见上)。

示例 ​

java
public final class MyModEvents {
    /** 广播型:给别处挂"每 tick 做点什么" */
    public static final Event<Runnable> TICK = Event.runnable();
    /** 取值型:第一个返回非 null 的监听器决定结果(用 3 参 NonNull 变体才安全) */
    public static final Event<TriFunction<World, Integer, Integer, String>> LOOKUP = Event.triFunctionFirstNonNull();
}

// 注册
MyModEvents.TICK.register(() -> counter++);

// 触发
MyModEvents.TICK.invoker().run();
String r = MyModEvents.LOOKUP.invoker().apply(world, x, z);

二进制读写:core.api.io ​

DataStream ​

Reference: net.ornithemc.osl.core.api.io.DataStream

作用:把 DataInputStream / DataOutputStream 包成一个对象,同时实现 DataInput 与 DataOutput。这样"写包 / 读包"两侧的代码可以共用同一个类型,也能把"只读"或"只写"的意图显式表达出来。

需要:用静态工厂创建,构造函数是私有的。同一个实例要么只读、要么只写:对着只读实例调写方法抛 IOException("not writing!"),对着只写实例调读方法抛 IOException("not reading!")。

返回:写方法全部 void;读方法返回对应基本类型;所有方法都声明 throws IOException(透传底层流)。

成员作用需要(参数 / 前置条件)返回
output(OutputStream)新建只写 DataStream(内部 new DataOutputStream(output))output 非 nullDataStream
input(InputStream)新建只读 DataStream(内部 new DataInputStream(input))input 非 nullDataStream
wrapOutput(DataOutputStream) / wrapInput(DataInputStream)包装已有的数据流(不再多套一层)传入的流需要你自己关闭DataStream
writeBoolean / writeByte / writeShort / writeChar / writeInt / writeLong / writeFloat / writeDouble按 Java 的大端定长格式写基本类型只写流无(void)
write(int) / write(byte[]) / write(byte[], int off, int len)原样写字节同上无(void)
writeBytes(String) / writeChars(String) / writeUTF(String)写字符串:writeBytes 每字符取低 8 位、writeChars 写 UTF-16 单元、writeUTF 写 modified UTF-8(最多 65535 字节,超长抛 UTFDataFormatException)同上无(void)
readFully(byte[]) / readFully(byte[], int off, int len)读满指定长度,读不满抛 EOFException只读流无(void)
skipBytes(int n)跳过若干字节同上实际跳过的字节数
readBoolean / readByte / readUnsignedByte / readShort / readUnsignedShort / readChar / readInt / readLong / readFloat / readDouble读基本类型,格式必须与写端一致同上对应类型(如 readByte 返回 byte、readUnsignedByte 返回 int)
readLine()读一行(旧的字节语义:逐字节读到换行/回车)同上String;流结束返回 null
readUTF()读 modified UTF-8 字符串(与 writeUTF 配对)同上String

DataStream 只是包装:不缓冲、不关闭底层流,生命周期由调用方负责。

JSON 文件:core.api.json ​

JsonFile ​

Reference: net.ornithemc.osl.core.api.json.JsonFile

作用:把 quilt-parsers 的 JsonWriter / JsonReader 包装成"一个文件对象 + 一串链式调用"。它固定把整个文件当成一个 JSON 对象:write() / read() 自动 beginObject(),close() 自动 endObject(),中间用 writeName / writeString / readName / readString 之类按顺序操作。

需要:构造时给 Path;先调用 write()(覆盖写)或 read() 之一;必须 close()(实现 Closeable),否则文件没有收尾、JSON 不完整,流也不会关闭。两个打开方法不能在同一实例上重复调用(抛 IOException("already writing!") / "already reading!"),也不允许边读边写。

返回:写操作全部返回 this(便于链式),读操作返回读到的值;所有方法声明 throws IOException。

成员作用需要(参数 / 前置条件)返回
JsonFile(Path path)绑定文件路径(此时尚未打开)父目录需已存在(是否自动创建目录:源码未明确说明)新实例
write()打开写入器并开始写顶层对象尚未 write() / read()无(void)
read()打开读取器并开始读顶层对象尚未 write() / read()无(void)
close()结束顶层对象并关闭流,之后不能再读写已经 write() 或 read()无(void)
writeName(String name)写下一个属性名正在写、且当前位于对象内JsonFile
writeObject(JsonFileConsumer object) / writeObject(String name, JsonFileConsumer object)写一个嵌套对象;带 name 的版本等价于 writeName(name).writeObject(object)同上JsonFile
writeArray(JsonFileConsumer... elements) / writeArray(String name, JsonFileConsumer... elements)写一个数组,每个回调负责写一个元素同上JsonFile
writeString(String value) / writeString(String name, String value)写字符串值同上JsonFile
writeBoolean(boolean) / writeBoolean(Boolean)(各带 name 重载)写布尔值同上JsonFile
writeNumber(Number) / writeDouble(double) / writeLong(long)(各带 name 重载)写数值同上JsonFile
writeNull() / writeNull(String name)写 null同上JsonFile
writeJson(String value) / writeJson(String name, String value)把一段已序列化好的 JSON 文本原样写进去同上;value 必须是合法 JSONJsonFile
hasNext()当前对象/数组里是否还有下一个成员正在读boolean
peek()预读下一个 token同上JsonToken
readName()读下一个属性名同上String
readName(String name)读下一个属性名并与给定名字比较,不等就抛异常名字必须与文件中的键完全一致JsonFile;不匹配抛 IOException
readObject(JsonFileConsumer object) / readObject(String name, JsonFileConsumer object)读一个嵌套对象同上无(void)
readArray(JsonFileConsumer... elements) / readArray(String name, JsonFileConsumer... elements)读一个数组,按回调个数逐个读元素回调数量必须与元素数量一致无(void)
readString() / readString(String name)读字符串同上String
readBoolean() / readBoolean(String name)读布尔同上boolean
readNumber() / readNumber(String name)读数字同上Number
readDouble() / readDouble(String name)读双精度同上double
readLong() / readLong(String name)读长整型同上long
readInt() / readInt(String name)读整数同上int
readNull() / readNull(String name)断言下一个值是 null同上无(void)
skipValue()跳过下一个值(含整个对象/数组)同上无(void)

JsonFileConsumer ​

Reference: net.ornithemc.osl.core.api.json.JsonFile.JsonFileConsumer

作用:writeObject / readObject / writeArray / readArray 用的回调;签名允许抛 IOException,所以回调里可以直接继续调用 JsonFile 的方法。

需要:自己给一个 lambda 即可,参数就是外层那个 JsonFile。

返回:无(void)。

成员作用需要(参数 / 前置条件)返回
accept(JsonFile json)在对象/数组内部执行读写json 是外层同一个实例无(void);可抛 IOException

示例 ​

java
try (JsonFile json = new JsonFile(path)) {
    json.write();
    json.writeString("name", "example");
    json.writeArray("values", j -> j.writeString("a"), j -> j.writeString("b"));
    json.writeBoolean("enabled", true);
}

注册表:core.api.registry ​

本包有两代东西:RegistryKey + Registry + Registries 是"键 → 值"的通用小注册表;SimpleIdRegistry / DefaultedIdRegistry / IdBiMap 是旧的"数字 ID"注册表,全部已 Deprecated。

Registries ​

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

作用:Registry 的门面:提供"建一个具名注册表"和"在注册表里读写映射"的静态方法,避免调用方到处 new 注册表。

需要:所有 Registry 实例都由这里创建;同一个 RegistryKey 只能注册一次,重复会抛 IllegalStateException(消息形如 cannot register duplicate key ... to registry osl:registries)。

返回:见下表。注意注册表本身没有"按 key 反查已注册的 Registry"的公开方法(内部根注册表只写不读),所以请自己把拿到的 Registry 存进静态字段。

成员作用需要(参数 / 前置条件)返回
register(RegistryKey name)新建注册表并登记到内部根注册表name 未被使用过新的 Registry<K, V>(泛型由调用方指定)
registerMapping(Registry registry, K key, V value)往某个注册表里放映射(等价于 registry.register(key, value))key、value 都不能重复注册进去的 value
getMapping(Registry registry, K key)按 key 取值无值;未注册为 null
getKey(Registry registry, V value)按值反查 key无key;未注册为 null

Registry<K, V> ​

Reference: net.ornithemc.osl.core.api.registry.Registry<K, V>

作用:最小的双向映射注册表(key ⇄ value),用 LinkedHashMap 保存插入顺序。core 里它是 RegistryKey 的容器,mod 也可以拿它当"名字 → 对象"的自用注册表。

需要:实例只能由 Registries.register(...) 创建(构造函数是包私有的)。没有遍历、删除、size 之类的 API,也没有同步;注册一般只在初始化阶段做。

返回:register 返回注册进去的值,get / getKey 未命中返回 null。

成员作用需要(参数 / 前置条件)返回
register(K key, T value)建立 key ⇄ value 映射key 不能已存在、value 不能已注册过(任一重复抛 IllegalStateException);value 用引用身份判重,请保证单例注册进去的 value
get(K key)按 key 取值无值(泛型窄化为 T extends V);未注册为 null
getKey(V value)按值取 key无key(泛型窄化为 T extends K);未注册为 null
equals / hashCode按注册表的 RegistryKey 名字判等无boolean / int

RegistryKey ​

Reference: net.ornithemc.osl.core.api.registry.RegistryKey

作用:注册表的名字(不可变、可比较、可作 Map 键),形式是"父名:子名"的字符串。

需要:用 of(...) 创建(构造函数私有)。of(String) 把名字挂到内部根键 osl:registries 下,of(RegistryKey parent, String value) 拼成 parent:value。

返回:见下表。

成员作用需要(参数 / 前置条件)返回
of(String value)在根命名空间下建键,结果为 osl:registries:valuevalue 非 nullRegistryKey
of(RegistryKey parent, String value)建子键,结果为 parent.get() + ":" + valuevalue 非 nullRegistryKey
get()取完整字符串无String
equals / hashCode按字符串判等无boolean / int

SimpleIdRegistry<T> ​

Reference: net.ornithemc.osl.core.api.registry.SimpleIdRegistry<T>

作用:(已废弃,请改用 registries 模块的注册表 API:net.ornithemc.osl.registries.api.registry 下的 Registries / WritableRegistry / IdMap。)一个把"数字 ID"和"带命名空间的字符串 key"都映射到同一个值的注册表:id ⇄ value、key ⇄ value、value ⇄ id/key,用来替代原版各种"按 id 或按名字查找"的静态表。实现 Iterable<T>,迭代顺序是 key 映射表的顺序。

需要:值必须是引用唯一的对象(内部用 IdentityHashMap 记 value → key,用 fastutil 的引用表记 value → id)。注册时 id 必须 >= 0,id、key、value 三者都不能重复,任一重复抛 IllegalStateException;不传 id 的 register(key, value) 使用自增 id(从 0 开始;注册显式 id 时会把自增游标推到 id + 1)。

返回:register 返回注册进去的值;查询未命中返回 null,getId 未命中返回 -1。

成员作用需要(参数 / 前置条件)返回
SimpleIdRegistry()建空注册表无新实例
register(NamespacedIdentifier key, T value)用下一个自增 id 注册key、value 均未注册过value
register(int id, NamespacedIdentifier key, T value)用指定 id 注册id >= 0 且未占用;key、value 未注册过value
get(int id)按 id 查无值或 null
get(NamespacedIdentifier key)按 key 查无值或 null
has(T value)该值是否注册过依赖引用身份boolean
getId(T value)反查 id同上int(未注册为 -1)
getKey(T value)反查 key同上NamespacedIdentifier(未注册为 null)
keySet()所有已注册的 key无Set<NamespacedIdentifier>(可变视图,不要直接改)
iterator()迭代所有值无Iterator<T>

DefaultedIdRegistry<T> ​

Reference: net.ornithemc.osl.core.api.registry.DefaultedIdRegistry<T>

作用:(已废弃,请改用 registries 模块的 net.ornithemc.osl.registries.api.registry.DefaultedRegistry。)带"默认值"的 SimpleIdRegistry:查询未命中时不再返回 null,而是返回默认项。

需要:构造时给出默认项的 key(String 形式会被解析成 NamespacedIdentifier);默认项必须用"key 等于默认 key"的那次 register 注册,否则默认值一直是 null。

返回:get(...) 未命中时返回默认值(默认项也没注册过则为 null)。

成员作用需要(参数 / 前置条件)返回
DefaultedIdRegistry(String defaultKey)用字符串指定默认 key字符串会被当作 minecraft 命名空间下的 identifier(内部走 from,不是 parse),因此不能含冒号;非法字符抛运行时异常新实例
DefaultedIdRegistry(NamespacedIdentifier defaultKey)用现成 ID 指定默认 key无新实例
register(int id, NamespacedIdentifier key, T value)注册;key 等于默认 key 时同时记为默认值同父类value
get(int id) / get(NamespacedIdentifier key)查询,未命中回退到默认值无值 / 默认值 / null

其余成员(register(key, value)、has、getId、getKey、keySet、iterator)与 SimpleIdRegistry 相同。

IdBiMap<T> ​

Reference: net.ornithemc.osl.core.api.registry.IdBiMap<T>

作用:(已废弃,请改用 registries 模块的 net.ornithemc.osl.registries.api.registry.IdMap。)只有 id ⇄ value 的双向映射,没有字符串 key,是 SimpleIdRegistry 的轻量版。

需要:value 按引用身份判重;id >= 0;id 或 value 重复抛 IllegalStateException。

返回:register 返回值;get 未命中 null;getId 未命中 -1。

成员作用需要(参数 / 前置条件)返回
IdBiMap()建空映射无新实例
register(T value)用下一个自增 id 注册value 未注册过value
register(int id, T value)用指定 id 注册id >= 0 且未被占用value
get(int id)按 id 查无值或 null
has(T value)是否注册过无boolean
getId(T value)反查 id无int(未注册为 -1)
iterator()迭代所有值(按 id 映射表顺序)无Iterator<T>

通用工具:core.api.util ​

NamespacedIdentifier ​

Reference: net.ornithemc.osl.core.api.util.NamespacedIdentifier

作用:跨版本中立的"命名空间:标识符"ID,等价于原版的 Identifier,但在所有 MC 版本上都存在、行为一致(原版的 Identifier 直到 13w21a 才出现,14w27b 之前还只在客户端有,早期版本甚至完全不校验)。如果你的代码要跨版本、或者要在"原版 ID 类型还不存在 / 名字不一样"的版本上工作,就用它。

需要:一般不要自己实现这个接口,用 NamespacedIdentifiers.from(...) / parse(...) 拿实例(实现类是 impl 包里的不可变类)。它可以自由作为 Map 的键:实现类提供基于 namespace/identifier 的 equals / hashCode,toString() 为 namespace:identifier。

返回:namespaced / prefixed / suffixed / subidentifier 都返回新副本(类型本身不可变),不改动原对象。

成员作用需要(参数 / 前置条件)返回
SEPARATOR命名空间与标识符之间的分隔符常量(':')无char
separator()分隔符(默认实现返回 SEPARATOR)无char
namespace()命名空间部分无String
identifier()标识符部分无String
namespaced(String namespace)换命名空间不校验新命名空间(实现类直接替换)新的 NamespacedIdentifier
prefixed(String prefix)标识符前加前缀(命名空间不变)无新副本
suffixed(String suffix)标识符后加后缀无新副本
subidentifier(int beginIndex) / subidentifier(int beginIndex, int endIndex)取标识符的子串(命名空间不变)索引越界抛 StringIndexOutOfBoundsException新副本

NamespacedIdentifiers ​

Reference: net.ornithemc.osl.core.api.util.NamespacedIdentifiers

作用:NamespacedIdentifier 的工厂与校验器:负责字符集规则(命名空间只允许 [a-z0-9-._],标识符另外允许 /)、长度上限常量和比较器。

需要:解析外部输入(配置文件、命令参数、资源路径)时用 parse 或 isValid 系,不要自己拼字符串。校验失败抛出的是运行时异常(具体类型在 impl 包里,不属于 api)。

返回:from / parse 返回 ID;validate 原样返回传入的 ID(便于链式);isValid 系返回 boolean。

成员作用需要(参数 / 前置条件)返回
MINECRAFT_NAMESPACE / DEFAULT_NAMESPACE原版命名空间 "minecraft";默认命名空间等于它无String
MAX_LENGTH_NAMESPACE / MAX_LENGTH_IDENTIFIER长度上限常量(当前都是 Integer.MAX_VALUE,即不限制长度)无int
COMPARATOR比较器:先比 identifier,再比 namespace无Comparator<NamespacedIdentifier>
from(String identifier)用默认命名空间(minecraft)构造标识符合法(非空、字符集合法)NamespacedIdentifier;非法抛运行时异常
from(String namespace, String identifier)用指定命名空间构造两者都合法同上
parse(String s)解析 namespace:identifier 形式的字符串;没有冒号时按默认命名空间处理,冒号在开头(":foo")或任一部分为空视为格式错误s 非 nullNamespacedIdentifier;失败抛解析异常(运行时)
validate(NamespacedIdentifier id)校验一个已有 IDid 非 null原样返回 id;非法抛运行时异常
validateNamespace(String) / validateIdentifier(String)只校验某一部分非 null、非空、字符集合法、长度不超上限原样返回该字符串;非法抛运行时异常
isValid(NamespacedIdentifier) / isValidNamespace(String) / isValidIdentifier(String)只判断、不抛异常(null 视为非法;这组不检查长度,与 validate 系不完全对称)无boolean
isCharAllowed(int chr)某字符是否允许出现在 ID 中(含冒号、横线、点、下划线、斜杠、a-z0-9)无boolean
equals(NamespacedIdentifier a, NamespacedIdentifier b)语义相等(分隔符、命名空间、标识符都相同)两者非 nullboolean

Unit ​

Reference: net.ornithemc.osl.core.api.util.Unit

作用:只有一个常量的枚举,用来表达"没有值 / 已终止"这种占位。典型用途是配合 Optional 表示"访问到此结束"(见 text-components 模块的 TextVisitResults)。

需要:直接用 Unit.INSTANCE。

返回:无方法。

成员作用需要(参数 / 前置条件)返回
INSTANCE唯一实例无Unit

函数式接口:core.api.util.function ​

Java 8 自带的 Consumer / BiConsumer / Function / BiFunction 只到两参,也不允许抛受检异常,这里补齐。

IOConsumer<T> ​

Reference: net.ornithemc.osl.core.api.util.function.IOConsumer<T>

作用:允许抛 IOException 的一参消费者,主要用于"读/写文件时对每个元素做点什么"的回调。

需要:作为 lambda 实现;调用方负责捕获或声明 IOException。

返回:无(void)。

成员作用需要(参数 / 前置条件)返回
accept(T t)处理一个元素可抛 IOException无(void)

IOSupplier<T> ​

Reference: net.ornithemc.osl.core.api.util.function.IOSupplier<T>

作用:允许抛 IOException 的供应者,用于"惰性打开资源"。

需要:同 IOConsumer。

返回:T。

成员作用需要(参数 / 前置条件)返回
get()产出值可抛 IOExceptionT

TriConsumer<T, U, V> ​

Reference: net.ornithemc.osl.core.api.util.function.TriConsumer<T, U, V>

作用:三参消费者(BiConsumer 的三参特化)。Event.triConsumer() 用的就是它。

需要:作为 lambda 实现;预期通过副作用工作。

返回:无(void)。

成员作用需要(参数 / 前置条件)返回
accept(T t, U u, V v)处理三个参数无无(void)
andThen(TriConsumer after)组合:先执行自己、再执行 afterafter 非 null(null 抛 NullPointerException);前半抛异常时 after 不执行组合后的 TriConsumer<T, U, V>

TriFunction<T, U, V, R> ​

Reference: net.ornithemc.osl.core.api.util.function.TriFunction<T, U, V, R>

作用:三参函数(BiFunction 的三参特化),有返回值。Event.triFunctionFirst() 等工厂用的就是它。

需要:作为 lambda 实现。

返回:R。

成员作用需要(参数 / 前置条件)返回
apply(T t, U u, V v)计算结果无R
andThen(Function after)先 apply,再把结果交给 afterafter 非 null(null 抛 NullPointerException)组合后的 TriFunction<T, U, V, W>

坐标与方向:core.api.util.math ​

BlockPos ​

Reference: net.ornithemc.osl.core.api.util.math.BlockPos

作用:OSL 自己的整数方块坐标(不可变),提供打包成 long、距离、偏移、沿方向移动等原版在不同版本里叫法各异的功能。它和 Minecraft 的 BlockPos 是两个不同的类,不能互相赋值,需要自己转换(例如 BlockPos.of(mcPos.getX(), mcPos.getY(), mcPos.getZ()))。

需要:用 of(x, y, z) 或构造函数创建;pack / unpack 只做位运算、不检查取值范围,超范围坐标会被静默截断(见下方位布局);要"临时可变坐标"用嵌套类 Mutable,要"高频复用、零分配"用 PooledMutable(配合 try-with-resources)。

返回:变换方法返回新对象(Mutable 系除外);add(0, 0, 0) 会原样返回 this。

成员作用需要(参数 / 前置条件)返回
of(int x, int y, int z)新建不可变坐标无BlockPos
pooled(int x, int y, int z)从对象池取一个可变坐标必须 close() 归还(PooledMutable 实现 AutoCloseable),池上限 100,超出的不回收BlockPos.PooledMutable
BlockPos(BlockPos pos) / BlockPos(int x, int y, int z)拷贝 / 直接构造无新实例
pack(BlockPos) / pack(int x, int y, int z)打包成 long坐标在下方表内范围内,否则截断long
packX(int) / packY(int) / packZ(int)只打包某一个分量(已移位,未做符号扩展)同上long(可直接按位或)
unpack(long)从 long 还原坐标long 必须来自 packBlockPos
unpackX(long) / unpackY(long) / unpackZ(long)只解出某一个分量(做符号扩展)同上int
pack()实例版打包(等价于 pack(this))同 packlong
x() / y() / z()三个分量无int
equals / hashCode按当前 x/y/z 判等与求哈希(hashCode 为 x + 31 * (y + 31 * z))无boolean / int
compareTo(BlockPos)排序:先 y,再 z,再 x无int(返回差值,不做归一化)
toString()形如 BlockPos{x=1,y=2,z=3}无String
distanceSquared(BlockPos) / distanceSquared(BlockPos, boolean center) / distanceSquared(double x, double y, double z, boolean center)平方距离;center 为 true 时按方块中心(+0.5)计算无double
distanceManhattan(BlockPos)曼哈顿距离无int
add(int dx, int dy, int dz) / add(BlockPos)平移(返回新对象)无BlockPos
subtract(BlockPos)反向平移无BlockPos
up() / down() / north() / south() / west() / east()(各带 int amount 重载)沿某方向移动 1 格 / n 格无BlockPos
offset(Direction dir) / offset(Direction dir, int amount)沿 Direction 移动dir 非 nullBlockPos
immutable()取不可变副本(基类返回 this,Mutable 返回新副本)无BlockPos

pack 的位布局 ​

pack 把三个 int 塞进一个 long(共 64 位),用于"把坐标当 Map 的键"或"只用一个 long 存档/发包":

分量位数位偏移有效取值范围(超范围会被掩码截断)
y120(最低 12 位)-2048 ~ 2047
z2612-33554432 ~ 33554431
x2638(最高 26 位)-33554432 ~ 33554431
  • 打包:(x & 0x3FFFFFF) << 38 | (z & 0x3FFFFFF) << 12 | (y & 0xFFF)。
  • 解包用算术右移做符号扩展,所以负数坐标能正确还原。
  • 不要把 pack() 的结果与原版 BlockPos 的长整型表示直接互换,除非你自己核对过位布局。
  • 不要把 pack() 的结果当成 hashCode():后者是 x + 31 * (y + 31 * z),两者不同。
  • 因为超范围不报错,"打包再解包"可能拿回与原值不同的坐标——需要严格时请自行校验范围。

BlockPos.Mutable ​

作用:可变的坐标,避免在循环里反复创建对象。继承 BlockPos,重写 x() / y() / z()。

需要:不要把它当 HashMap 的键(hashCode 随内容变化);add(...) 返回的是不可变新对象,原地移动请用 move(...)。

返回:set / move 返回 this(便于链式),immutable() 返回新副本。

成员作用需要(参数 / 前置条件)返回
Mutable(BlockPos pos) / Mutable(int x, int y, int z)构造无新实例
setX / setY / setZ(int)改单个分量无无(void)
set(int x, int y, int z) / set(BlockPos pos)一次性设置无this
move(int dx, int dy, int dz) / move(BlockPos dpos) / move(Direction dir) / move(Direction dir, int amount)相对移动dir 非 nullthis
immutable()复制成不可变坐标无新的 BlockPos

BlockPos.PooledMutable ​

作用:线程安全(内部对池加锁)的可变坐标对象池,专给"每 tick 大量临时坐标"的场景,减少 GC 压力。

需要:用 acquire 取、用 try-with-resources 归还;归还后不能再使用该实例(会被别的调用方复用)。

返回:acquire 返回一个已置为指定坐标的池化实例。

成员作用需要(参数 / 前置条件)返回
acquire() / acquire(int x, int y, int z)从池里取(池空则新建)无PooledMutable
close()归还到池(池未满 100 时才真正入池)只调用一次;close() 之后再使用属于错误无(void)
java
try (BlockPos.PooledMutable p = BlockPos.pooled(x, y, z)) {
    p.move(Direction.UP);
    use(p.x(), p.y(), p.z());
}

Direction ​

Reference: net.ornithemc.osl.core.api.util.math.Direction

作用:六个方向的枚举,自带两套"元数据编号"(2D 水平 0-3、3D 0-5)、轴信息、相反方向、绕各轴的顺/逆时针旋转,以及沿方向的单位偏移。原版不同版本里这些信息散落在多个类和 switch 中,这里集中成一份跨版本稳定的实现。

需要:byName 不认的字符串返回 null;byData2d / byData3d 对任意整数都取模,不抛异常;旋转方法只对同一平面内的方向有效,跨界会抛 IllegalStateException。

返回:见下表;全部是纯查表,无副作用。

成员作用需要(参数 / 前置条件)返回
DOWN / UP / NORTH / SOUTH / WEST / EAST六个方向(toString() 返回小写名)无该常量
VALUES所有方向组成的数组(公开字段,不要修改)无Direction[]
byName(String)按小写名查名字为 down / up / north / south / west / east;null 返回 nullDirection 或 null
byData2d(int)按旧版水平元数据查(内部对 4 取模)无Direction(永远是水平方向)
byData3d(int)按旧版 3D 元数据查(内部对 6 取模)无Direction
data2d() / data3d()各自的元数据编号无int
axis()所属轴无Direction.Axis
axisDirection()沿轴的正负方向无Direction.AxisDirection
offsetX() / offsetY() / offsetZ()单位偏移(不属于该轴的为 0)无int
opposite()相反方向无Direction
clockwise() / counterClockwise()等价于绕 Y 轴顺/逆时针旋转无Direction
clockwiseX / counterClockwiseX / clockwiseY / counterClockwiseY / clockwiseZ / counterClockwiseZ绕指定轴旋转 90°只接受该轴平面内的方向,否则抛 IllegalStateExceptionDirection

编号速查:byData2d 的 0/1/2/3 依次是 SOUTH / WEST / NORTH / EAST;byData3d 的 0-5 依次是 SOUTH / WEST / NORTH / EAST / DOWN / UP。

Direction.Axis(枚举,实现 Predicate<Direction>) ​

作用:三个坐标轴,能"从坐标三元组里挑出属于自己的那个分量",并告知自己所在平面。

需要:无。

返回:见下表。

成员作用需要(参数 / 前置条件)返回
X / Y / Z三个轴无该常量
plane()所在平面(X、Z 为水平,Y 为垂直)无Direction.Plane
isVertical() / isHorizontal()平面判断无boolean
choose(int x, int y, int z) / choose(double x, double y, double z)取出本轴对应的分量无int / double
test(Direction dir)该方向是否沿本轴(dir 为 null 时返回 false)无boolean

Direction.AxisDirection(枚举) ​

作用:表示"沿轴的哪一侧"。

需要:无。

返回:见下表。

成员作用需要(参数 / 前置条件)返回
POSITIVE / NEGATIVE沿轴正/负方向(toString() 为 towards positive / towards negative)无该常量
offset()偏移值 +1 / -1无int

Direction.Plane(枚举,实现 Iterable<Direction> 与 Predicate<Direction>) ​

作用:垂直平面(2 个方向)与水平平面(4 个方向),可遍历、可判断、可随机取一个。

需要:无。

返回:见下表。

成员作用需要(参数 / 前置条件)返回
VERTICAL / HORIZONTAL垂直(DOWN、UP)与水平(NORTH、SOUTH、WEST、EAST)无该常量
iterator()遍历本平面的方向无Iterator<Direction>
test(Direction dir)该方向是否在本平面(null 返回 false)无boolean
pickDirection(Random random)随机取一个本平面方向random 非 nullDirection

拓扑排序:core.api.util.sort ​

TopoSort ​

Reference: net.ornithemc.osl.core.api.util.sort.TopoSort

作用:对"有依赖关系的对象集合"做拓扑排序,典型场景是"注册项之间有加载顺序"、"配方有前置"、"监听器要按依赖排序"。它直接作用在对象本身(T)上,不要求实现任何接口,也不要求可比较。

需要:同时给出"全部节点"和 Map<T, Set<T>> 依赖表(key 是节点,value 是它的前置节点集合)。依赖表里出现、但不在节点集合里的前置项会被静默忽略;节点集合里没出现在依赖表中的节点视为无前置。所有节点必须能作为 HashMap 的键(正确实现 equals / hashCode)。源码没有环检测:一旦有环会死循环(不抛异常),调用前请自己保证无环。

返回:排好序的 List<T>——前置节点总排在依赖它的节点之前;同一批"无前置"节点的相对顺序取决于传入集合的迭代顺序,不保证稳定。

成员作用需要(参数 / 前置条件)返回
sort(Collection<T> unsortedNodes, Map<T, Set<T>> incomingEdges)按依赖表排序节点唯一、无环;incomingEdges 中 value 为 null 或空视为无前置List<T>(新列表;传入集合不被修改)
sort(Collection<Node<T>> unsortedNodes)接受内部节点包装的重载参数类型是私有嵌套类,mod 代码无法调用(只有类内部能用)List<T>
java
Map<String, Set<String>> deps = new HashMap<>();
deps.put("b", Set.of("a"));                                        // b 依赖 a
List<String> order = TopoSort.sort(List.of("a", "b"), deps);       // [a, b]

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