Polymesh

Polymesh

Polymesh是一个Forge/NeoForge 1.20.1客户端运行时，用于渲染来自模组资源的glTF 2.0模型。

Polymesh预览查看大图

Polymesh

Polymesh 是一个 Forge/NeoForge 1.20.1 客户端运行时，用于从模组资源中渲染 glTF 2.0 模型。

打包

  • 运行时库 jar：polymesh-1.0.0-forge.jar
  • 演示/测试 jar：the_utah_teapot-1.0.0-forge.jar
  • CesiumMan 验证 jar：cesium_man_demo-1.0.0-forge.jar
  • glTF 资源会在 assets/<modid>/models/gltf/*.gltf 和 *.glb 目录下被自动发现。

物品注册

正常注册物品，然后在客户端初始化期间注册其 glTF 模型：

PolymeshApi.registerItemRenderer(item, new ResourceLocation("mymod", "model_name"),
    GltfRenderOptions.builder()
        .scale(1.0f)
        .animationClip("Walk")
        .loopAnimation(true)
        .build());

该物品仍需要从 initializeClient 提供自定义渲染器；在那里返回 new GltfItemRenderer(theItem)——它会读取上述注册的模型 ID 和选项，因此它们只存在于一个地方。

运行时说明

  • 静态非蒙皮网格只上传一次到共享 GPU 缓冲区，并由物品实例复用。
  • 蒙皮或带形态目标的物品网格使用持久的 VAO/VBO/EBO 对象，并根据动画姿势版本进行动态顶点缓冲区刷新。这避免了每帧 VertexConsumer 三角形发射，只在动画、蒙皮或形态姿势变化时才重新计算变形顶点。
  • 保留 glTF 中的法线。缺失的法线会在加载时一次性生成。
  • 保留 glTF 中的切线。当 UV 可用于运行时数据消费者时，会生成缺失的切线。
  • 嵌入的 .glb 图像会在模型加载时注册为动态 Minecraft 纹理。
  • 资源重载会清除 GPU 缓冲区并重建已加载的模型。
  • 物品、实体和方块实体渲染器共享同一个渲染后端（PolymeshRenderer），它优先使用 GPU 静态/动画路径，并在需要时（例如在激活着色器包时）回退到 CPU 顶点消费者路径。
  • glTF extras、扩展列表、节点名称、形态目标名称和带姿势的节点变换会保留供游戏逻辑使用。

支持的功能

  • 带相对缓冲区/图像的 glTF 2.0 .gltf 文件
  • 二进制 .glb 文件
  • 节点层级和 TRS/矩阵变换
  • 带基础颜色纹理/因子和 Alpha 模式的材料
  • 用于物品渲染的蒙皮、逆绑定矩阵、形态目标和动画通道
  • 用于附着点、命中框驱动和游戏代码的运行时节点/骨骼查找
  • 具名形态目标查找和运行时形态权重覆盖
  • 模型、节点和材料上的 glTF extras 元数据

演示模组

  • teapot 包含静态 Utah Teapot 物品和一个 CesiumMan 物品。
  • cesium-man 是一个最小验证模组，只有一个由 assets/cesium_man_demo/models/gltf/cesium_man.glb 支持的 cesium_man 动画物品。

着色器说明

Polymesh 保留 glTF 资源中编写的法线，并通过原版风格的实体渲染状态进行渲染。它不声称提供着色器包端的平滑法线修复；那些从自有几何管线推导光照的着色器包可能仍需要着色器端的支持。

许可证

Polymesh —— 一个用于 Minecraft Forge/NeoForge 1.20.1 的 glTF 2.0 模型渲染库 版权所有 (C) 2026 Phe

本库是自由软件：你可以根据自由软件基金会发布的 GNU 较宽松公共许可证的条款重新分发和/或修改它，无论是许可证的第 3 版，还是（按你的选择）任何更高版本。

分发本库是希望它会有用，但不提供任何担保；甚至没有对适销性或特定用途适用性的默示担保。详情请参阅 GNU 较宽松公共许可证。

你应该已经随本库收到了一份 GNU 较宽松公共许可证的副本（见 LICENSE.LESSER 和 LICENSE）。如果没有，请参阅 https://www.gnu.org/licenses/。

捆绑的依赖项： jgltf（MIT）和 Jackson（Apache-2.0）已按各自许可证重新打包在 forge jar 内。