Basic Usage

There are three main methods to load models and their dependencies in TriLib:

Local File-System Loading
URL Loading
Custom Source Loading

The user can adapt other loading mechanisms as the core loading methods accept Streams as data input and Scriptable Objects called Mappers, used to load Textures and external data from custom data Streams.

Local File-System Loading

Using File Picker

Loading models from the local file-system is simplified by using the StandaloneFileBrowser classes that come with TriLib.

Let's create an empty Unity project in this example and import the TriLib Unity package. Make sure you include the StandaloneFileBrowser folder when extracting.

Create a new Script. You can call it "TestLoader.cs" then assign this script to the "Main Camera" on your scene.

Use the following code in your "TestLoader.cs" and hit the play button to test it:

using TriLibCore;
using TriLibCore.General;
using UnityEngine;

public class TestLoader : MonoBehaviour
{
    // Lets the user load a new model by clicking a GUI button.
    private void OnGUI()
    {
        // Displays a button to begin the model loading process.
        if (GUILayout.Button("Load Model from File"))
        {
            // Creates an AssetLoaderOptions instance.
            // AssetLoaderOptions is a class used to configure many aspects of the loading process.
            // We won't change the default settings this time, so we can use the instance as it is.
            var assetLoaderOptions = AssetLoader.CreateDefaultLoaderOptions();

            // Creates the AssetLoaderFilePicker instance.
            // AssetLoaderFilePicker is a class that allows users to select models from the local file system.
            var assetLoaderFilePicker = AssetLoaderFilePicker.Create();

            // Shows the model selection file-picker.
            assetLoaderFilePicker.LoadModelFromFilePickerAsync("Select a File", OnLoad, OnMaterialsLoad, OnProgress, OnBeginLoad, OnError, null, assetLoaderOptions);
        }
    }

    // This event is called when the model is about to be loaded.
    // You can use this event to do some loading preparation, like showing a loading screen in platforms without threading support.
    // This event receives a Boolean indicating if any file has been selected on the file-picker dialog.
    private void OnBeginLoad(bool anyModelSelected)
    {

    }

    // This event is called when the model loading progress changes.
    // You can use this event to update a loading progress-bar, for instance.
    // The "progress" value comes as a normalized float (goes from 0 to 1).
    // Platforms like UWP and WebGL don't call this method at this moment, since they don't use threads.
    private void OnProgress(AssetLoaderContext assetLoaderContext, float progress)
    {

    }

    // This event is called when there is any critical error loading your model.
    // You can use this to show a message to the user.
    private void OnError(IContextualizedError contextualizedError)
    {

    }

    // This event is called when all model GameObjects and Meshes have been loaded.
    // There may still Materials and Textures processing at this stage.
    private void OnLoad(AssetLoaderContext assetLoaderContext)
    {
        // The root loaded GameObject is assigned to the "assetLoaderContext.RootGameObject" field.
        // If you want to make sure the GameObject will be visible only when all Materials and Textures have been loaded, you can disable it at this step.
        var myLoadedGameObject = assetLoaderContext.RootGameObject;
        myLoadedGameObject.SetActive(false);
    }

    // This event is called after OnLoad when all Materials and Textures have been loaded.
    // This event is also called after a critical loading error, so you can clean up any resource you want to.
    private void OnMaterialsLoad(AssetLoaderContext assetLoaderContext)
    {
        // The root loaded GameObject is assigned to the "assetLoaderContext.RootGameObject" field.
        // You can make the GameObject visible again at this step if you prefer to.
        var myLoadedGameObject = assetLoaderContext.RootGameObject;
        myLoadedGameObject.SetActive(true);
    }
}
</pre>

Using the Model Filename

You can also load your Models, passing the Model Filename to the AssetLoader methods.

Let's create an empty Unity project in this example and import the TriLib Unity package.

Create a new Script. You can call it "TestLoader.cs" then assign this script to the "Main Camera" on your scene.

Use the following code in your "TestLoader.cs" and hit the play button to test it:

using TriLibCore;
using TriLibCore.General;
using UnityEngine;

