DOCSEARCHbyAlgolia
Submit Docs

glTFast Documentation

repository·openupm·Indexed 23 days ago

https://github.com/atteneder/gltfast

A high-performance Unity library for efficiently importing and exporting glTF 3D files (.gltf and .glb) at runtime or within the Editor. It supports glTF 2.0 specifications, including various Khronos extensions, and provides workflows for both GameObject and Entities (DOTS) systems across URP, HDRP, and Built-in render pipelines.

Tokens
11.6K
Snippets
17
Records
79
Agent score
81%

What's inside glTFast

  1. Understand the glTFast repository structure

    openupm

    glTFast is part of a monorepo. The core package and its associated test assets are located within the Packages directory. If you are navigating the repository manually, use this structure as a guide:

    • Packages/com.unity.cloud.gltfast: The primary glTFast Unity package.
    • Packages/com.unity.cloud.gltfast.tests: Contains test code and assets.
      • Packages/com.unity.cloud.gltfast.tests/Assets~: Contains glTF test assets.
    • Projects/: Contains various test projects used for validation.
    <Root>
├── Packages
│   ├── com.unity.cloud.gltfast
│   └── com.unity.cloud.gltfast.tests
│       └── Assets~
└── Projects
    ├── glTFast-Test
    └── ...

  2. Choose a glTF workflow for your project

    openupm

    glTFast supports four primary workflows depending on whether you are working in the Unity Editor or at runtime in a built application:

    1. Runtime Import/Loading

    Load and instantiate glTF files while the game or application is running. This is ideal for dynamic or third-party assets and supports compression methods like KTX™/Basis Universal, Draco™, and meshoptimizer.

    2. Editor Import (Design-Time)

    Import glTF assets directly into the Unity Editor. This allows artists to use glTF as a standardized interface, reducing friction between DCC tools and Unity. It enables adding Unity-specific behaviors (scripts, animation controllers) to assets.

    3. Runtime Export

    Allows your application to save and share dynamic, user-generated 3D content (e.g., metaverse snapshots or e-commerce product configurations) as glTF files at runtime.

    4. Editor Export (Experimental)

    Use the Unity Editor as an authoring tool to export scenes and GameObjects as glTFs. This is useful for archiving or using Unity as a content source for the wider glTF ecosystem.

  3. Adjust scene origin during export

    openupm
    By default, the glTF root nodes' positions match the original GameObjects' world positions in Unity. If your scene is far from the origin, you can use AddScene to provide an inverse scene origin matrix. This applies the matrix to all root-level nodes, effectively centering the exported content.

  4. How glTF workflows work in glTFast

    openupm

    glTFast supports four primary workflows for handling glTF files within Unity:

    1. Runtime Import/Loading: Loading glTF assets dynamically while the game or application is running.
    2. Editor Import: Importing glTF files at design-time by adding them to the project assets.
    3. Runtime Export: Saving and sharing dynamic, user-generated 3D content during runtime.
    4. Editor Export: Using Unity as a glTF authoring tool by exporting assets from the Editor.

  5. Control vertex attribute discarding

    openupm

    To reduce file size, glTFast automatically discards mesh vertex attributes that are not required by the assigned materials (e.g., vertex colors if the material doesn't use them, or tangents/normals if the material is unlit).

    If you are using the glTF for further editing (authoring workflows) and need to keep these attributes, you can disable discarding on a per-attribute basis by setting the PreservedVertexAttributes mask in ExportSettings.

  6. Manage glTFast test assets

    openupm

    Test assets (such as glTF files) are stored in the hidden directory Packages/com.unity.cloud.gltfast.tests/Assets~.

    • Editor Playmode: Assets are loaded directly from the hidden directory.
    • Player Builds: The GLTFast.Editor.Tests.PreprocessBuild script automatically copies all test assets into a directory named gltfast within your project's StreamingAssets folder to ensure accessibility.
    CAUTION

    If you run tests in a production project, you must manually remove the gltfast folder within StreamingAssets to prevent test assets from being included in your production build.

  7. glTFast Workflow Support Matrix

    openupm

    glTFast supports two primary workflows: GameObject (standard Unity workflow) and Entities (Unity DOTS workflow).

    • GameObject Workflow: Fully supports both Runtime and Editor (design-time) import. Export is currently experimental and missing core features.
    • Entities (DOTS) Workflow: Supports Runtime import. Editor support and Export are currently not available.

  10. Export GameObjects or scenes via script

    openupm

    You can export individual GameObjects or entire scenes to glTF™ files at runtime using the GLTFast.Export namespace.

    Prerequisites: Ensure your Assembly Definition (.asmdef) references both the glTFast and glTFast.Export assemblies.

    Workflow:

    1. Create an instance of GameObjectExport.
    2. Add content using AddScene.
    3. Choose an export method:
      • SaveToFileAndDispose: Exports to one or more files (e.g., .gltf, .bin, and texture files). Note: The GameObjectExport instance becomes invalid after this call and cannot be reused.
      • SaveToStreamAndDispose: Exports to a Stream.

    Warning: Exporting to a Stream currently only works for self-contained glTF-Binary (.glb) files where the binary buffer and textures are included in the single file. Other export settings will cause this to fail.

  11. Upgrade to Unity glTFast (com.unity.cloud.gltfast)

    openupm

    Starting from version 5.2.0, the package was renamed to Unity glTFast (com.unity.cloud.gltfast) to better integrate with Unity's internal processes and allow distribution via the Unity Package Manager without scoped registries.

    To transition:

    1. Remove the original glTFast (com.atteneder.gltfast).
    2. Install Unity glTFast (com.unity.cloud.gltfast).
    3. Update your Assembly Definition references if necessary.
    4. Update any dependencies in your packages-lock.json or manifest if your package depends on it.

    Note on dependencies: If you use KtxUnity or DracoUnity with glTFast, you must also transition to their Unity variants (KTX for Unity and Draco for Unity).