Codec Lens

Codec Lens

Codec Lens 让 Mojang 的 Codec（DataFixerUpper）报错变得人类可读。安装模组即可——无需额外操作。当数据包解析失败时，日志中会输出结构化的诊断信息，而不是令人费解的单行错误。

Codec Lens 使 Mojang Codec（DataFixerUpper）的错误变得人类可读。装上 mod 就行，不需要任何配置。数据包解析失败时，日志中会自动输出结构化的诊断信息，而不是一行难以理解的错误。

---

整合包作者

只需将 jar 文件放入 mods/ 文件夹即可。无需配置。

把 jar 丢进 mods/ 文件夹即可，无需配置。

当数据包条目解析失败时，Minecraft 原有的错误仍会照常输出。Codec Lens 会在其后追加一段额外的诊断块：

当数据包条目解析失败时，Minecraft 原有的报错照常输出。Codec Lens 会在其后追加一段额外的诊断块：

╔══ CodecLens Diagnostic ══════════════════════════════
║ Registry entry: minecraft:worldgen/biome / minecraft:plains
║
║ Expected schema:
║   {
║     temperature: float,
║     downfall: float,
║     effects: {
║       fog_color: int,
║       sky_color: int,
║       water_color: int,
║       water_fog_color: int?,
║       ...
║     }
║   }
║
║ Diagnostic:
║   {
║     ✗ temperature: float  ← Expected float, got "warm" (got warm)
║       downfall: float  ✓
║       effects: { ... }  ✓
║   }
╚═════════════════════════════════════════════════════

• ✓ = 字段解析成功 / 字段解析成功
• ✗ = 字段解析失败，后跟原因 / 字段解析失败，后面跟着原因
• 类型后的 ? = 可选字段 / 类型后的 ? 表示可选字段
• 类型间的 | = 二选一（优先尝试左侧，失败后尝试右侧） / 类型间的 | 表示二选一

---

Mod 开发者

无感模式（零代码）

Codec Lens 对所有 RegistryDataLoader 的 Codec（世界生成、配方、伤害类型等）开箱即用。你的用户安装它后，就能自动获得更好的数据格式错误提示。

Codec Lens 对所有通过 RegistryDataLoader 加载的 Codec（世界生成、配方、伤害类型等）开箱即用。你的用户装上它，就能自动获得更好的数据格式报错。

API 使用

你也可以在代码中主动使用 Codec Lens：

你也可以在代码中主动使用 Codec Lens：

import io.github.tt432.codeclens.CodecLensAPI;

// 检查 Codec 的结构 / Inspect a codec's structure
String schema = CodecLensAPI.describeSchema(MyRecord.CODEC);
// → "{\n  name: string,\n  value: int\n}"

// 解码并在失败时自动诊断 / Decode with automatic diagnostics on failure
DataResult<MyRecord> result = CodecLensAPI.decodeWithDiagnostics(
    MyRecord.CODEC, JsonOps.INSTANCE, jsonElement);

// 获取原始诊断树用于程序化处理 / Get a raw diagnostic tree for programmatic use
FieldDiagnostic diag = CodecLensAPI.diagnoseRaw(
    MyRecord.CODEC, JsonOps.INSTANCE, jsonElement);

自定义 Codec 支持

如果你有自定义的 Codec 实现，Codec Lens 无法自动反射识别，可以注册一个 SchemaExtractor：

如果你有自定义的 Codec 实现，Codec Lens 无法自动反射识别，可以注册一个 SchemaExtractor：

import io.github.tt432.codeclens.extract.SchemaExtractorRegistry;
import io.github.tt432.codeclens.extract.SchemaExtractor;
import io.github.tt432.codeclens.schema.CodecSchema;

// 在模组初始化时注册 / Register during mod init
SchemaExtractorRegistry.register((codec, ctx) -> {
    if (codec instanceof MyWeightedListCodec<?> weighted) {
        // 使用内置 schema 节点描述结构
        return new CodecSchema.ListSchema(
            new CodecSchema.RecordSchema(List.of(
                new FieldEntry("data", ctx.extract(weighted.elementCodec()), false),
                new FieldEntry("weight", new CodecSchema.PrimitiveSchema("int"), false)
            ))
        );
    }
    return null; // 不认识，交给下一个处理 / Not ours, pass to next
});

对于自定义 MapCodec 类型，还有 MapCodecSchemaExtractor 接口，注册方式相同。

There is also MapCodecSchemaExtractor for custom MapCodec types — register it the same way via SchemaExtractorRegistry.register(...).

Schema 节点类型

节点	含义	格式化为
PrimitiveSchema("int")	基本类型	int
RecordSchema(fields)	带命名字段的对象	{ name: type, ... }
EitherSchema(l, r)	先尝试左侧，失败后尝试右侧	int | string
XorSchema(l, r)	恰好一个必须匹配	int ^ string
ListSchema(elem)	列表	[int]
MapSchema(k, v)	映射	map<string, int>
DispatchSchema(key, ks)	类型分发	dispatch("type": string)
PairSchema(a, b)	对	pair<string, int>
UnknownSchema(desc)	无法识别的 Codec	原始 toString

---

兼容性

• Minecraft 1.21.1
• NeoForge 21.1.x
• DFU 8.0.16
• Java 21+