public class TestLoader : MonoBehaviour
{
    // Lets the user load a new model by clicking a GUI button.
    private void OnGUI()
    {
        // Displays a button to begin the model loading process.
        if (GUILayout.Button("Load Model from File"))
        {
            // Creates an AssetLoaderOptions instance.
            // AssetLoaderOptions is a class used to configure many aspects of the loading process.
            // We won't change the default settings this time, so we can use the instance as it is.
            var assetLoaderOptions = AssetLoader.CreateDefaultLoaderOptions();

            // Loads the model from the "PATH_TO_MY_FILE.FBX" path
            AssetLoader.LoadModelFromFile("PATH_TO_MY_FILE.FBX", OnLoad, OnMaterialsLoad, OnProgress, OnError, null, assetLoaderOptions);
        }
    }

    // This event is called when the model is about to be loaded.
    // You can use this event to do some loading preparation, like showing a loading screen in platforms without threading support.
    // This event receives a Boolean indicating if any file has been selected on the file-picker dialog.
    private void OnBeginLoad(bool anyModelSelected)
    {

    }

    // This event is called when the model loading progress changes.
    // You can use this event to update a loading progress-bar, for instance.
    // The "progress" value comes as a normalized float (goes from 0 to 1).
    // Platforms like UWP and WebGL don't call this method at this moment, since they don't use threads.
    private void OnProgress(AssetLoaderContext assetLoaderContext, float progress)
    {

    }

    // This event is called when there is any critical error loading your model.
    // You can use this to show a message to the user.
    private void OnError(IContextualizedError contextualizedError)
    {

    }

    // This event is called when all model GameObjects and Meshes have been loaded.
    // There may still Materials and Textures processing at this stage.
    private void OnLoad(AssetLoaderContext assetLoaderContext)
    {
        // The root loaded GameObject is assigned to the "assetLoaderContext.RootGameObject" field.
        // If you want to make sure the GameObject will be visible only when all Materials and Textures have been loaded, you can disable it at this step.
        var myLoadedGameObject = assetLoaderContext.RootGameObject;
        myLoadedGameObject.SetActive(false);
    }

    // This event is called after OnLoad when all Materials and Textures have been loaded.
    // This event is also called after a critical loading error, so you can clean up any resource you want to.
    private void OnMaterialsLoad(AssetLoaderContext assetLoaderContext)
    {
        // The root loaded GameObject is assigned to the "assetLoaderContext.RootGameObject" field.
        // You can make the GameObject visible again at this step if you prefer to.
        var myLoadedGameObject = assetLoaderContext.RootGameObject;
        myLoadedGameObject.SetActive(true);
    }
}

URL Loading

You can use the AssetDownloader class to load models from URLs (network). The usage is relatively simple and similar to the local file-system loading.

Let's create an empty Unity project in this example and import the TriLib Unity package. Make sure you include the StandaloneFileBrowser folder when extracting.

Create a new Script. You can call it "TestLoader.cs" then assign this script to the "Main Camera" on your scene.

Important: If you're downloading models from files that are not Zipped, you must pass the model extension as the last parameter from the AssetDownloader.LoadModelFromUri call (Eg: "fbx")

Use the following code in your "TestLoader.cs" and hit the play button to test it:

using TriLibCore;
using TriLibCore.General;
using UnityEngine;

public class TestLoader : MonoBehaviour
{
    // Lets the user load a new model by clicking a GUI button.
    private void OnGUI()
    {
        // Displays a button to begin the model loading process.
        if (GUILayout.Button("Load Model from URL"))
        {
            // Creates an AssetLoaderOptions instance.
            // AssetLoaderOptions is a class used to configure many aspects of the loading process.
            // We won't change the default settings this time, so we can use the instance as it is.
            var assetLoaderOptions = AssetLoader.CreateDefaultLoaderOptions();

            // Creates the web-request.
            // The web-request contains information on how to download the model.
            // Let's download a model from the TriLib website.
            var webRequest = AssetDownloader.CreateWebRequest("https://ricardoreis.net/trilib/demos/avatars/003/003_visemes.zip");

            // Important: If you're downloading models from files that are not Zipped, you must pass the model extension as the last parameter from this call (Eg: "fbx")
            // Begins the model downloading.
            AssetDownloader.LoadModelFromUri(webRequest, OnLoad, OnMaterialsLoad, OnProgress, OnError, null, assetLoaderOptions, null, null);
        }
    }

