Class AssetLoader

Provides static methods for loading 3D models and related assets into Unity. This class includes functionality for reading various file types or streams, creating mesh and material data, setting up animations, configuring LODs, and more.

Inheritance

object

AssetLoader

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: TriLibCore

Assembly: Assembly-CSharp.dll

Syntax

public static class AssetLoader

Methods

CreateDefaultLoaderOptions(bool, bool)

Creates an AssetLoaderOptions instance with TriLib's default settings and registers mappers such as ByBonesRootBoneMapper and all valid MaterialMapper instances.

If generateAssets is true (in the Unity Editor), the scriptable objects will be created as assets; otherwise, they will be created in memory only.

Declaration

public static AssetLoaderOptions CreateDefaultLoaderOptions(bool generateAssets = false, bool supressWarning = false)

Parameters

Type	Name	Description
bool	generateAssets	If true, newly created ScriptableObject instances will be saved as assets.
bool	supressWarning	If true, suppresses the warning about creating a new AssetLoaderOptions instance. Pass true if you are caching the instance to avoid repeated warnings.

Returns

Type	Description
AssetLoaderOptions	A new AssetLoaderOptions object initialized with default TriLib settings and the available mappers.

GetCompatibleMaterialMapperName()

Determines and returns the name of a compatible MaterialMapper implementation based on the currently active render pipeline (HDRP, URP, or built-in/Standard).

Declaration

public static string GetCompatibleMaterialMapperName()

Returns

Type	Description
string	The name of the MaterialMapper best suited for the active render pipeline. If HDRP is active, returns HDRPMaterialMapper. If URP is active, returns UniversalRPMaterialMapper. Otherwise, returns StandardMaterialMapper.

GetSelectedMaterialMapper(bool)

Retrieves the project-wide selected MaterialMapper based on TriLib settings. If a matching mapper is found and instantiate is true, this method will create a new instance of that mapper.

Declaration

public static MaterialMapper GetSelectedMaterialMapper(bool instantiate)

Parameters

Type	Name	Description
bool	instantiate	If true, creates a new instance of the selected MaterialMapper. If false, returns the prefab/reference directly.

Returns

Type	Description
MaterialMapper	The selected MaterialMapper, or null if no mapper is selected in the TriLib settings.

LoadFastestSettings(ref AssetLoaderOptions)

Configures the specified AssetLoaderOptions for optimal loading performance. This method attempts to load the Autodesk Interactive and glTF2 material helpers (if they exist), sets default references (e.g., blend shape mapper), and tweaks various settings for faster loading.

Declaration

public static void LoadFastestSettings(ref AssetLoaderOptions assetLoaderOptions)

Parameters

Type	Name	Description
AssetLoaderOptions	assetLoaderOptions	A reference to the AssetLoaderOptions instance to configure with the fastest possible settings.

LoadModelFromFile(string, Action<AssetLoaderContext>, Action<AssetLoaderContext>, Action<AssetLoaderContext, float>, Action<IContextualizedError>, GameObject, AssetLoaderOptions, object, bool, Action<AssetLoaderContext>, bool)

Loads a model from the specified path asynchronously, returning an AssetLoaderContext that contains information about the loading process and the resulting UnityEngine.GameObject hierarchy.

This method creates or uses an existing AssetLoaderOptions if none is provided. It attempts to load the model in a background thread where possible (depending on platform/thread settings), and calls back on the Unity main thread (unless otherwise noted).

Declaration

public static AssetLoaderContext LoadModelFromFile(string path, Action<AssetLoaderContext> onLoad = null, Action<AssetLoaderContext> onMaterialsLoad = null, Action<AssetLoaderContext, float> onProgress = null, Action<IContextualizedError> onError = null, GameObject wrapperGameObject = null, AssetLoaderOptions assetLoaderOptions = null, object customContextData = null, bool haltTask = false, Action<AssetLoaderContext> onPreLoad = null, bool isZipFile = false)

Parameters

