Skip to content

10 crash-reports ​

一句话定位:用一套统一接口读取、扩写、构造 Minecraft 崩溃报告,并在游戏崩溃时把自己的信息塞进报告里。

项值
模块 idcrash-reports
Mavennet.ornithemc.osl-gen2:crash-reports:0.1.0+mc1.4.3-mc1.14.4
端双端
依赖ploceus.dependOslModule('crash-reports', '0.24.0')

原版崩溃报告(net.minecraft.util.crash.CrashReport)在 1.12.2 上字段是私有的、分段只能靠内部类拼,mod 想加一段调试信息几乎无从下手。本模块把"标题 / 异常 / 系统详情分段 / 自定义分段 / 保存到文件 / 生成文本"抽成 CrashReport 接口,并让原版类通过接口注入实现它,因此游戏自己产出的崩溃报告也能直接当 API 用。此外还提供"崩溃时自动回调"的 CrashListener,以及构造"带报告的异常"的工具方法。

工具类 ​

CrashExceptions ​

Reference: net.ornithemc.osl.crashreports.api.CrashExceptions

作用:构造"带崩溃报告的异常"。抛出它之后,游戏会按正常崩溃流程处理,并显示/保存这份报告。适合"mod 检测到致命配置错误,想把诊断信息一起送到崩溃界面"的场景。

需要:一个报告标题(会显示在 Description: 一行)和引发崩溃的 Throwable;可选一个 Consumer<CrashReport> 用来补充分段。

返回:RuntimeException(可直接 throw),异常携带的报告可再取回。

成员作用需要(参数 / 前置条件)返回
from(String title, Throwable error)构造异常与报告;报告只含系统详情(OS、Java、内存、JVM 参数、mod 列表),正文为空title、error 不可为 null(源码未做判空)RuntimeException
from(String title, Throwable error, Consumer<CrashReport> builder)同上,并在返回前把报告交给 builder 让你 addSection / getSystemReport().addDetail(...)builder 不能为 null;builder 里抛的异常会原样向外传播RuntimeException
java
if (configBroken) {
    throw CrashExceptions.from("OSL Example config is broken", new IllegalStateException("missing 'cookie'"),
        report -> report.addSection("Config").addDetail("path", configPath));
}

实现细节:返回的运行时类型其实是原版的 net.minecraft.util.crash.CrashException(它本身是 RuntimeException 的子类),因此游戏能识别它并走原版崩溃界面。不要依赖具体类型,按 RuntimeException 处理即可。

报告 ​

CrashReport ​

Reference: net.ornithemc.osl.crashreports.api.crash.CrashReport

作用:崩溃报告的统一视图。既代表原版 net.minecraft.util.crash.CrashReport(通过接口注入实现),也代表 OSL 自己构造的报告(CrashReport.of(...))。所有分段、文本、保存操作都从这里出。

需要:通常不是自己 new,而是从"当前发生的崩溃"里拿:游戏传给 CrashListener 的参数、CrashException.getReport()、或 CrashReport.of(...)。

返回:见下表;分段相关方法返回 CrashReportSection,文本相关方法返回 String。

成员作用需要(参数 / 前置条件)返回
getTitle()报告标题(原版 Description: 那一行)—String
getError()导致崩溃的异常—Throwable
getSystemReport()"系统详情"分段,可直接追加条目—CrashReportSection
addSection(String name)新建一个分段并加入报告,生成文本时按加入顺序输出name 是段落标题新建的 CrashReportSection
addSection(String name, int stackTraceOffset)同上,并指定分段自带堆栈时跳过多少帧stackTraceOffset 从异常堆栈顶部开始计数;OSL 自建报告默认 1,原版报告会在此值上再 +1新建的 CrashReportSection
getErrorMessage()异常的完整堆栈文本;异常 message 为 null 的 NPE/StackOverflowError/OutOfMemoryError 会被替换成以报告标题为 message 的副本—String
buildFriendlyString()生成完整报告文本:头部、吐槽语、时间、Description、堆栈、各分段、系统详情—String
buildFriendlyStringWithoutHeader()只生成分段部分(无头部与描述)—String
getSaveFile()报告已保存到的路径未保存过时可能为 null(OSL 自建报告返回 null;原版报告直接读其内部字段,源码未判空)Path 或 null
saveToFile(Path file)把 buildFriendlyString() 写入文件,自动创建父目录只有第一次调用会成功;已保存过直接返回 false;写失败记日志并返回 falseboolean
static of(String title, Throwable error)构造报告若 error 已是 CrashException,直接返回它内部的那份报告,避免嵌套CrashReport

1.12.2 说明:接口注入让原版 CrashReport 实现本接口,所以 CrashReport.of 与游戏给的报告用法完全一致;saveToFile 在原版报告上走原版写文件逻辑(1.12.2 支持)。

CrashReportSection ​

Reference: net.ornithemc.osl.crashreports.api.crash.CrashReportSection

