Conf-Engine

面向 TurboWarp 的蒙皮骨骼动画引擎

#Simple3D #TurboWarp #extension #Skeleton #Skin

---

Conf Engine 4.1/4.2 使用指南

加载 & 绘制

3. 引擎配置： 在 TurboWarp 的 GLTFLoader 中新建变量，通过文件扩展将该变量设置为data:URL形式导入的.glb文件。
4. 加载积木： 在广播 Load 下，使用 Load from ( ) ( ) 自制积木，将变量拖入,并为其命名。
5. 渲染执行： 在 Render 的重复执行中添加 Draw ( ) 积木，填入要渲染的模型的名称。
6. 点击绿旗运行。

骨骼 & 动画

• 程序动画： 在广播 Animation 下，使用 设置模型( )骨骼( )局部矩阵( ) 积木来修改骨骼局部姿态。
• 骨骼动画： 使用 Play Animation ( ) ( ) 播放预设动画。
• 更新矩阵: 修改局部矩阵后，需使用 更新模型 ( ) 的骨骼层级继承计算 来重新计算骨骼当前(current)绝对坐标系矩阵

---

Conf Engine 3 使用指南

加载 & 绘制

1. 导出模型： 在 Blender 里导入 flexgltf_export.py 脚本，修改脚本最后一行的目录为你想要的导出目录。
2. 场景准备： 物体模式下按 A 全选场景，运行脚本，等待导出为 JSON 文件。（⚠注意，请确保模型没有将所有网格合并，如果已合并，请按部件或材质拆分）
3. 引擎配置： 在 TurboWarp 的 GLTFLoader 中新建变量，通过文件扩展将该变量设置为导出的 JSON 内容。
4. 加载积木： 在广播 Load 下，使用 Load from ( ) 自制积木，将变量拖入。
5. 渲染执行： 在 Render 的重复执行中添加 Draw ( ) 积木，填入 JSON 的文件名。
6. 点击绿旗运行。

骨骼 & 动画

• 程序动画： 在广播 Animation 下，配合 Matrix 扩展使用 设置模型( )骨骼( )局部矩阵( ) 积木。
• 骨骼动画： 使用 Play Animation ( ) ( ) 播放预设动画。
• 更新矩阵: 修改局部矩阵后，需使用 更新模型 ( ) 的骨骼层级继承计算 来重新遍历计算骨骼当前(current)绝对坐标系矩阵

---

技术细节&工作流

• blender插件：生成易被scratch读取和处理的高度定制化模型格式（文件后缀为.json），格式参考了glTF

  • 格式mesh对象：为了性能，该定制格式没有层级node结构，所有mesh都是平铺；每个网格包含name、mat、tex、v、uv、b_idx、b_wt。
  • 与传统glTF不同，为了scratch读取方便，脚本将所有的顶点信息直接嵌入对应的网格对象结构中而不引用外部二进制文件
  • name：网格名 mat：材质名 tex：贴图名 v：交错布局的顶点坐标，已自动三角化，方便后续直接提交给GPU uv：uv b_idx：骨骼索引 b_wt：骨骼权重
  • skeleton对象：具有层次继承结构，保存了场景骨骼初始绑定姿态下的绝对坐标系矩阵、骨骼局部坐标系矩阵
  • animation对象：出于性能考虑，格式十分精简，每个动画以name为key，包含duration、tracks
    • duration：该动画持续时间 tracks：动画槽
      • tracks是中是一系列的骨骼变换流，记录每一关键帧中姿态有改变的骨骼的索引、TRS以及时刻。姿态无变化的骨骼不会记录，以节省空间

