Mappers are special classes TriLib uses to map and process many loading features that otherwise would need to be made manually model by model, which is inviable due to the nature of the runtime importing process.
Mappers should be assigned to an Asset Loader Options instance that can be created via code or manually on Unity Editor by right-clicking with mouse on the Assets Explorer and selecting an item in TriLib/Asset Loader Options menu.
All mappers are optional when the option in Asset Loader Options are not changed.
Mappers can be created and configured by code or on Unity Editor as well by right-clicking with the mouse on Assets Explorer and selecting an item under TriLib/Mappers menu.
There are several types of mappers:
Texture Mappers are used for reading texture byte data from custom data sources.
TriLib will pass the global context used to load the texture, among the information that the texture reader parsed from the original texture, like its Filename. The return of the mapping method requires a TextureLoadingContext class with fields Stream (Containing the Stream to read the RGBA final texture data), AssetLoaderContext (Containing the same context passed to the mapping method), and Texture (Containing the same texture passed to the mapping method as well).
External Data Mappers
External Data Mappers are used to read binary/ASCII data used by some file formats. (For instance, OBJ files may use this mapper to load data from MTL files, or GLTF files may use this mapper to load data from binary files)
TriLib will pass the global context used to load the external data, among the original external data Filename found on the model file to the mapping method. The return of the mapping method requires a Stream used to read the external data file and also requires a FinalPath value to be set containing the short name of the external data file.
Material Mappers are used for converting original model Materials into Unity Materials.
The instances of this mapper should inform if they are compatible with the original Material TriLib is trying to load and fill a VirtualMaterial data with the original Material properties that can be mapped into Unity Material properties.
Root Bone Mappers
Root Bone Mappers are used to find a model root bone inside its hierarchy when the model contains skinning. TriLib will pass the global loading context to the mapping method, and it should return the most suitable root bone on the RootGameObject hierarchy, in case it has been found. Otherwise, it should return null.
Humanoid Avatar Mappers
Humanoid Avatar Mappers are used to create Avatars from the loaded GameObject hierarchy. TriLib will pass the global loading context to the mapping method, and it should return a Dictionary mapping BoneMapping classes with final Transforms. A BoneMapping should have its HumanBone field set-up, which is the field used by the mapping mechanism.
Animation Clip Mappers
Animation Clip Mappers are used to convert processed model Animation Clips into new Animation Clips (Like for instance, the LegacyToHumanoidAnimationClipMapper that converts Legacy to Humanoid Animation Clips) or can be used to do any post-processing on loaded Animation Clips. TriLib will pass the global loading context to the mapping method, among the processed Animation Clips. The mapping method may return the original Animation Clips or the processed ones. If new Animation Clips be returned, the user must release the previous Animation Clips memory by calling Destroy on every instance.
Animator Controller Override Mappers