Type	Name	Description
string	path	The absolute or relative file path to the model.
Action<AssetLoaderContext>	onLoad	Callback invoked on the main thread once the model is loaded (but materials may still be pending). Use this to perform any setup/initialization right after the base model data is available.
Action<AssetLoaderContext>	onMaterialsLoad	Callback invoked on the main thread after the model’s materials (textures, shaders, etc.) have finished loading. This is the final stage of the loading process.
Action<AssetLoaderContext, float>	onProgress	Callback invoked (potentially on a background thread) whenever the loading progress changes. The float parameter represents a value from 0 to 1 indicating progress completion.
Action<IContextualizedError>	onError	Callback invoked on the main thread if an error occurs at any point during the loading process.
GameObject	wrapperGameObject	An optional parent UnityEngine.GameObject under which the newly loaded model UnityEngine.GameObject will be placed. If null, the model will be loaded at the root level.
AssetLoaderOptions	assetLoaderOptions	The AssetLoaderOptions controlling how the model is loaded. If null, this method will create and use a default set of loading options.
object	customContextData	Any custom data you want to pass along to the AssetLoaderContext for use within the loading pipeline.
bool	haltTask	If true, loading tasks are created but not started immediately. This can be used to queue or chain multiple tasks.
Action<AssetLoaderContext>	onPreLoad	Callback invoked on a background thread before Unity objects are created. Use this for any setup tasks that need to run ahead of object instantiation.
bool	isZipFile	Indicates whether the specified path points to a Zip file containing model data.

Returns

Type	Description
AssetLoaderContext	The AssetLoaderContext that tracks all loading information, including references to the loaded UnityEngine.GameObject hierarchy and any associated data or errors.

LoadModelFromFileNoThread(string, Action<IContextualizedError>, GameObject, AssetLoaderOptions, object, bool)

Loads a model from the specified path synchronously on the main thread, returning an AssetLoaderContext with the resulting UnityEngine.GameObject hierarchy.

This method does not utilize background threads, which may be required on certain platforms or situations where multithreading is unsupported or disabled.

Declaration

public static AssetLoaderContext LoadModelFromFileNoThread(string path, Action<IContextualizedError> onError = null, GameObject wrapperGameObject = null, AssetLoaderOptions assetLoaderOptions = null, object customContextData = null, bool isZipFile = false)

Parameters

Type	Name	Description
string	path	The absolute or relative file path to the model.
Action<IContextualizedError>	onError	Callback invoked on the main thread if an error occurs at any point during loading.
GameObject	wrapperGameObject	An optional parent UnityEngine.GameObject under which the newly loaded model UnityEngine.GameObject will be placed. If null, the model will be loaded at the root level.
AssetLoaderOptions	assetLoaderOptions	The AssetLoaderOptions controlling how the model is loaded. If null, this method will create and use a default set of loading options.
object	customContextData	Any custom data you want to pass along to the AssetLoaderContext for use within the loading pipeline.
bool	isZipFile	Indicates whether the specified path points to a Zip file containing model data.

Returns

Type	Description
AssetLoaderContext	The AssetLoaderContext containing information about the load, including references to the loaded UnityEngine.GameObject hierarchy and any encountered errors.

LoadModelFromStream(Stream, string, string, Action<AssetLoaderContext>, Action<AssetLoaderContext>, Action<AssetLoaderContext, float>, Action<IContextualizedError>, GameObject, AssetLoaderOptions, object, bool, Action<AssetLoaderContext>, bool)

Loads a model from the given stream asynchronously, returning an AssetLoaderContext with the resulting UnityEngine.GameObject hierarchy.

Use this overload when the model data is not located in a file but is provided via a Stream. For instance, loading from memory or from a custom data source.

Declaration

public static AssetLoaderContext LoadModelFromStream(Stream stream, string filename = null, string fileExtension = null, Action<AssetLoaderContext> onLoad = null, Action<AssetLoaderContext> onMaterialsLoad = null, Action<AssetLoaderContext, float> onProgress = null, Action<IContextualizedError> onError = null, GameObject wrapperGameObject = null, AssetLoaderOptions assetLoaderOptions = null, object customContextData = null, bool haltTask = false, Action<AssetLoaderContext> onPreLoad = null, bool isZipFile = false)

Parameters

