📌 声明
本项目人员只负责模组移植。开发与测试人员均与 OYSM 团队及 YSM 团队没有任何关系。
从7月17日开始，Fox Model Loader正式停止维护，无论你要自用还是fork，请切换到花火火的变身器，项目地址：https://github.com/sdf123098/Sparkle-Morpher
鉴于 OYSM 与 YSM 之间的历史争议，我们不关注、也不参与这些事情。我们的内心只有移植。
如果你觉得这是在挑衅，那你错了。我们只是在研究 Vibe Coding——即借助 AI 辅助工具探索模组移植与二次开发的可行性。
请勿在本仓库中发起与代码无关的争论。
Fox Model Loader 是一款基于 OpenYSM 构建的 Minecraft 模组，可以将原版玩家模型替换为带完整动画的自定义模型。模组使用 Minecraft 基岩版模型与动画文件（.ysm），并借助 GeckoLib 实现复杂动画播放，让每位玩家都能拥有独立的角色外观、动作和第一人称手臂表现。
本项目专注于将 OpenYSM 迁移到 Minecraft 1.21+ 与 26.1.x 平台，并持续适配新版客户端的渲染、输入、动画与资源管理变化。
- 加载
.ysm基岩版格式模型，替换默认 Steve / Alex 玩家模型。 - 每位玩家可独立选择模型与纹理，支持在模型、纹理和分类之间切换。
- 26.1.2 版移除了杂项分类（Alex、Steve 等皮肤模型），精简内置模型列表；default 模型不再受原版皮肤覆盖干扰。
- 基于 Molang 表达式的动画引擎，支持复杂状态机与数据驱动动画。
- 内置行走、奔跑、跳跃、潜行、游泳、飞行、滑翔等移动动画。
- 支持剑、斧、镐、锹、锄、重锤、三叉戟、原版矛等武器姿势。
- 26.1.2 版新增"原版矛"独立分类，三叉戟恢复为独立类型，不同材质矛使用数据驱动时长，基于原版动力武器组件计算动画采样。
- 支持拉弓、进食、饮用药水、格挡、投掷等使用动画。
- 主手与副手动画可独立响应，右键行为匹配原版逻辑（副手非空 + 主手工具/武器时仅主手挥动）。
- 可按手持物品、穿戴装备、骑乘实体、当前维度等条件触发自定义动画。
- swing 动画阈值修正为
<=2，数据驱动模式下通过shouldForceSwingPredicate()确保 swing 控制器正确参与判定。
- 在模型选择界面中浏览远程模型仓库。
- 支持
.ysm与.zip格式下载，支持搜索、筛选、下载队列和已完成任务管理。 - 内置 CDN 加速，便于快速获取模型资源。
- 支持创建、重命名、删除分类文件夹，支持批量移动模型。
- 删除分类时可选择保留或移除其中内容，操作完成后自动刷新缓存。
- 支持从本地客户端选择模型并上传到服务器，文件夹模型自动打包为
.zip。 - 自定义文件夹上传界面采用紧凑图标工具栏，适配窄窗口与高界面缩放。
- 支持
.ysm与.zip格式，已移除.7z入口。
- GUI 中提供实时 3D 预览，支持旋转、缩放和查看模型细节。
- 将原版第一人称手臂替换为与当前模型匹配的自定义手臂，支持独立左手、右手骨骼，可同步手持物品与动画。
- 客户端切换模型后自动同步到服务端，同一服务器中的其他玩家可看到对应的自定义模型。
- 服务端可配置模型上传权限与文件大小限制。
- 默认模型切换现已添加专项绕过逻辑，不再因服务端缓存校验误判而拒绝。
- Fabric 版：通过 ModMenu 集成，在模组菜单中点击"设置"按钮即可打开配置界面。
- NeoForge 版：通过
IConfigScreenFactory+registerExtensionPoint注册配置界面，模组菜单设置按钮可正常使用。 - 1.21.1 版：Fabric 与 NeoForge 配置界面均可在 v1.3.1 正常打开（NeoForge 1.21.1 为首次官方支持）。
- 动画帧分析器：帧级诊断工具，定位动画卡顿根因。
- 模型内存分析器：全生命周期内存检查点日志，可选开启"模型导入性能日志"。
- 支持 PojavLauncher、FCL、Zalith Launcher，内置模型选择器与文件导入功能，提供与桌面端一致的体验。
本项目基于上游 OpenYSM 迁移：
- 上游源码: https://github.com/OpenYSMDev/OpenYSM
- 反馈 QQ 群: 1104823534
Fox Model Loader 只专注于将 OpenYSM 迁移至新版 Minecraft 平台，并为社区提供可用的自定义玩家模型加载工具。请勿在本仓库中讨论与开发无关的争议话题。
本项目从 OpenYSM 1.20.1 出发，依次完成四个平台的迁移与适配，最终形成覆盖 1.21.1 与 26.1.2 双版本、Fabric 与 NeoForge 双加载器的四路构建体系。
驱动引擎：DeepSeek V4 Pro（1M 上下文） + Claude Code
Minecraft 1.21.1 对游戏 API 做了较大调整，迁移主要解决以下技术问题：
- Mixin 目标方法签名变化，需要逐一适配。
- 核心类字段与方法重命名，引发连锁编译错误。
- Fabric Loom、Gradle 插件和 Fabric API 等依赖升级。
最终完成编译与运行时问题修复，游戏可正常启动并加载自定义模型。
构建环境：
| 组件 | 版本 |
|---|---|
| Java | 21 |
| Fabric Loom | 1.8-SNAPSHOT |
| Fabric Loader | 0.16.x |
| Fabric API | 1.21.1 对应版本 |
驱动引擎：GPT-5.5 + Codex
Minecraft 26.x 对渲染、输入、实体、NBT、Registry 与构建环境做了大量破坏性改动，迁移难度明显高于 1.21.1，主要解决以下技术问题：
- 将
GuiGraphics相关渲染代码迁移到GuiGraphicsExtractor，并适配新的渲染方法命名。 - 适配新版
EntityRenderer类型参数、extractRenderState()与createRenderState()。 - 修复模型骨骼绑定、纹理映射、动画状态机在新 API 下的兼容问题。
- 适配新版鼠标和键盘输入事件对象。
- 修复
AbstractArrow、Boat等实体类包路径变化导致的 import 问题。 - 适配 NBT 与 Registry API 中 Optional 返回值和键集合访问方式变化。
- 在缺少官方 Mojang 映射的情况下，通过 ASM 9.9 字节码分析工具生成 tiny v2 映射文件。
- 将 Fabric Loom 升级至 1.17.0-alpha.8，以支持 Java 25 字节码。
- 在 Architectury API 暂无 26.x 支持时，创建 22 个 stub 类补齐平台抽象。
最终解决 200+ 个编译错误和 40+ 个运行时崩溃，游戏可正常启动并加载模型。
构建环境：
| 组件 | 版本 |
|---|---|
| Java | 25 (Azul Zulu 25.0.2) |
| Gradle | 9.5.1 |
| Fabric Loom | 1.17.0-alpha.8 |
| Fabric Loader | 0.19.2 |
| Fabric API | 0.149.1+26.1.2 |
| Shadow 插件 | 9.0.0-beta4 |
驱动引擎：GPT-5.5 + Codex
在 26.1.2 Fabric 版稳定后，将项目迁移至 NeoForge 平台。NeoForge 26.1.2 使用独立的注册体系、数据组件 API、网络通道与事件总线，迁移主要解决以下技术问题：
- 将 Fabric 注册回调替换为 NeoForge
RegisterEvent与ModContainer.registerExtensionPoint()。 - 将 Fabric 网络包替换为 NeoForge
Payload+RegisterPayloadHandlersEvent。 - 将 Fabric API 事件替换为 NeoForge 事件总线订阅。
- 适配 NeoForge 数据组件注册与
DataComponentType。 - 配置系统从 Fabric Config API 迁移至 NeoForge
ModConfigSpec。
驱动引擎：GLM 5.2 + Claude Code
1.21.1 NeoForge 是四个平台中最后完成适配的，自 v1.3.1 起正式提供官方构建。迁移主要解决以下技术问题：
- 同阶段三的大部分 NeoForge API 替换工作，但需回退至 1.21.1 版本的 API 签名（如 1.21.1 不存在
RegisterConfigScreenEvent，改用IConfigScreenFactory+registerExtensionPoint）。 - NeoForge 1.21.1 零 Architectury 依赖，与独立 Architectury API 无冲突风险，无需桩类处理。
构建环境：
| 组件 | 版本 |
|---|---|
| Java | 21 |
| NeoForge | 1.21.1 对应版本 |
- Stub 只应为目标 JAR 中确实不存在的类创建，真实存在的类必须使用真实实现。
- 方法签名需要精确匹配到包名和参数类型，不能用
Object粗略替代。 javap和字节码检查比猜测 API 更可靠。- 相同类型错误应优先批量修复，避免逐个手动处理。
- 渲染管线、模型渲染和输入事件系统是 26.x 迁移中最需要重点验证的部分。
- Architectury stub 类与真实 API 存在方法签名冲突时，仅靠
depends声明不足以解决——Fabric 版可依赖 Loader 版本去重规避，但 26.1.2 版需源码级包重命名彻底消除碰撞。 - Shadow 插件的 relocate 在 Java 25 项目中不可用（内置 ASM 不支持 class file major version 69），包重定位必须通过源码级修改完成。
- NeoForge 1.21.1 不存在
RegisterConfigScreenEvent，配置界面注册必须使用IConfigScreenFactory+registerExtensionPoint。 swingPulseAge在 tick 中从 1 递增到 2，<=1阈值永远为 false——动画阈值必须基于实际运行行为调试而非文档假设。- 默认模型不在服务端缓存时，C2S 同步包会误判无效——必须为 default 添加专项绕过逻辑。