    // This event is called when the model loading progress changes.
    // You can use this event to update a loading progress-bar, for instance.
    // The "progress" value comes as a normalized float (goes from 0 to 1).
    // Platforms like UWP and WebGL don't call this method at this moment, since they don't use threads.
    private void OnProgress(AssetLoaderContext assetLoaderContext, float progress)
    {

    }

    // This event is called when there is any critical error loading your model.
    // You can use this to show a message to the user.
    private void OnError(IContextualizedError contextualizedError)
    {

    }

    // This event is called when all model GameObjects and Meshes have been loaded.
    // There may still Materials and Textures processing at this stage.
    private void OnLoad(AssetLoaderContext assetLoaderContext)
    {
        // The root loaded GameObject is assigned to the "assetLoaderContext.RootGameObject" field.
        // If you want to make sure the GameObject will be visible only when all Materials and Textures have been loaded, you can disable it at this step.
        var myLoadedGameObject = assetLoaderContext.RootGameObject;
        myLoadedGameObject.SetActive(false);
    }

    // This event is called after OnLoad when all Materials and Textures have been loaded.
    // This event is also called after a critical loading error, so you can clean up any resource you want to.
    private void OnMaterialsLoad(AssetLoaderContext assetLoaderContext)
    {
        // The root loaded GameObject is assigned to the "assetLoaderContext.RootGameObject" field.
        // You can make the GameObject visible again at this step if you prefer to.
        var myLoadedGameObject = assetLoaderContext.RootGameObject;
        myLoadedGameObject.SetActive(true);
    }
}

Importing Avatars

Importing an avatar using TriLib requires a few steps.

Configure `AssetLoaderOptions`

The first step is to configure your AssetLoaderOptions:

Set the AssetLoaderOptions.AnimationType field to AnimationType.Humanoid.
Assign a HumanoidAvatarMapper to the AssetLoaderOptions.HumanoidAvatarMapper field.

A HumanoidAvatarMapper is used to map the bones from the source model to Unity’s Animator/Mecanim muscles and bones.

TriLib includes the MixamoAndBipedByName HumanoidAvatarMapper, which supports models rigged using Mixamo, Biped, and DAZ Studio formats.

Using a Custom `HumanoidAvatarMapper`

If you need to support a different bone setup, you can create a ByNameHumanoidAvatarMapper in your project assets by right-clicking in the Project window and selecting:

Create -> TriLib -> Mappers -> Humanoid -> ByNameHumanoidAvatarMapper

You can then configure the bone matching by name in the Unity inspector by modifying your ByNameHumanoidAvatarMapper asset.

To reference your ByNameHumanoidAvatarMapper instance, the easiest option is to create a public variable in the class responsible for loading the avatar and assign the mapper via the Inspector.

Putting It All Together

There are several ways to load models using TriLib (as covered in previous sections), so this section only shows the specific code needed to set up avatar importing. Add this code where you configure your AssetLoaderOptions, then proceed to load your model using the method that suits your needs:

var assetLoaderOptions = AssetLoader.CreateDefaultLoaderOptions(false, true);
assetLoaderOptions.AnimationType = AnimationType.Humanoid;
// You can also assign the HumanoidAvatarMapper through a public field set in the Inspector
assetLoaderOptions.HumanoidAvatarMapper = ScriptableObject.CreateInstance<MixamoAndBipedByNameByNameHumanoidAvatarMapper>();

Assigning an `AnimatorController`

If you need to assign an AnimatorController to the loaded avatar, you can do so after loading, typically inside the OnMaterialsLoad method:

var animator = assetLoaderContext.RootGameObject.GetComponent<Animator>();
// You can expose "MyAnimatorController" as a public field in your loading class
animator.runtimeAnimatorController = MyAnimatorController;

Remarks

TriLib can’t import new humanoid animations due to a limitation in the Unity API. You should include your existing animations when compiling your project in order to use them with avatars imported through TriLib.

Basic Usage

Local File-System Loading

Using File Picker

Using the Model Filename

URL Loading

Importing Avatars

Configure AssetLoaderOptions

Using a Custom HumanoidAvatarMapper

Putting It All Together

Assigning an AnimatorController

Remarks

Configure `AssetLoaderOptions`

Using a Custom `HumanoidAvatarMapper`

Assigning an `AnimatorController`