Type	Name	Description
Stream	stream	A Stream containing the model data to load.
string	filename	The model’s filename (if known). This is primarily used to determine the base directory or metadata.
string	fileExtension	The file extension (e.g., "fbx"). If null, this will be automatically determined using GetFileExtension(string, bool) based on filename.
Action<AssetLoaderContext>	onLoad	Callback invoked on the main thread once the model is loaded (but materials may still be pending).
Action<AssetLoaderContext>	onMaterialsLoad	Callback invoked on the main thread after the model’s materials have finished loading.
Action<AssetLoaderContext, float>	onProgress	Callback invoked (potentially on a background thread) whenever the loading progress changes. The float parameter represents a value from 0 to 1 indicating progress.
Action<IContextualizedError>	onError	Callback invoked on the main thread if an error occurs at any point during the loading process.
GameObject	wrapperGameObject	An optional parent UnityEngine.GameObject under which the newly loaded model UnityEngine.GameObject will be placed. If null, the model will be loaded at the root level.
AssetLoaderOptions	assetLoaderOptions	The AssetLoaderOptions controlling how the model is loaded. If null, this method will create and use a default set of loading options.
object	customContextData	Any custom data you want to pass along to the AssetLoaderContext for use within the loading pipeline.
bool	haltTask	If true, loading tasks are created but not started immediately. This can be used to queue or chain multiple tasks.
Action<AssetLoaderContext>	onPreLoad	Callback invoked on a background thread before Unity objects are created. Useful for any pre-instantiation preparation.
bool	isZipFile	Indicates whether the provided stream refers to a Zip file containing model data.

Returns

Type	Description
AssetLoaderContext	The AssetLoaderContext tracking all relevant loading data, including the resulting UnityEngine.GameObject hierarchy and any progress or errors.

LoadModelFromStreamNoThread(Stream, string, string, Action<IContextualizedError>, GameObject, AssetLoaderOptions, object, bool)

Loads a model from the given stream synchronously on the main thread, returning an AssetLoaderContext with the resulting UnityEngine.GameObject hierarchy.

This method does not utilize background threads, suitable for environments or platforms where asynchronous/parallel loading is not available or desired.

Declaration

public static AssetLoaderContext LoadModelFromStreamNoThread(Stream stream, string filename = null, string fileExtension = null, Action<IContextualizedError> onError = null, GameObject wrapperGameObject = null, AssetLoaderOptions assetLoaderOptions = null, object customContextData = null, bool isZipFile = false)

Parameters

Type	Name	Description
Stream	stream	A Stream containing the model data to load.
string	filename	The model’s filename (if known). Used to determine the base directory or any other relevant metadata.
string	fileExtension	The file extension (e.g., "fbx"). If null, this will be automatically determined using GetFileExtension(string, bool) based on filename.
Action<IContextualizedError>	onError	Callback invoked on the main thread if an error occurs at any point during loading.
GameObject	wrapperGameObject	An optional parent UnityEngine.GameObject under which the newly loaded model UnityEngine.GameObject will be placed. If null, the model will be loaded at the root level.
AssetLoaderOptions	assetLoaderOptions	The AssetLoaderOptions controlling how the model is loaded. If null, a default configuration will be created and used.
object	customContextData	Any custom data you want to pass along to the AssetLoaderContext for use within the loading pipeline.
bool	isZipFile	Indicates whether the provided stream refers to a Zip file containing model data.

Returns

Type	Description
AssetLoaderContext	The AssetLoaderContext containing information about the load, including references to the loaded UnityEngine.GameObject hierarchy and any encountered errors.

LoadOrCreateScriptableObjectSafe(string, string, string, bool)

Attempts to load a UnityEngine.ScriptableObject from the specified directory. If not found, creates a new instance using typeName and typeNamespace.

Declaration

public static ScriptableObject LoadOrCreateScriptableObjectSafe(string typeName, string typeNamespace, string directory, bool instantiate)

Parameters

Type	Name	Description
string	typeName	The class name of the UnityEngine.ScriptableObject to load or create.
string	typeNamespace	The namespace in which typeName resides.
string	directory	The Resources directory path where the UnityEngine.ScriptableObject might be located. For example, if you have a Resource at "Assets/Resources/Mappers/Material/CustomMaterialMapper.asset", then directory could be "Mappers/Material".
bool	instantiate	If true, returns a cloned instance (via UnityEngine.Object.Instantiate(UnityEngine.Object, UnityEngine.Vector3, UnityEngine.Quaternion)). If false, returns the original UnityEngine.ScriptableObject reference.

Returns

Type	Description
ScriptableObject	A reference to the loaded or newly created UnityEngine.ScriptableObject, or null if the specified type or resource could not be found.