统一GLTF

用于导入和导出 glTF 2.0 资源的 Unity3D 库。

UnityGLTF 没有任何本机依赖项（纯 C#），因此适用于 Unity 支持的所有平台。这包括 WebGL 导入和导出。

该库旨在通过对 glTF 规范的附加扩展轻松扩展。导入和导出都允许附加自定义插件和回调，并且可以进行大量修改以适应特定的管道。支持许多 glTF 扩展。

• 安装
• Unity 版本和渲染管线兼容性
• UnityGLTF 和 glTFast
• 支持的功能和扩展
  • 导入和导出
  • 仅导入
  • 仅导出
• glTF 交互性
  • 可视化脚本图表导出器
  • 特征
  • 支持
  • 查看器支持
• glTF材料
  • 材料转换
  • 材质和着色器导出兼容性
  • 针对折射材料（透射率和体积）进行配置
    • 材质设置
    • URP
    • 内置
    • HDRP
• 导出 glTF 文件
  • 测试、调试、兼容性
• 动画导出（Animation Export）
  • 动画师控制器
  • GLTFRecorder API
  • 时间线记录器
  • 旧版动画组件
  • KHR_animation_pointer支持
• 混合形状导出（Blend Shape Export）
• 导入 glTF 文件
  • 运行时导入
    • 通过 Gltf 组件加载
    • 通过代码示例加载：
  • 确保着色器在生成中可用
  • 编辑器导入
  • 默认导入器选择
• 动画导入（Animation Import）
• 扩展
  • 自定义插件示例
• 已知问题
• 贡献
  • Unity 包
  • GLTF序列化程序
  • 测试

您可以使用一键式安装程序从 Needle Package Registry 安装此软件包：

1. 下载 UnityGLTF 软件包安装程序
2. 将下载的 .unitypackage 拖放到 Unity 中，然后按照步骤作。

您也可以从 git 安装此包，与 UPM（Unity 包管理器）兼容。

1. 打开Window > Package Manager
2. 点击+
3. 选择Add Package from git URL
4. 糊

   https://github.com/KhronosGroup/UnityGLTF.git
   
5. 点击。Add

注意：如果您想定位到特定版本，请向上述网址追加或提交特定内容。 例：。#release/<some-tag>https://github.com/KhronosGroup/UnityGLTF.git#release/2.14.1

请使用 Unity 的长期支持版本（2021.3+、2022.3+、6000.0+）。

推荐：

• Unity 2021.3+、Unity 2022.3+、Unity 6+
• 线性色彩空间
• 通用渲染管线（URP）和内置渲染管线（BiRP）

HDRP：

• 目前功能有限。

遗产：

• 使用 Unity 2020.3 时，请使用旧版本的 UnityGLTF，例如 2.9.1-rc 及更早版本。

注意：非 LTS Unity 版本（不是 2021.3、2022.3、6000.0 等）上的问题很可能不会得到解决。请尽可能使用 LTS（长期支持）版本。

Unity 注册表中提供了 Unity 的单独 glTF 实现 glTFast。
glTFast 得到 Unity 的支持意味着，简而言之，它非常严格地遵守标准，并且无法轻易发布适用于大多数（但不是全部）用户的未经批准的扩展或实验性功能。

• UnityGLTF 旨在成为更灵活的框架，具有广泛的导入/导出插件支持和开箱即用的有用插件。
• glTFast 旨在成为性能更高的框架，重点是利用 Unity 特定的功能，例如 Burst 和 Jobs。
• UnityGLTF 具有多功能的插件/扩展基础设施。这在导入/导出过程中提供了很大的灵活性。
• UnityGLTF 支持使用并附带未经批准的扩展名，例如 、 和 。KHR_animation_pointerKHR_audioKHR_materials_variants
• glTFast 利用 Unity 特定的功能，例如 Burst 和 Jobs，因此在某些情况下可以具有更好的性能。
• glTFast 具有更好的 HDRP 支持。

