OpenYSM

YSM开源替代品，基于2.6.5，当前工作树为 Fabric 1.20.1 port

说明

本仓库是面向 YesSteveModel (YSM) 2.6.5（2026年4月）行为兼容目标的实验性开源实现。

仓库包含 1.20.1 Forge 版本的 Java 端实现源码。请注意，OpenYSM-Experimental 不是 YesSteveModel 官方项目，也不包含或分发 YesSteveModel 原始 Native/C++ 源代码。

请注意：项目并非 Production Ready，可能存在命名语义错误，渲染错误等问题，如果您在使用过程中遇到了任何问题请打开 Issue 反馈，最好附带截图和可能的报错日志。

当前进度（OpenYSM-Experimental）

这个分支目前重点不是做一个稳定发布版，而是把 OpenYSM 的加载、兼容、Java fallback 和 native 渲染实验整理成可测试的工作树。

当前已经接入或验证：

• Fabric Loom 1.20.1 单 jar 构建已接入，mod id 仍为 yes_steve_model，入口为 Fabric common/client initializer。
• Forge 平台调用已替换或 shim 到 Fabric：配置、平台路径、mod 检测、声音注册、生命周期、事件、命令、网络和能力存储都可在 Fabric 编译。
• 可选第三方兼容先做 Fabric-safe stub：CarryOn、Curios、Oculus、Touhou Little Maid 等外部 API 不再阻塞核心 jar 编译；真实 Fabric 集成需要逐个验证 API 后再恢复。
• Forge 1.20.1 / YSM 2.6.5 的 Java 侧模型加载、渲染、动画控制器、音频和纹理解码路径。
• 现代已加密 .ysm 模型加载，以及原版/旧版 YSM flat-folder 结构兼容：info.json、main.json、arm.json、*.animation.json 和纹理可以合成为当前 descriptor 结构。
• 旧版 .ysm 读取 fallback：优先走新版 YsmCrypt.decryptYsmFile，失败后尝试 legacy YSGP v1/v2 解包并交给 folder deserializer。
• legacy extra.animation.json 会补齐 properties.extra_animation，让动画轮盘能显示和触发旧模型的额外动画。
• legacy/未加密兼容性 harness 已接入：当前覆盖 27 个内置未加密 folder 模型、去掉 ysm.json 的 flat-folder fixture、2 个本地私有 format 9/15 .ysm 真实样本，以及 2 个单顶层模型目录 .zip 导出样本。私有样本不入仓，可用 ./gradlew legacyModelCompatibilityHarness -Pysm.compatFixtureDir=/path/to/fixtures 复跑。
• 默认模型握手/同步路径已修正，避免客户端和服务器在默认模型处理上不一致。
• 可选 native renderer 已接入 Java/JNI render-first fast path：
  • 配置模式保留 AUTO、OFF、RENDER_ONLY、FULL_EXPERIMENTAL。
  • AUTO 仍默认走 Java renderer；要测试 native 需要选择 RENDER_ONLY 或使用 -Dysm.nativeRenderer=render。
  • /openysm native status 和 /openysm native parity 可用于查看 native 状态和做 Java/native 输出对比。
  • 当前 native 后端是 scalar CPU path，不包含 AVX2/SIMD。
  • Windows x64 已有实机渲染验证；CPU Scalar V2 的本地 harness 已通过，Windows 场景 FPS/回归测试仍需要继续跑。

仍然实验中：

• native renderer 永久保留 Java fallback；任何 native 库加载、自检、缓存、DirectBuffer 或兼容路径失败都应回退 Java。
• 旧版/未加密模型仍可继续扩充更多第三方真实样本矩阵；当前已覆盖本地 format 9/15 与未加密 folder/zip 样本。
• AVX2/SIMD、GPU renderer、native parser/audio/crypto/zstd 加速暂时不是当前补丁目标。

Fabric port 代码边界

Fabric port 现在保留三类兼容代码，避免核心逻辑在迁移期间被大规模改写：

• net.minecraftforge.* 只作为临时 Forge API 兼容层存在，用来承接尚未完全改成 Fabric API 的配置、事件、网络和 registry 调用。
• src/fabricStubs/java 只保留仍被核心路径引用的第三方 mod no-op stub；已经不需要独立类的 no-op 兼容会合并到 OpenYSM 自己的 Fabric 边界。
• src/generated/resources/META-INF/native 是发布 jar 需要携带的 native renderer 资源，不属于可删除的兼容脚手架。

清理优先级是先删掉重复的 Fabric stub，再逐步把 Forge shim 调用替换成 OpenYSM 自己的 Ysm* 平台/网络/配置封装。真实第三方 Fabric 集成只有在确认对应 API 后再恢复。

构建与验证

