YSM Mapping API

YSM Mapping API

开发状态：YSM Mapping API 正在积极开发中。正式稳定版发布前，可能会发生破坏性变更。

YSM Mapping API 是一个前置库和依赖模组，供与 Yes Steve Model (YSM) 集成的其他模组使用。

由于 YSM 的内部类、方法和字段都经过混淆，依赖硬编码运行时名称的集成可能不够稳定。Minecraft 启动期间，YSM Mapping API 会分析已安装的 YSM JAR 文件的字节码结构，并将经过验证的匹配项作为带类型的语义符号提供给依赖模组。

此模组不会添加物品、方块、模型、菜单或独立的玩法功能。只有在其他模组将 YSM Mapping API 列为必需依赖时，才需要安装它。Yes Steve Model 需要单独安装，本模组不包含它。

支持的版本

• 仅限 Minecraft 1.20.1
• Fabric Loader 0.16.0 或更高版本
• Forge 47.4.10 或更高版本
• Java 17

• 仅限 Minecraft 1.21.1
• Fabric Loader 0.16.0 或更高版本
• NeoForge 21.1.235 或更高版本
• Java 21

• 两个版本均需要 Yes Steve Model 2.6.0 或更高版本。

文件对应特定的 Minecraft 版本和模组加载器。请仅使用与你的环境完全匹配的 JAR。如果无法验证较新 YSM 版本的结构，部分符号可能无法解析；此 API 不会猜测未知映射。

本地缓存与设置

以下文件会自动生成：

config/ysm_mapping_api/
├─ settings.json
└─ mappings.json

mappings.json用于存储上次成功分析得到的映射。如果 YSM 和请求的符号集合均未更改，则会重复使用该文件；只有在新一轮分析成功完成后，才会替换该文件。

面向模组开发者

使用方模组需在以下位置声明所需符号：

META-INF/ysm-mapping-api/requests-v1.json

初始化完成后，模组可以使用 YsmMappingApi.resolve(...)解析带类型的映射，使用 YsmSymbols中的精选语义键，或定义使用方专属的键。

Mixin 集成可以通过提供的插件和运行时引用映射器包装器，并配合源代码别名来实现。目前精选注册表涵盖 YSM 网络通信、客户端/服务端模型同步、模型和纹理访问、音频缓存、玩家与动画状态、装备钩子、骨骼和渲染器等领域。

清单文档和集成示例可在源代码仓库中查看。问题可通过问题跟踪器反馈。