glTFast 和 UnityGLTF 可以共存于同一个项目中;例如，您可以使用 glTFast 进行导入，使用 UnityGLTF 进行导出。
对于导入的资源，您可以通过下拉菜单选择要使用的导入器。如果两者位于同一项目中，则
glTFast 导入具有优先权。另请参阅默认导入器选择。

下面的列表是非决定性的，没有特定顺序。请注意，存在一些差距，即 im- 和导出可以轻松支持功能，但目前不支持。欢迎 PR！

• 具有多个剪辑的动画和动画器
• 蒙皮网格渲染器（Skinned Mesh Renderers）
• 混合形状
  • 混合形状的稀疏访问器
• 线性和 Gamma 色彩空间支持（不再维护 Gamma）
• 顶点颜色（Vertex Colors）
• 相机（透视、正交）
• URP 和内置渲染管线了解更多
• KHR_lights_punctual（点光源、聚光源和定向光源）
• KHR_texture_transform（UV 偏移、缩放、旋转）
• KHR_materials_unlit（无光照表面）
• KHR_materials_transmission（玻璃状材料）
• KHR_materials_volume（折射材料）
• KHR_materials_ior（用于传输和音量）
• KHR_materials_emissive_strength（自发光值大于 1）
• KHR_materials_iridescence（薄膜干涉，如水面油）
• KHR_materials_clearcoat（二级镜面层，如一层清漆）
• KHR_materials_sheen（织物表面）
• KHR_materials_specular（部分支持）
• KHR_materials_dispersion（折射率色散）
• KHR_animation_pointer（任意属性动画）
• MSFT_lod（详细级别）
• KHR_node_visibility（游戏对象活动状态）
• KHR_node_hoverability 
• KHR_node_selectability 
• KHR_interactivity（可视化脚本导出为交互性图）

• KHR_mesh_quantization（较小的缓冲区/较小的文件大小）
• KHR_draco_mesh_compression（需要 com.unity.cloud.draco)
• KHR_texture_basisu（需要 com.unity.cloud.ktx)
• EXT_mesh_gpu_instancing（实例数据）
• EXT_meshopt_compression（需要 com.unity.meshopt.decompress) 

• KHR_materials_variants
• KHR_interactivity（可视化脚本图形导出器）
• 时间轴录制器轨道，用于在编辑器中和运行时导出动画
• 导出时的无损关键帧优化
• 所有 2D 纹理都可以导出，包括 RenderTextures——它们在导出时被烘焙。
• 可选插件：导出时将 TMPro 3D 对象烘焙到网格
• 可选插件：导出时将粒子系统烘焙到网格体
• 可选插件：导出时将 Canvas 烘焙到网格体
• 包含的插件示例：KHR_audio_emitter 

该插件允许您将 VisualScripting 图形导出为 glTF 文件中的KHR_interactivity图。

支持多种节点导出。此外，Unity 的可视化脚本具有但 KHR_interactivity 扩展中缺少的许多功能在导出到兼容的图形逻辑时会被“扁平化”。例如，作用域变量将导出为具有唯一名称的变量，因此导出的图形中不存在冲突。这允许在 Unity 编辑器中构建复杂图表的灵活性很大，同时仍然能够导出到 glTF 文件。

• SubGraph 支持
  • 子图将在导出时展平
• 变量
  • 不支持“已保存”变量
• 自定义事件
• 协程
• 一个 glTF 文件中的多个可视化脚本图
  • 多个图形将合并为一个KHR_interactivity图
• 部分列表/数组支持
  • 列表的容量无法在运行时更改，因此请确保在可视化脚本图中创建具有足够大小的列表。
• 数学、向量、矩阵运算
• 部分动画师支持
  • 支持启动动画。当前不支持自动图形转换。
• 逻辑作
• 材质编辑：获取/浮点、颜色、纹理偏移/缩放集
• 属性插值：使用“插值…”节点系列