当前 Fabric 开发 jar 输出到 build/devlibs/，可发布/安装的 remap 后 jar 输出到 build/libs/ysm-2.6.5-fabric+mc1.20.1.jar。

常用检查：

• ./gradlew compileJava
• ./gradlew legacyModelCompatibilityHarness
• ./gradlew legacyModelCompatibilityHarness -Pysm.compatFixtureDir=/path/to/fixtures
• ./gradlew nativeRendererHarness
• ./gradlew remapJar
• ./gradlew runServer
• git diff --check

为什么开源？

我们决定将新版 YSM 源码开源，主要基于以下几个原因：

1. 独立实现

本项目的加载和渲染逻辑以 Java 重新实现，目标是在保持资源格式兼容的同时降低对 Native 组件的依赖。

我们发布该实验性实现，供社区学习、研究、测试和二次开发。

2. 新版加密的现状

此前社区已经出现了一个破解 YSM 2.6.5 及以下版本加密的工具和方法，新版的加密机制实际上已经失去了保护作用。

同时，目前社区中的大部分新模型都已经公布了源文件或者被解密，新版加密已经毫无实际意义。

3. 支持开放的游戏氛围

我们注意到社区中没有开发者制作了去除加密功能的最新 YSM 版本，这表明了这是一个蓝海市场。

OpenYSM 开发组一直非常支持开放、自由的游戏开发氛围，我们希望通过开源新版源码，为其他开发者的二次开发和学习提供便利。

TODO

• Ogg Opus音频解码播放
• Webp、Avif等纹理的解码
• 符合YSM标准的服务器客户端通讯握手流程
• 模型的读取与渲染
• Fabric 1.20.1 单 jar 构建、metadata、入口和基础运行路径
• Forge 平台服务迁移为 Fabric wrapper/shim，核心命令、网络、事件和能力存储可编译运行
• 可选第三方 mod 兼容先降级为 Fabric-safe stub，避免核心 OpenYSM 因外部 API 缺失失败
• 子模型动画控制器
• 与服务器通讯握手时默认模型未正确处理
• 原版/旧版 flat-folder 模型结构兼容：info.json、main.json、arm.json、动画 JSON 和纹理
• legacy .ysm fallback 读取路径已接入
• legacy extra animation 会补齐动画轮盘数据
• 更多低版本二进制模型/未加密模型真实样本兼容性测试：legacyModelCompatibilityHarness 已覆盖内置未加密模型、去 descriptor flat-folder、私有 format 9/15 .ysm 和单顶层目录 zip 导出样本
• 可选 scalar native render-first fast path 已接入；Windows x64 已通过实机渲染验证，Java fallback 永久保留
• CPU Scalar V2 native harness 已覆盖骨骼父子层级、part mask、36-byte packed 输出、glow light、projection culling、隐藏骨骼、动画变换和非均匀缩放法线
• CPU Scalar V2 在 Windows benchmark 场景中继续做 /openysm native parity 和 FPS 回归
• 逐个恢复并验证真实 Fabric 第三方兼容实现
• AVX2/SIMD native renderer 优化（等 scalar path 足够稳定后再做）
• YSGPHeader生成

修改

我们相比已经发布的 YSM 版本做出了以下修改

• 使用 Java 重写了加载和渲染逻辑，现在可以脱离原始 Native/C++ 运行，例如在 MacOS、RISC-V 甚至手机上
• 支持现有的已加密的 YSM 模型
• 支持一部分原版/旧版 YSM 模型目录和旧 .ysm 包作为兼容输入
• 兼容单顶层模型目录的 .zip 导出包，方便复用原版/旧版模型导出结果
• 补齐旧模型 extra animation 到动画轮盘所需的 metadata
• 添加了可选 native scalar renderer，用于测试 Java/JNI 直写顶点缓冲的渲染加速；默认仍以 Java renderer 为稳定 fallback
• 添加了/openysm cache dump命令帮助你调试模型传输，导出服务器中的所有模型
• 添加了/openysm native status和/openysm native parity命令帮助你调试 native renderer 状态和 Java/native 输出一致性

开源协议

源代码协议

本项目的源代码采用 MIT License 开放，您可以自由地使用、修改和分发代码，仅需要保留原始的版权声明。

详细的许可证条款请参见 LICENSE 文件。

模型资源协议

仓库中自带的模型文件采用不同的协议：

• 默认模型: 采用 CC0 (Creative Commons Zero) 协议，完全开放，无任何使用限制
• 酒狐 (Wine Fox) 模型: 采用 CC BY-NC-SA 4.0 协议，允许非商业使用，需要署名，并且衍生作品需要采用相同协议

请在使用相应模型时严格遵守对应的协议要求。

使用建议

我们鼓励开发者基于此源码进行二次开发，创造出更加开放、易用的模型加载工具。