atteneder/gltfast

Efficient glTF 3D import / export package for Unity

glTFast

NOTE: It's recommended to switch to Unity glTFast, a fork of this package that is developed and supported by Unity. Consult the upgrade guide for details.

glTFast enables use of glTF™ (GL Transmission Format) asset files in Unity®.

It focuses on speed, memory efficiency and a small build footprint while also providing:

• 100% glTF 2.0 specification compliance
• Ease of use
• Robustness and Stability
• Customization and extensibility for advanced users

Features

glTFast supports the full glTF 2.0 specification and many extensions. It works with Universal, High Definition and the Built-In Render Pipelines on all platforms.

See the comprehensive list of supported features and extensions.

Workflows

There are four use-cases for glTF within Unity

• Import
  • Runtime Import/Loading in games/applications
  • Editor Import (i.e. import assets at design-time)
• Export
  • Runtime Export (save and share dynamic, user-generated 3D content)
  • Editor Export (Unity as glTF authoring tool)

Read more about the workflows in the documentation.

Installing

NOTE: Consider switching to Unity glTFast, a fork of this package that is developed and supported by Unity. Consult the upgrade guide for details.

Installation instruction for the original glTFast.

Usage

You can load a glTF asset from an URL or a file path.

Runtime Loading via Component

Add a GltfAsset component to a GameObject.

Runtime Loading via Script

var gltf = gameObject.AddComponent<GLTFast.GltfAsset>();
gltf.url = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/glTF/Duck.gltf";

See Runtime Loading via Script in the documentation for more details and instructions how to customize the loading behavior via script.

Editor Import

Move or copy glTF files into your project's Assets folder, similar to other 3D formats:

Unity glTFast will import them to native Unity prefabs and add them to the asset database.

See Editor Import in the documentation for details.

Editor Export

The main menu has a couple of entries for glTF export under File > Export and glTFs can also be created via script.

Project Setup

Materials and Shader Variants

❗ IMPORTANT ❗

Unity glTFast uses custom shader graphs that you have to include in builds in order to make materials work. If materials are fine in the Unity Editor but not in builds, chances are some shaders (or variants) are missing.

Read the section Materials and Shader Variants in the Documentation for details.

Contribution

See CONTRIBUTING.md.

License

Copyright 2023 Unity Technologies and the Unity glTFast authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use files in this repository except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Trademarks

Unity® is a registered trademark of Unity Technologies.

Khronos® is a registered trademark and glTF™ is a trademark of The Khronos Group Inc.

gltfast's Issues

Performance on ios

The (impressive) speed of this library in the editor gets lost when building for ios. The loading duration increases by 400%. Switching from .glb to .gltf does not affect the duration.

Camera support

Optional camera import support. Default should be to not import cameras (or at least not activate them).

Extension KHR_lights_punctual

support extension KHR_lights_punctual

Optional though. Default should be not to import lights, I guess

Loading of draco file fails

I'm getting a decoding error when trying to load draco compressed files.

Failed: Decoding error.
UnityEngine.Debug:LogError(Object)
GLTFast.PrimitiveDracoCreateContext:CreatePrimitive() (at Library/PackageCache/com.atteneder.gltfast@64f3c1b978d7139af3da6d9c48b02ae06a375d90/Runtime/Scripts/GltFast.cs:159)
GLTFast.<Prepare>d__43:MoveNext() (at Library/PackageCache/com.atteneder.gltfast@64f3c1b978d7139af3da6d9c48b02ae06a375d90/Runtime/Scripts/GltFast.cs:545)
GLTFast.<LoadContent>d__8:MoveNext() (at Library/PackageCache/com.atteneder.gltfast@64f3c1b978d7139af3da6d9c48b02ae06a375d90/Runtime/Scripts/GltfAsset.cs:77)
UnityEngine.SetupCoroutine:InvokeMoveNext(IEnumerator, IntPtr)

I tried running with 2019.2 as well as 2019.3 on windows 10, git as well as lsf are up to date.
Packages appear to also be in order and up to date:

{
  "dependencies": {
    "com.atteneder.draco": "https://gitlab.com/atteneder/DracoUnity.git",
    "com.atteneder.gltfast": "https://github.com/atteneder/glTFast.git",
    "com.unity.ext.nunit": "1.0.0",
    "com.unity.ide.vscode": "1.1.2",
    "com.unity.test-framework": "1.1.1",
    "com.unity.modules.imageconversion": "1.0.0",
    "com.unity.modules.imgui": "1.0.0",
    "com.unity.modules.jsonserialize": "1.0.0",
    "com.unity.modules.unitywebrequest": "1.0.0",
    "com.unity.modules.unitywebrequesttexture": "1.0.0"
  },
  "testables": [
    "com.atteneder.gltfast"
  ],
  "lock": {
    "com.atteneder.draco": {
      "revision": "HEAD",
      "hash": "b04c2d09ff4d4889e68e0cdfe6b3dc47f4a58a29"
    },
    "com.atteneder.gltfast": {
      "revision": "HEAD",
      "hash": "64f3c1b978d7139af3da6d9c48b02ae06a375d90"
    }
  }
}