已经支持许多可视化脚本节点。要查看受支持节点的完整列表，请单击按钮以在控制台中查看受支持节点的完整列表。Project Settings > UnityGLTF > Export > KHR_interactivity (VisualScripting) > Log supported Visual Scripting Units

• 字符串作（KHR_interactivity 扩展不支持）
• 当前缺少四元数数学运算（尚未在KHR_interactivity规范中）
• 某些节点有其他限制。你可以在脚本图表中看到这些内容：
  

这些查看器支持当前的KHR_interactivity规范，并已通过 UnityGLTF 导出器进行了广泛测试：

• 巴比伦：https://sandbox.babylonjs.com/
• Khronos 交互式图创作工具 https://github.khronos.org/glTF-InteractivityGraph-AuthoringTool/

glTF 着色模型基于物理，支持许多不同类型的表面。要在 Unity 中使用 glTF 的扩展材质模型，请使用 材质。
它允许使用各种 glTF 材质扩展进行导入、导出和 Unity 内部。着色器包括URP缺少的许多功能，例如透射和粗略折射、光泽和透明涂层以及每个纹理的UV控制。对于未光照的材质，请使用 。UnityGLTF/PBRGraphUnityGLTF/UnlitGraph

UnityGLTF 包含帮助程序，可以轻松转换为 UnityGLTF/PBRGraph。
将材质从任何着色器切换到 PBRGraph 时，可以运行自动转换以引入属性。
一些着色器已经带有自动转换功能，请参阅下表。

当着色器还没有转换器时，UnityGLTF 会询问您是否要创建转换脚本。这些脚本包含源着色器和目标着色器的所有属性，但尚未指定映射 （，因为这取决于着色器作者的意图） 。创建转换脚本
后，可以对其进行编辑，以正确地从源着色器的属性映射到 PBRGraph 属性。下次将此类着色器切换到 PBRGraph
时，转换脚本将运行并以指定方式自动转换材质。

注意：目前，自定义转换脚本不会自动用于 glTF 导出。为获得最佳效果，请在编辑器中转换材质。

如果要设计 glTF 导出，建议将 Unity 2021.3+ 与 URP 和 UnityGLTF/PBRGraph 材质一起使用。它支持折射和虹彩等现代材料扩展，并允许完美的往返。此材料非常适合在 Unity 内外构建 glTF 管道。

透射和体积允许渲染玻璃等完全透明但仍显示反射的材质，以及体积衰减（例如彩色果冻）和粗糙折射（例如拉丝玻璃）。 要使用这些材质功能，你需要对材质和渲染管线进行一些设置。

1. 在PBRGraph材质上，选中“启用传输”，并选择“启用体积”
2. 根据需要更改透射率、厚度、折射率和衰减值。

要在 Unity 中正确查看透射材质和体积材质，

1. 选择你的URP渲染器资源
2. 在“渲染器功能”部分下，添加“不透明纹理（粗折射）”功能

要在 Unity 中正确查看透射材质和体积材质，

1. 将“粗折射”组件添加到主摄像机。

HDRP 有自己的粗折射支持。目前没有自动导入/导出支持可以转换为该支持。如果需要，请使用 glTFast。

注意：全金属材料永远不会透明。有关详细信息，请参阅KHR_materials_transmission规范。

要从场景或项目导出对象，

1. 选择对象
2. 使用 / 下的菜单项导出Assets > UnityGLTF > Export selected as GLBExport selected as glTF

提示：您可以在 Unity 的快捷方式管理器中设置快捷方式以进行快速导出。例如，对于 GLB 导出和 glTF 导出，允许非常快速的迭代。Ctrl + SpaceCtrl + Shift + Space

现有的各种 glTF 查看器具有不同的功能集。只有少数部分完全覆盖了 glTF 规范，大多数仅支持一个子集。
支持有限的显着功能：

• 每个纹理的设置。textureCoord
• 设置。许多观众干脆忽略了它。textureRotation
• 稀疏访问器。某些查看器仅支持混合形状的稀疏访问器，而其他查看器则根本不支持。
• 顶点颜色。

