From 8695598d018d700ba85bcdbc660f07581edd09b8 Mon Sep 17 00:00:00 2001 From: hybridherbst Date: Wed, 3 Jan 2024 10:31:04 +0100 Subject: [PATCH] readme adjustments --- README.md | 181 ++++++++++++++++++++++++++---------------------------- 1 file changed, 88 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index dcc051780..886c46a25 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # UnityGLTF -![Good coverage of glTF 2.0.](https://img.shields.io/badge/glTF%20Spec-2.0-brightgreen) +![Great coverage of glTF 2.0.](https://img.shields.io/badge/glTF%20Spec-2.0-brightgreen) ![Unity 2021.3+ and URP recommended](https://img.shields.io/badge/Unity-2021.3%E2%80%932023.1%2B-brightgreen) -![Support for 2018.4–2019.4 is not actively maintained](https://img.shields.io/badge/Unity-2019.4%E2%80%932020.3-yellow) +![Support for 2020.3 is not actively maintained](https://img.shields.io/badge/Unity-2020.3-yellow) ![URP supported](https://img.shields.io/badge/Render%20Pipeline-URP-brightgreen) ![BiRP supported with better support on 2021.3+](https://img.shields.io/badge/Render%20Pipeline-Built--in-brightgreen) @@ -17,7 +17,7 @@ Unity3D library for importing and exporting [glTF 2.0](https://github.com/Khrono UnityGLTF doesn't have any native dependencies (pure C#) and thus works on all platforms that Unity supports. This includes WebGL import and export. -The library is designed to be easy to extend with additional extensions to the glTF specification. Both import and export allow attaching custom callbacks and can be heavily modified to fit into specific pipelines. Many glTF extensions are supported. +The library is designed to be easy to extend with additional extensions to the glTF specification. Both import and export allow attaching custom plugins and callbacks and can be heavily modified to fit into specific pipelines. Many glTF extensions are supported. ## Contents - [Installation](#installation) @@ -96,46 +96,44 @@ These configurations have been working in the past. They will not be updated wit UnityGLTF hasn't received official support since early 2020. However, a number of forks have fixed issues and improved several key areas, especially animation support,export workflows, color spaces and extendibility. These forks have now been merged back into main so that everyone can benefit from then, and to enable further work. A separate glTF implementation for Unity, [glTFast](https://github.com/atteneder/glTFast), is on its path towards becoming feature complete. -At the time of writing glTFast has better _import support_ and UnityGLTF has better _export support_. +At the time of writing they have about the same level of _import support_ and UnityGLTF has better _export support_. glTFast and UnityGLTF can coexist in the same project; you can for example use glTFast for import and UnityGLTF for export, where each of these shine. For imported assets, you can choose which importer to use with a dropdown. glTFast import has precedence if both are in the same project. -Key differences of glTFast include: -- It leverages modern Unity features such as Burst and Jobs and thus has better performance in some cases -- Better import support: allows importing compressed textures and meshes - – Slightly better coverage of the glTF Spec: texture transforms for other textures than baseMap and occlusionMap are supported -- HDRP import support. - -> **TL;DR:** -> - UnityGLTF has very good export support (runtime, editor, animations, materials). -> - glTFast has better general import support (compressed meshes and textures, HDRP support). -> - If you're using custom extensions, UnityGLTF might still be the right choice for import for its extensibility. +Key differences to glTFast include: +- glTFast leverages Unity-specific features such as Burst and Jobs and thus can have better performance in some cases +- glTFast has better HDRP support. +- UnityGLTF has a versatile plugin/extension infrastructure. This allows for a lot of flexibility during import/export. +- UnityGLTF enables using non-ratified extensions such as `KHR_animation_pointer`, `KHR_audio`, and `KHR_materials_variants` to allow testing how they fit into production pipelines. ## Supported Features and Extensions The lists below are non-conclusive and in no particular order. Note that there are gaps where features could easily be supported for im- and export but currently aren't. PRs welcome! ### Import and Export -- Animations, Skinned Mesh Renderers, Blend Shapes +- Animations +- Skinned Mesh Renderers +- Blend Shapes + - Sparse accessors for Blend Shapes - Linear and Gamma colorspace support (Gamma won't be maintained anymore) - Vertex Colors -- Cameras +- Cameras (perspective, orthographic) - URP and Built-In Render Pipeline [Learn More](#material-and-shader-export-compatibility) -- KHR_lights_punctual (Point, Spot, Directional Lights) -- KHR_texture_transform +- KHR_lights_punctual (point, spot, and directional lights) +- KHR_texture_transform (UV offset, scale, rotation) - KHR_materials_unlit -- KHR_materials_transmission -- KHR_materials_volume -- KHR_materials_ior -- KHR_materials_emissive_strength -- KHR_materials_iridescence -- KHR_materials_clearcoat -- KHR_materials_sheen (partial support) +- KHR_materials_transmission (glass-like materials) +- KHR_materials_volume (refractive materials) +- KHR_materials_ior (for transmission and volume) +- KHR_materials_emissive_strength (emissive values greater than 1) +- KHR_materials_iridescence (thin-film interference, like oil on water) +- KHR_materials_clearcoat (secondary specular layer, like a coat of varnish) +- KHR_materials_sheen (cloth, partial support) - KHR_materials_specular (partial support) +- MSFT_lods (level of detail) ### Import only -- MSFT_LODExtension - KHR_mesh_quantization - KHR_draco_mesh_compression (requires com.atteneder.draco) - KHR_texture_basisu (requires com.atteneder.ktx) @@ -144,53 +142,28 @@ The lists below are non-conclusive and in no particular order. Note that there a ### Export only - KHR_animation_pointer -- Sparse accessors for Blend Shapes - Timeline recorder track for exporting animations at runtime - Lossless keyframe optimization on export (animation is baked but redundant keyframes are removed) -- All 2D textures can be exported, no matter if readable or not, RenderTextures included – they're baked at export. +- All 2D textures can be exported, RenderTextures included – they're baked at export. ## glTF Materials To leverage the extended material model of glTF in Unity, use the `UnityGLTF/PBRGraph` material. -It allows the use of various glTF material extensions for import, export, and inside Unity. +It allows the use of various glTF material extensions for import, export, and inside Unity. +This includes features that URP is missing, such as transmission, volume, and per-texture UV control. ### Material Conversions UnityGLTF contains helpers to make converting to UnityGLTF/PBRGraph easy. -When you switch a material from any shader to PBRGraph, an automatic conversion can run to bring the properties over in the best possible way. -Some shaders already come with automatic conversions: -- `Standard` -- `URP/Lit` -- `URP/Unlit` +When you switch a material from any shader to PBRGraph, an automatic conversion can run to bring the properties over. +Some shaders already come with automatic conversions, please see the table below. -When a shader doesn't have a converter yet, UnityGLTF will ask if you want to create a *Conversion Script*. These scripts contain all properties of the source shader and the target shader, but no specified mapping yet (as that dependends on the intent of the shader author). +When a shader doesn't have a converter yet, UnityGLTF will ask if you want to create a *Conversion Script*. These scripts contain all properties of the source shader and the target shader, but no specified mapping yet (as that depends on the intent of the shader author). After the conversion script has been created, you can edit it to correctly map from the source shader's properties to PBRGraph properties. When you switch such a shader to PBRGraph the next time, your conversion script will run and automatically translate the materials in the specified way. > **Note:** Currently, conversion scripts aren't used automatically on glTF export. Convert materials at edit time for best results. -### Configure for Refractive Materials (Transmission and Volume) - -Transmission and Volume allow rendering materials like glass, that are fully transparent but still show reflections, as well as volume attenuation (e.g. colored jelly) and rough refraction (e.g. brushed glass). - -> **Note**: Fully metallic materials are never transparent. See [the KHR_materials_transmission spec](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_transmission/README.md#transparent-metals) for more info. - -#### Material Setup -1. On a PBRGraph material, check "Enable Transmission" and optionally "Enable Volume" -2. Change the Transmission, Thickness, Index of Refraction and Attenuation values as desired. - -#### URP -To see transmissive and volume materials correctly in Unity, -1. Select your URP Renderer Asset -2. Under the "Renderer Features" section, add a "Opaque Texture (Rough Refraction)" feature - -#### Built-In -To see transmissive and volume materials correctly in Unity, -1. Add the "RoughRefraction" component to your Main Camera. - -#### HDRP -HDRP has its own rough refraction support. There's currently no automatic import / export support to convert to that. Use glTFast if you need this. - ### Material and Shader Export Compatibility If you want to design for glTF export, it's recommended to use Unity 2021.3+ with URP and the **UnityGLTF/PBRGraph** material. It comes with support for modern material extensions like refraction and iridescence, and allows for perfect roundtrips. Great for building glTF pipelines in and out of Unity. @@ -211,23 +184,37 @@ If you want to design for glTF export, it's recommended to use Unity 2021.3+ wit | HDRP (limited support) | HDRP/Lit | | Unity | | | HDRP/Unlit | | Unity | -### Legacy -These extensions and shaders worked in the past but are not actively supported anymore. +### Configure for Refractive Materials (Transmission and Volume) -- KHR_materials_pbrSpecularGlossiness - *This extension has been deprecated by Khronos. Please use pbrMetallicRoughness instead.* - - GLTF/PbrSpecularGlossiness (legacy shader from UnityGLTF) - - ShaderGraphs/glTF-pbrSpecularGlossiness (legacy shader from glTFast) - - glTF/PbrSpecularGlossiness (legacy shader from glTFast) +Transmission and Volume allow rendering materials like glass, that are fully transparent but still show reflections, as well as volume attenuation (e.g. colored jelly) and rough refraction (e.g. brushed glass). +To use these material features, you need to do some setup on the material and your render pipeline. + +#### Material Setup +1. On a PBRGraph material, check "Enable Transmission" and optionally "Enable Volume" +2. Change the Transmission, Thickness, Index of Refraction and Attenuation values as desired. + +#### URP +To see transmissive and volume materials correctly in Unity, +1. Select your URP Renderer Asset +2. Under the "Renderer Features" section, add a "Opaque Texture (Rough Refraction)" feature + +#### Built-In +To see transmissive and volume materials correctly in Unity, +1. Add the "RoughRefraction" component to your Main Camera. + +#### HDRP +HDRP has its own rough refraction support. There's currently no automatic import / export support to convert to that. Use glTFast if you need this. + +> **Note**: Fully metallic materials are never transparent. See [the KHR_materials_transmission spec](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_transmission/README.md#transparent-metals) for more info. ## Exporting glTF Files -To quickly export an object from a scene or your project, +To export an object from a scene or your project, 1. Select the object 2. Use the menu items under `Assets > UnityGLTF > Export selected as GLB` / `Export selected as glTF` to export -> **Tip:** You can set shortcuts for quick export in Unity's Shortcut Manager. -Ctrl + Space for GLB export and Ctrl + Shift + Space for glTF export allow for super quick iteration. +> **Tip:** You can set shortcuts for quick export in Unity's Shortcut Manager. For example, +Ctrl + Space for GLB export and Ctrl + Shift + Space for glTF export allow for very fast iteration. ### Testing, debugging, compatibility @@ -238,8 +225,8 @@ Notable features with limited support: - setting `textureRotation`. Many viewers simply ignore it. - sparse accessors. Some viewers support sparse accessors only for blend shapes, others don't support it at all. - vertex colors. -- -To test your files, here's a number of other viewers you can use: + +To view your glTF files, here's a number of tools you can use: | Name | Notes | |------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| @@ -250,7 +237,7 @@ To test your files, here's a number of other viewers you can use: | UnityGLTF
(this project!) | Simply drop the exported glb file back into Unity. | | [glTFast](https://github.com/atteneder/glTFast) | Add the glTFast package to your project.
You can switch the used importer on glTF files between glTFast and UnityGLTF. | -To further process files after exporting them with UnityGLTF, you can use +To further process files after exporting them with UnityGLTF, you can use: | Name | Notes | |----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| @@ -258,7 +245,8 @@ To further process files after exporting them with UnityGLTF, you can use ## Animation Export -Animations can be exported both in the Editor and at runtime. +Animations can be exported both in the Editor and at runtime. +Editor export works with Animator (multiple clips), Animation (multiple clips), and Timeline (GLTFRecorderTrack). ### Animator Controller @@ -271,14 +259,16 @@ Both Humanoid and Generic animations will be exported. Humanoid animations are b > **Note**: Animator export only works in the Editor. For runtime export, use the GLTFRecorder capabilities or the Timeline Recorder. -### GLTFRecorder +### GLTFRecorder API -For creating and/or recording animations at runtime, you can use the GLTFRecorder. It allows to *capture* the state of entire hierarchies and complex animations and export them directly as glTF file, with or without KHR_animation_pointer support. -An example is given as GLTFRecorderComponent. +For creating and/or recording animations at runtime, you can use the GLTFRecorder API. It allows to capture the state of entire hierarchies and complex animations and export them directly as glTF file, +optionally with KHR_animation_pointer support for complex material and property animations. +See `GLTFRecorderComponent` for an example implementation. ### Timeline Recorder -Timelines or sections of them can be recorded with a GltfRecorderTrack and one or more GltfRecorderClips. +Timelines or sections of them can be recorded with a `GltfRecorderTrack` and one or more `GltfRecorderClips`. +Timeline recording uses the GLTFRecorder API under the hood. ### Legacy Animation Component @@ -286,55 +276,60 @@ Timelines or sections of them can be recorded with a GltfRecorderTrack and one o Animation components and their legacy clips can also be exported. -### KHR_animation_pointer +### KHR_animation_pointer support -UnityGLTF supports exporting animations with the KHR_animation_pointer extension. The core glTF spec only allows animation node transforms and blendshape weights, while this extension allows animating arbitrary properties in the glTF file – including material properties, and even in custom extensions. +UnityGLTF supports exporting animations with the KHR_animation_pointer extension. +The core glTF spec only allows animation node transforms and blend shape weights, while this extension allows animating arbitrary properties in the glTF file – +including material and object properties, even in custom extensions and script components. -Exporting with KHR_animation_pointer can be turned on in `Project Settings > UnityGLTF > Use Animation Pointer`. +Exporting with KHR_animation_pointer can be turned on in `Project Settings > UnityGLTF` by enabling the KHR_animation_pointer plugin. > **Note:** The exported files can be viewed with Gestaltor, Babylon Sandbox, and Needle Engine, but currently not with three.js / model-viewer. See https://github.com/mrdoob/three.js/pull/24108. They can also not be reimported into UnityGLTF at this point. -## Blendshape Export - -Morph Targets / Blend Shapes are supported, including animations. -To create smaller files for complex blendshape animations (e.g. faces with dozens of shapes), you can export with "Sparse Accessors" on. +## Blend Shape Export -> **Note**: While exporting with sparse accessors works, importing blend shapes with sparse accessors is currently not supported. +Morph Targets / Blend Shapes / Shape Keys are supported, including animations. +To create smaller files for complex blend shape animations (e.g. faces with dozens of shapes), export with the "Sparse Accessors" setting enabled. ## Importing glTF files ### Editor Import -For importing `.gltf` or `.glb` files in the editor, place them in your Asset Database as usual. Make sure to bring bin/textures along for `.gltf`; `.glb` is usually self-contained. +For importing `.gltf` or `.glb` files in the editor, place them in your project as usual (Assets or Packages). +Make sure to bring .bin/textures along for `.gltf` files with the correct relative paths;`.glb` is usually self-contained. -When moving `.gltf` files inside Unity, make sure to move their bin/texture files as well, to not break the path references between them. +When moving `.gltf` files inside Unity, make sure to move their .bin/texture files as well, to not break the path references between them. ### Default Importer Selection -UnityGLTF uses Unity's `ScriptedImporter` interface. For any given file format (file extension) there has to be one default importer and there can be additional, alternative importers. - -UnityGLTF will register itself as the default importer for the .gltf and .glb extensions. +UnityGLTF will register itself as the default importer for the `.gltf` and .`glb` extensions. If the [glTFast package](https://github.com/atteneder/glTFast) is also present in a project, **glTFast gets precedence** and UnityGLTF is available as Importer Override, which can be selected from a dropdown on each glTF asset. -You can make UnityGLTF the default importer and de-prioritize glTFast by adding the following settings to your project's scripting defines: +UnityGLTF uses Unity's `ScriptedImporter` system. For any given file format (file extension) there has to be one default importer and there can be additional, alternative importers. +You can make UnityGLTF the default importer and de-prioritize glTFast by adding the following settings to your project's `Scripting Defines`: ``` GLTFAST_FORCE_DEFAULT_IMPORTER_OFF UNITYGLTF_FORCE_DEFAULT_IMPORTER_ON ``` -Care has been taken to align glTFast's and UnityGLTF's importers, so that in most cases you can switch between them without breaking prefab references. That being said, switching between importers can change material references, mesh references etc., so some manual adjustments may be needed after switching. +Care has been taken to align glTFast's and UnityGLTF's importers, so that in most cases you can switch between them without breaking prefab references. That being said, switching between importers can change material references, mesh references etc., so some manual adjustments may be needed. +You may have to adjust the root stripping settings of each importer (glTFast and UnityGLTF do that slightly differently). ## Animation Import Animations can be imported both in the Editor and at runtime. -On the importer, you can choose between "Legacy" or "Mecanim" clips. +On the importer, you can choose between "Legacy", "Mecanim" or "Humanoid" clips. -At runtime, if you're importing "Mecanim" clips, you need to make sure to add them to a playable graph (e.g. Animator Controller or Timeline) to play them back. +At runtime, if you're importing "Mecanim" clips, you need to make sure to add them to a playable graph via script (e.g. Animator Controller or Timeline) to play them back. ## Extensibility -There's lots of attachment points for exporting and importing glTF files with UnityGLTF. These allow modifying node structures, extension data, materials and more as part of the regular export and import process both in the Editor and at runtime. +UnityGLTF has import and export plugins. These have callbacks for modifying node structures, extension data, materials and more as part of the regular export and import process. They are used both in the Editor and at runtime. +You can make your own plugins and enable them in the `Project Settings > UnityGLTF` menu. + +Creating a plugin is simple: +1. inherit from GltfImportPlugin or GltfExportPlugin > 🏗️ Under construction. You can take a look at `MaterialExtensions.cs` for an example in the meantime.