I created the file using the fbx2gltf converter 0.9.7 using .\FBX2glTF-windows-x64.exe --input .\Y_Bot.fbx --output Y_Bot.glb --binary --draco (also tried without --binary)

I attached the file in question and would be extremly happy for any pointers where to start debugging / fixing the whole thing!

data.zip

Unity backwards compatibility

Test with a reasonably old version of Unity (2017.1 maybe).

MetalicRoughness textures are not applied correctly

atm the Unity Standard shader is used, which uses the channels of the metalic/roughness textures differently. Hence the result is incorrect.

Thread support

Investigate if the loading process can be moved off the main thread and spread accross multiple worker threads.

Support for Universal Render Pipeline (URP)

Currently there's only support for the Built-In render pipeline via DefaultMaterialGenerator. It implements the interface IMaterialGenerator.

To add support for the URP, the corresponding code creating the materials has to go into a new class implementing IMaterialGenerator.

It has to be used in the constructor of GLTFast instead of the default one (ideally dynamically).

        public GLTFast() {
            materialGenerator = new DefaultMaterialGenerator();
        }

multimaterials per mesh not working

Individual materials per primitive seem to not work atm.

Add support for KHR_mesh_quantization

See https://github.com/zeux/glTF/tree/master/extensions/2.0/Khronos/KHR_mesh_quantization
Requires #18 to be implemented first

Draco mesh compression support

Support extension KHR_draco_mesh_compression

Texture transform support

support extension KHR_texture_transform

Specular Glossiness material model

support extension KHR_materials_pbrSpecularGlossiness

Extension MSFT_lod

See MSFT_lod extension

For export, see #345

Unlit material support

support extension KHR_materials_unlit

Advanced texture packing support

extensions
MSFT_packing_normalRoughnessMetallic
MSFT_packing_occlusionRoughnessMetallic

DoubleSided Materials support

Texture Transform

extension KHR_texture_transform
KhronosGroup/glTF-Sample-Models#167