要查看您的 glTF 文件，您可以使用以下多种工具：

要在使用 UnityGLTF 导出文件后进一步处理文件，您可以使用：

动画可以在编辑器中和运行时导出。 编辑器导出适用于 Animator（多个剪辑）、动画（多个剪辑）和时间轴（GLTFRecorderTrack）。

您可以将整个动画师及其剪辑导出为具有多个动画的 glTF 文件。
动画剪辑将以动画器控制器中的每个运动状态命名。
每个运动的“速度”属性将烘焙到导出的剪辑中。当您想要导出不变时，请确保速度为 1。支持层次结构中
任意数量的动画师，以及这些层次结构中任意数量的剪辑。

将导出人形和通用动画。人形动画在导出时烘焙到目标绑定上。

注意：Animator 导出仅适用于编辑器。对于运行时导出，请使用 GLTFRecorder 功能或时间线记录器。

要在运行时创建和/或录制动画，您可以使用 GLTFRecorder API。它允许捕获整个层次结构和复杂动画的状态，并将它们直接导出为 glTF 文件， （可选）KHR_animation_pointer支持复杂的材质和属性动画。
有关示例实现，请参阅。GLTFRecorderComponent

时间线或它们的部分可以用 和 一个或多个 来记录。 时间线录制在后台使用 GLTFRecorder API。GltfRecorderTrackGltfRecorderClips

注意：动画组件导出仅适用于编辑器，因为 Unity 不提供所需的运行时访问权限。对于运行时导出，请使用功能。GLTFRecorder

动画组件及其旧剪辑也可以导出。

UnityGLTF 支持导入和导出带有 KHR_animation_pointer 扩展名的动画。 核心 glTF 规范仅允许动画节点变换和混合形状权重，而此扩展允许对 glTF 文件中的任意属性进行动画处理 – 包括材质和对象属性，甚至在自定义扩展和脚本组件中也是如此。

可以通过启用 KHR_animation_pointer 插件来打开使用 KHR_animation_pointer 导出。Project Settings > UnityGLTF

注意：导出的文件可以使用 Gestaltor、Babylon Sandbox 和 Needle Engine 查看，但目前不能使用 three.js / model-viewer 查看。参见 mrdoob/three.js#24108。

支持变形目标/混合形状/形状关键帧，包括动画。
要为复杂的混合形状动画（例如具有数十种形状的面）创建较小的文件，请在启用“稀疏访问器”设置的情况下导出。

要在运行时导入 or 文件，您可以使用 用于加载。.gltf.glbGLTFComponent

从本地文件：

string dir = "C:SamplePath";
string filename = "AntiqueCamera.glb";

var importOpt = new ImportOptions();
importOpt.DataLoader = new UnityWebRequestLoader(dir);
var import = new GLTFSceneImporter(filename, importOpt);
await import.LoadSceneAsync();

从网络：

string uriDir = "https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/AntiqueCamera/glTF-Binary/";
string filename = "AntiqueCamera.glb";

var importOpt = new ImportOptions();
importOpt.DataLoader = new UnityWebRequestLoader(uriDir);
var import = new GLTFSceneImporter(filename, importOpt);
await import.LoadSceneAsync();

访问加载的 gltf 场景：

import.LastLoadedScene

在加载的 gltf 场景中，您将找到该组件。使用该方法创建加载场景的副本。InstantiatedGLTFObjectDuplicate

请确保你已在 . 否则，生成中可能缺少着色器。请注意，在第一次构建时，编译时间可能需要一些时间。UnityGLTFShaderVariantCollectionUnityGLTFShaderVariantCollection-BiRPProject Settings > Graphics > Preloaded Shaders

当您为移动平台构建并且需要更小的着色器尺寸，并且您知道您真正需要哪些着色器功能时，最好创建自己的着色器变体集合。