• FlexGLTF扩展：核心扩展，解析、句柄、计算、输出

  • 读取json文件，保存场景网格信息
  • FlexGLTF会遍历骨骼树，将骨骼的 初始(original)绝对坐标系矩阵、骨骼局部坐标系矩阵保存在内存中，并额外使用一部分内存存放一套 当前(current)绝对坐标系矩阵
  • scratch层会从FlexGLTF中读取网格信息，比如VBO，提交给SImple3D（GPU）。
  • FlexGLTF会单独提取出当前网格会用到的所有骨骼（为每个网格单独创建handles），把每个顶点在handles中用到的骨骼的索引作为bone_indices，调用 set mesh ( ) bone indices 上传给simple3D
  • 用户可以在渲染循环(renderLoop)中每帧修改骨骼的局部坐标系矩阵，并在修改后调用 更新模型 ( ) 的骨骼层级继承计算 积木。此积木会重新遍历骨骼树，对所有骨骼进行层次继承变换，并将计算好的结果写入内存中的 当前(current)绝对坐标系矩阵
  • 最后，在调用Simple3D的 Draw Mesh（） 之前，scratch层的积木会将调用 set mesh ( ) current matrix 把当前绝对坐标系矩阵，对每个网格挑取它们会用到的那部分，组成矩阵流上传。

• OmniGLB v1.2.0 扩展：核心逻辑同FlexGLTF

  • 不同点1：直接解析base64编码的.glb文件，读取场景节点、网格、骨骼、动画
  • 不同点2：不再以Joint为基础，改为以Node为基础，可以轻松管理网格模型对象、计算网格之间的基础，并处理节点动画

---

许可、致谢与开发环境 (License, Credits & Environment)

本项目采用分层授权模式，以平衡开发灵活性与核心组件的开源保护：

1. 授权说明 (Licensing)

• 引擎逻辑 (.sb3): 采用 MIT License 开源。包含所有在 TurboWarp 编辑器中编写的积木逻辑。您可以自由重混、分发及商用。
• 核心扩展与插件: 采用 Mozilla Public License 2.0 (MPL 2.0) 开源。
  • 涉及文件：FlexGLTF.js (3D 蒙皮骨骼动画解析器)、OmniGLB.js (3D 蒙皮骨骼动画解析器)、export.py (Blender 导出脚本)。
  • 核心要求： 如果您修改了这些特定的源代码文件，必须以 MPL 2.0 协议公开您的修改。

2. 技术参考与环境 (Environment & Reference)

• glTF™ 参考: 核心扩展 FlexGLTF 的数据交换格式参考了 glTF™ (GL Transmission Format) 开放标准。本项目是针对 TurboWarp 环境优化的自定义实现。
• TurboWarp: 本项目专为 TurboWarp 环境设计。特此声明：TurboWarp 是一个独立的开源项目，不属于 Scratch 或 MIT。 本项目利用了其高性能编译器及动态扩展加载能力。
• Blender: 本项目使用 Blender 进行 3D 建模与动画预处理。配套的 export.py 插件作为独立脚本运行于 Blender 环境下。

4. 人工智能使用声明 (AI-Assisted Work Declaration)

本项目遵循开发者原创原则，并借助人工智能工具进行了优化：

• 核心逻辑： 本项目的整体架构、引擎逻辑设计（.sb3 积木架构）以及 FlexGLTF 的核心实现均由本人独立完成。
• 辅助修缮： 在开发过程中，我借助了人工智能（Google Gemini）进行代码调试（DeBug）、语法润色以及部分法律声明文档的辅助撰写。
• 最终审核： 所有由 AI 生成或建议的内容均经过本人严格审核、修改与实机测试，确保其符合项目的技术规范与安全要求。

4. 第三方扩展致谢 (Third-Party Credits)

本项目集成了以下优秀的开源扩展，对原作者表示诚挚感谢：

• Simple3D Extension - 作者：Vadik1 (Xeltalliv) 访问源码
• JSON Extension - 作者：Skyhigh173 与 Mio 访问源码
• Files Extension - 作者：TurboWarp 贡献者 访问源码

详情请参阅仓库根目录下的 LICENSE 文件。