Assets/GLTFast/GLTFast.cs(345,31): error CS1644: Feature `null propagating operator' cannot be used because it is not part of the C# 4.0 language specification

Occurs when I import into fresh Unity 2018.3 project

Support for KTX 2.0 textures with Basis Universal compression

Add support for extensions:

• KHR_image_ktx2
• KHR_texture_basisu

See KhronosGroup/glTF#1612

Loading glb from Application.persistantdatapath in android.

Hi,
I downloaded the glb files in persistantPath in Android and when I try to load from this path I get an error
Unity: Cannot connect to destination host /storage/emulated/0/Android/data/com.xxx.xxxx/files/C772BCFB-B2FD-406E-8B32-05D3D5DEFAD6.glb

Support external buffers in GLBs

At the moment only GLBs that contain all buffers in itself are supported.

Create an Unity Asset Store Package

For easier installation/usage.
Ideally an automated process.

glTF 1.0 backwards compatibility

Problem when loading asset with more than 65k vertices

when i load low poly assets they build just fine.. however if i try to import one with around 300k vertices this is what i get

instead of

BufferView target support

Take BufferView target into account when loading buffers.
See
https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#buffers-and-buffer-views

glTF JSON (non-binary)

Support for regular text based glTFs

Destroying an imported scene does not free up memory

Textures, Materials and Meshes stick in memory, even after being destroyed.
Easy to spot using the Unity Profiler.

Invalid Package Dependency

I am not incredibly well versed in how Unity's fancy new Package Manager works, but when I follow your instructions on attempting to add glTFast to my manifest.json file, it returns the following error.

An error occurred while resolving packages:
  Package com.atteneder.gltfast@https://github.com/atteneder/glTFast.git has invalid dependencies:
    com.atteneder.draco: Package [[email protected]] cannot be found

Support for High Definition Render Pipeline (HDRP)

So I can't load GLTF files?

Do I need to use another library to convert a GLTF file into GLB in order to use :

var loadModel = new GameObject().AddComponent<GLTFast.GlbAsset>();
loadModel.url = gltf;

Unity Package

Make this project a UnityPackage

• Easier usage for developers
• Separation of core and usage/example code

All nodes and meshes are in wrong coordinate space

glTF is right-handed whilst Unity uses a left-handed coordinate system. Initially glTFast simply scaled the root node by -1 in the Z-axis to fix this. Turns out this can have some negative impact on, for example, shader or physics behaviour.

TODO: convert node's transforms and meshes into Unity space

glb import from network share failed

I tried to import a .glb from a network share and got the following error.

HTTP/1.1 502 Bad Gateway \\server\share\file.glb
UnityEngine.Debug:LogErrorFormat(String, Object[])
GLTFast.<LoadRoutine>d__6:MoveNext() (at Assets/GLTFast/GltfAsset.cs:41)
UnityEngine.SetupCoroutine:InvokeMoveNext(IEnumerator, IntPtr)

Just opened the stuff up for the first time and

Support for multiple UV sets

Meshes can have a second UV set (TEXCOORD_1) that materials can use via texCoord.
See https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#meshes

poor performance on editor/android with large glb file

Hi, i was testing this project and i have very bad performance with "large" glb scene (40mb-100mb) (3d models with lot of objects, ~1M verts ), this was designed just for litle objects? what about performance on mobile devices? what are the limits of this library?

Streamable

Make loading glTFs streamable, so the already received part of the content can be parsed while the rest is loading.

• Detect Binary/JSON
• Parse JSON ahead
• Fill individual BufferViews/Accessors instead of single Buffer
• Start buffer to data conversion ahead
  • Vertex/Index/Matrix Buffers
  • Textures

Related:

• #318
• Streamable instantiation: Instantiate right after parsing but before loading is done and have the content (meshes, textures) appear once they are there.
  • Texture streaming
    • Instantiate first and assign textures once they are ready
    • Mipmap streaming: stream in low levels first and improve resolution on the go

Create automated test

Test all files from the official sample repositories
https://github.com/KhronosGroup/glTF-Sample-Models
https://github.com/bghgary/glTF-Asset-Generator

on all platforms.

Missing namespaces

I've just cloned the project and opened inside of Unity 2018.3.0 which is causing missing namespaces. These are:

• TestTools
• NUnit
• TestAttribute
• Unity TestAttribute
• Unity Test

Is this because i'm using a newer version of Unity or are these carried over from the Kronos project and i'm missed something?

Skin support

Support meshes/rigs with skinning applied.

• Joints
• Weights

Load Progress and state reporting

It would be interesting to get a progress (done vs pending percentage) and provide data/interfaces required for progress bars and ETA calculation.

Callbacks for major loading events, like:

• Geometry is ready
• Materials are ready
• Textures are ready
• Animations are ready
• Everything is ready

Edit: Since version 4.0.1 you can retrieve warning/error messages via ICodeLogger injection.

Support missing Vertex Color Formats

Namely:
Vec3 (without alpha channel)
UInt16

Draco compressed files do not load

I receive this error whenever the plugin tries to decode a gltf or glb compressed with draco:

'''
EntryPointNotFoundException: DecodeMeshForUnity
DracoMeshLoader+DracoJob.Execute () (at Library/PackageCache/com.atteneder.draco@b04c2d09ff4d4889e68e0cdfe6b3dc47f4a58a29/Runtime/Scripts/DracoMeshLoader.cs:64)
Unity.Jobs.IJobExtensions+JobStruct`1[T].Execute (T& data, System.IntPtr additionalPtr, System.IntPtr bufferRangePatchData, Unity.Jobs.LowLevel.Unsafe.JobRanges& ranges, System.Int32 jobIndex) (at /Users/builduser/buildslave/unity/build/Runtime/Jobs/Managed/IJob.cs:30)
'''

I've tried files exported from Blender 2.8 as well as this sample file:
https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/CesiumMilkTruck/glTF-Draco

I've also tried Unity 2019.2.3f1 on both Windows 10 and OSX with the same result.

Sampler support

Apply correct texture filtering and wrapping modes provided by glTF samplers

Optimized Shader/Material System

Right now the Unity Standard Shader is utilized which has some downsides:

• costly texture transformations for occlusion/roughness/metalic textures, since the channel usage differs

• missing features (like double sidedness or unlit)

An optimized shader (or a derivate of the Standard Shader) could improve speed/size.

Things to consider:
(Scriptable) Render Pipeline compatibility:
Forward/Deferred, Lightweight, HQ, custom

Optimize against new Unity Mesh API

Unity 2019.3 Mesh API Improvements:
https://docs.google.com/document/d/1I225X6jAxWN0cheDz_3gnhje3hWNMxTZq3FZQs5KqPc/edit#heading=h.vyksohcynwk5

glTFast could probably be optimized a bit by using this new API

feedback thread:
https://forum.unity.com/threads/feedback-wanted-mesh-scripting-api-improvements.684670/

Morph Target / Sparse Accessors support

Follow the progress of the morph branch

• Proper Disposal
• Target names (from extras)
• Sparse accessors
• Works with Draco
• Animation
  • Multi primitives in separate objects

DDS texture support

support extension MSFT_texture_dds

Support embedded base64-encoded data

For images and buffers.