您还可以剥离下面的其他着色器变体，以减少着色器编译时间。Project Settings > UnityGtlf > Build

要在编辑器中导入或文件，请像往常一样将它们放置在项目中（资产或包）。 确保为具有正确相对路径的文件携带.bin/纹理;通常是独立的。.gltf.glb.gltf.glb

在 Unity 中移动文件时，请确保同时移动其.bin/纹理文件，以免破坏它们之间的路径引用。.gltf

UnityGLTF 会将自己注册为 和 的默认导入器。扩展。
如果项目中也存在 glTFast 包，则 glTFast 优先，并且 UnityGLTF 可用作导入器覆盖，可以从每个 glTF 资产的下拉列表中选择。.gltfglb

UnityGLTF 使用 Unity 的系统。对于任何给定的文件格式（文件扩展名），必须有一个默认导入器，并且可以有其他替代导入器。
您可以通过将以下设置添加到项目的 ：ScriptedImporterScripting Defines

GLTFAST_FORCE_DEFAULT_IMPORTER_OFF
UNITYGLTF_FORCE_DEFAULT_IMPORTER_ON

我们注意对齐 glTFast 和 UnityGLTF 的导入器，以便在大多数情况下您可以在它们之间切换而不会破坏预制件引用。话虽如此，在导入器之间切换可能会更改材质引用、网格引用等，因此可能需要进行一些手动调整。 您可能需要调整每个导入器的根剥离设置（glTFast 和 UnityGLTF 的处理方式略有不同）。

动画可以在编辑器和运行时导入。
在导入器上，您可以在“旧版”、“Mecanim”或“人形”剪辑之间进行选择。

在运行时，如果您要导入“Mecanim”剪辑，则需要确保通过脚本（例如动画师控制器或时间轴）将它们添加到可播放图表中以播放它们。

UnityGLTF 具有导入和导出插件。作为常规导出和导入过程的一部分，这些具有用于修改节点结构、扩展数据、材质等的回调。它们在编辑器和运行时都使用。 您可以制作自己的插件并在菜单中启用它们。
插件是可以有设置的 ScriptableObject;它们作为 GLTFSettings 资产的一部分进行序列化。 插件创建导入/导出处理程序的具体实例。Project Settings > UnityGLTF

要创建插件，请按照下列步骤作：

1. 创建一个继承自 或 的类。这是包含插件设置的 ScriptableObject。GLTFImportPluginGLTFExportPlugin
2. 此外，创建一个继承自 或 的类。此类具有实际的回调。GLTFImportPluginContextGLTFExportPluginContext
3. 在插件中实现以返回插件上下文的新实例。CreateInstance
4. 覆盖要在插件上下文中使用的回调。

如果您的插件读取/写入自定义扩展数据，您还需要实现序列化和反序列化。GLTF.Schema.IExtension

public class MyExportPlugin : GLTFExportPlugin
{
    public override string DisplayName { get => "My Custom Plugin"; }
    public override bool EnabledByDefault => true;
    public override bool AlwaysEnabled => false;
    
    public override GLTFExportPluginContext CreateInstance(ExportContext context)
    {
        return new MyExportPluginContext();
    }
}

public class MyExportPluginContext: GLTFExportPluginContext
{
    public override bool ShouldNodeExport(GLTFSceneExporter exporter, GLTFRoot gltfRoot, Transform transform)
    {
        return !transform.CompareTag("ignore");
    }
}

🏗️ 正在施工中。你可以看一个例子。MaterialVariantsPlugin.cs

• 中间的混合形状将不会被导出，因为 glTF 没有该功能。
• 对具有多个场景的 glTF 文件的支持有限。

UnityGLTF 是一个开源项目。欢迎经过充分测试的 PR。

UnityGLTF 目前由

• 前额叶皮层，Khronos 集团的成员和
• Needle，元宇宙标准论坛成员。

注意：从 20240129 年起，此存储库的默认分支已从 重命名为 。mastermain

"testables": [
	"org.khronos.unitygltf"
]