作用:崩溃报告里的一个分段(原版 net.minecraft.util.crash.CrashReportCategory 通过接口注入实现它)。每个条目是"键 → 值",值为 CrashReportDetail 时延迟到生成文本时才求值。

需要:从 CrashReport.addSection(...) 或 getSystemReport() 拿实例;不要自己实现。

返回:三个方法都是 void。

成员作用需要(参数 / 前置条件)返回
addDetail(String key, CrashReportDetail<String> detail)加一条惰性计算的条目值在生成报告时才 call(),此时世界/实体可能已处于异常状态,代码要能容忍无(void)
addDetail(String key, Object detail)加一条立即固定的条目(值由原版转成字符串)detail 非 null无(void)
addDetailError(String key, Throwable error)加一条异常条目(实现上等同 addDetail(key, error))最终排版由原版决定无(void)

重复 key 不会覆盖:addDetail 直接调用原版的追加逻辑,同一个 key 加两次会在报告里出现两条(OSL 内部记录了条目索引,但公开 API 没有移除/替换方法)。

CrashReportDetail<V> ​

Reference: net.ornithemc.osl.crashreports.api.crash.CrashReportDetail<V>

作用:延迟求值条目,等价于 Callable<V> 的语义化别名。适合放"只有在崩溃时才值得/才能算"的信息(玩家坐标、区块状态、当前 GUI 名等)。

需要:实现 call();在 call() 里抛异常时该条目如何显示由原版决定(源码未明确说明是否会中断整份报告的生成),建议自己 try/catch 并返回兜底字符串。

返回:call() 返回的 V(实际使用中多为 String)。

成员作用需要(参数 / 前置条件)返回
call()计算条目值(继承自 Callable)不应做重 I/O;执行时机是报告文本生成时V

CrashException ​

Reference: net.ornithemc.osl.crashreports.api.crash.CrashException

作用:把自己构造的 CrashReport 包成一个可抛出的运行时异常;getMessage() 返回报告标题,getCause() 返回报告里的原始异常。

需要:一份已经建好的 CrashReport(一般用 CrashReport.of(...))。日常更推荐 CrashExceptions.from(...),它一步到位。

返回:getReport() 返回报告,其余继承自 RuntimeException。

成员作用需要(参数 / 前置条件)返回
CrashException(CrashReport report)构造report 非 null(源码未判空)—
getMessage()报告标题—String
getCause()报告中的原始异常—Throwable
getReport()取回报告—CrashReport

崩溃时的回调 ​

CrashListener ​

Reference: net.ornithemc.osl.crashreports.api.crash.CrashListener

作用:函数式接口。游戏正在生成崩溃报告时被回调,让你把 mod 自己的信息写进报告(注册表状态、网络连接、异步任务队列……)。

需要:交给某个 CrashReportPopulator 注册(见下)。回调抛出的异常会被捕获并记日志,不会影响崩溃处理本身。

返回:无(void)。

成员作用需要(参数 / 前置条件)返回
populateCrashReport(CrashReport report, CrashReportSection section)往 section 里加条目;report 可用于 addSection 或读标题/异常report 可能为 null(见 WorldData 的情形);不要在回调里做重 I/O无(void)

CrashReportPopulator ​

Reference: net.ornithemc.osl.crashreports.api.crash.CrashReportPopulator

作用:注册 CrashListener 的入口。原版 Minecraft(仅客户端)、MinecraftServer、World、WorldData 都通过接口注入实现了它,所以直接强转就能注册。

需要:拿到对应实例再强转;监听器在每次崩溃填充报告时按注册顺序调用。

返回:addCrashListener 为 void。

成员作用需要(参数 / 前置条件)返回
addCrashListener(CrashListener listener)注册监听器listener 非 null;同一实例可注册多个无(void)

各宿主实例的触发时机与传入的分段(实现细节,但直接决定你写进哪一段):

宿主(1.12.2 类型)端触发点传给你的 sectionreport 参数
net.minecraft.client.Minecraft仅客户端原版 populateCrashReport 结束时系统详情分段非 null
net.minecraft.server.MinecraftServer双端原版 populateCrashReport 结束时系统详情分段非 null
net.minecraft.world.World双端原版 populateCrashReport 结束时该世界的分段非 null
net.minecraft.world.WorldData双端原版 populateCrashReport 结束时存档信息分段null(回调里必须先判空)
java
// 在世界崩溃时把玩家坐标写进世界分段
if (world instanceof CrashReportPopulator) {
    ((CrashReportPopulator) world).addCrashListener((report, section) ->
        section.addDetail("Player position", () -> player.getPos().toString()));
}

注意:接口注入只保证上面四个类实现了该接口;向其它对象强转会 ClassCastException。客户端上还可以用 lifecycle-events 的 MinecraftInstance.get()、服务端用 MinecraftServerInstance.get() 拿实例,再强转成 CrashReportPopulator。

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