unity-technologies/com.unity.cloud.gltfast

Efficient glTF 3D import / export library for Unity

Unity glTFast

Unity 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

Unity 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

Installation instructions

NOTE: This package originally had the identifier com.atteneder.gltfast. Consult the upgrade guide to learn how to switch to the Unity version (com.unity.cloud.gltfast) or install the original package.

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.

com.unity.cloud.gltfast's Issues

Add to "extras" during GLB export.

It is currently not possible to add to extras when performing a GLB export as far as I can tell.

I would like for the extras field to be added to GLTFast.Schema.Node (and other relevant areas), and not just to GLTFast.Newtonsoft.Schema.Node.

Alternatively being easily able to extend the GameObjectExporter and/or GLTFWriter to enable custom manipulation of the Json Serialization step of GLB Export would be fine.

Im currently having to modify the source code in my project to allow for this, as I require GLB export. Because this repo isnt up to date with version 6.6 (the version I get when adding the package "com.unity.cloud.gltfast" via package manager, I cant even just fork this repo to get things to work I have to copy files from the PackageCache, and make modifications to it locally.

If I've missed something then it would be great if the documentation could explain more clearly how to achieve adding extras to GLB files.

Add support for skinning export

Currently, when you export with an object that is a SkinnedMeshRenderer, all information is lost.
There was a merge request on the original repo regarding this feature : https://github.com/atteneder/glTFast/pull/512/files

Is it possible to consider this feature again?

Draco Package not found in Unity Editor

When trying to export a scene in Unity Editor using the Draco compression option, I am getting the following errors:

PackageMissing:KHR_draco_mesh_compression
PackageMissing:DracoUnity

I have installed the DracoUnity package using the .unitypackage mentioned here.

• glTFast version: 6.1.0
• Unity Draco version: 4.1.0
• Unity Editor version: 2022.3.12.f1
• Pipeline: BiRP
• Platform: Windows Editor.

Inconsistency between editor imported animations and runtime imported animations

Describe the bug
A clear and concise description of what the bug is.

Gltf animation imported in Editor, loaded via Addressables and animated with Playable Graph Api will loop when reaching the end of an animation clip.

Gltf animation imported in runtime, loaded via Gltfast api (Animation method set to Mecanim) and animated with Playable Graph Api will stuck at the end of the clip (last frame).

Apparently, runtime imported animations do not have Loop Time enabled. I wasn't able to find a way to specify whether to enable it.

Files

Attach or link to .gltf/.glb files that trigger the bug.

The model contains 2 animations: anim1 and anim2. Exported from blender.

test.zip

In addition, make sure to run those files through the glTF Validator first. If you encounter errors or warnings, try to make sure they are not responsible for the issue and file a bug report with the software that generated the glTF file as well.

Note: You have to ZIP archive them first in order for GitHub to accept the upload.

If your files are confidential:

• Try to create a similar, but intellectual-property-free glTF that reproduces the bug in the same way (so any community member can have a look)
• Otherwise, still create this issue and send the files (or a link to them) discretely via email

To Reproduce
Steps to reproduce the behavior:

Just load it up with the api in runtime and the animation clips does not have Loop Time enabled. Drag it directly into the project view would result it having animations with Loop Time enabled.

Expected behavior
A clear and concise description of what you expected to happen.

Same behavior between editor imported animation and runtime imported animations. Or at least a way to specify should the Loop Time be enabled.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• glTFast version 6.2.0
• Unity Editor version 6000.0.0f1
• Render Pipeline and version URP 17.0.3
• Platform: Editor

additionally (if significant for the bug):

Additional context
Add any other context about the problem here.

Now think about it this might be more like a feature request.

Improve Support for Custom Extensions in Edit Mode

Is your feature request related to a problem? Please describe.

Currently it's quite difficult to add support for custom glTF extensions in Edit Mode because GltfImporter cannot be customized.

glTFast uses JSON deserialization for extensions. The C# "schema class" must inherit from GLTFast.Schema.RootBase.

GltfImport (which defines the Root schema type) is small enough and easy to replace. But GltfImporter (the Edit Mode ScriptedImporter), is hard-coded to use GltfImport and this cannot be changed. GltfImporter is extensive and not easy to replace. Therefore, it's quite difficult to add support for custom extensions in Edit Mode.

Describe the solution you'd like

I would like any option for allowing the type of GltfImportBase<TRoot> created by GltfImporter to be customized. Some options might include:

1. Allowing a custom factory method to be specified in EditorImportSettings or ImportSettings.
2. Adding a method to the ImportAddon base class that would allow a custom GltfImportBase<TRoot> object to be created.
3. Adding a settable factory Func<GltfImportBase<TRoot>> property directly on GltfImporter itself.

Any other options would great.

Describe alternatives you've considered

Rewriting my own GltfImporter and making it the default ScriptedImporter. This would be a lot of code and would likely get out of sync with the package implementation.

Additional context

Although the package actually includes a version of GltfImport that uses Newtonsoft, the Newtonsoft version cannot be used for Edit Mode import because of the same reasons listed above. This makes the Newtsonsoft GltfImport class only useful for runtime loading and not editor importing.

LFS Quota Issue Cloning Project (within unity and manually)

Describe the bug

When cloning, I see:

> git clone https://github.com/Unity-Technologies/com.unity.cloud.gltfast.git
Cloning into 'com.unity.cloud.gltfast'...
remote: Enumerating objects: 12555, done.
remote: Counting objects: 100% (4454/4454), done.
remote: Compressing objects: 100% (493/493), done.
remote: Total 12555 (delta 4085), reused 4017 (delta 3961), pack-reused 8101
Receiving objects: 100% (12555/12555), 3.44 MiB | 15.03 MiB/s, done.
Resolving deltas: 100% (10216/10216), done.
Downloading Documentation~/Images/Unity-glTF-workflows.png (59 KB)
Error downloading object: Documentation~/Images/Unity-glTF-workflows.png (aa50e39): Smudge error: Error downloading Documentation~/Images/Unity-glTF-workflows.png (aa50e3980f8e9a99e53b8347cdde7e293fe37ffb5e1469640379d802ef304541): batch response: This repository is over its data quota. Account responsible for LFS bandwidth should purchase more data packs to restore access.

Errors logged to '[...]\com.unity.cloud.gltfast\.git\lfs\logs\20240202T140416.0968063.log'.
Use `git lfs logs last` to view the log.
error: external filter 'git-lfs filter-process' failed
fatal: Documentation~/Images/Unity-glTF-workflows.png: smudge filter lfs failed
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'

Files
none

To Reproduce
Steps to reproduce the behavior:

1. Go to attempt to clone the project on LFS-enabled git version 2.37.2.windows.2
2. See error

Expected behavior
Project should clone without error.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• glTFast version - repository
• Unity Editor version [e.g. 2021.2.1f1] - N/A
• Render Pipeline and version [e.g. Universal Render Pipeline 12.0] - N/A
• Platform: [e.g. Editor, Windows Player, iOS] - N/A

Additional context
none

[Request] Rename parent shader folder

Is your feature request related to a problem? Please describe.
I had a hard time finding the gltf shaders in the dropdown on materials. This was because the gltfast shaders are not under GLTF or GLTFast, but under shader graphs.

Describe the solution you'd like
In Shader Graph you can rename this parent folder. If needed I can make a PR for this and rename it to glTF, like the BiRP shaders.

Test

Describe the bug
A clear and concise description of what the bug is.

Files

Attach or link to .gltf/.glb files that trigger the bug.

In addition, make sure to run those files through the glTF Validator first. If you encounter errors or warnings, try to make sure they are not responsible for the issue and file a bug report with the software that generated the glTF file as well.

Note: You have to ZIP archive them first in order for GitHub to accept the upload.

If your files are confidential:

• Try to create a similar, but intellectual-property-free glTF that reproduces the bug in the same way (so any community member can have a look)
• Otherwise, still create this issue and send the files (or a link to them) discretely via email

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• glTFast version
• Unity Editor version [e.g. 2021.2.1f1]
• Render Pipeline and version [e.g. Universal Render Pipeline 12.0]
• Platform: [e.g. Editor, Windows Player, iOS]

additionally (if significant for the bug):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• For WebGL: Browser [e.g. stock browser, safari]

Additional context
Add any other context about the problem here.