简介基于TriLib插件的Unity引擎C#源码工程旨在帮助Unity开发者快速实现运行时三维模型动态导入、加载与预览功能适用于游戏内模型替换、关卡场景预览、AR/VR可视化等需要实时更新模型的项目。工程实现了在运行中选择模型并加载展示的完整流程并针对标准渲染管线进行了配置同时提供高清渲染管线与通用渲染管线的导入说明便于不同项目适配。压缩包共收录879个文件体积约26.37MB其中包含核心C#逻辑脚本、TriLib配套动态库、着色器、材质、FBX/OBJ三维模型样例以及场景与项目设置文件目录结构清晰可直接在Unity工程中参考或二次开发。工程基于TriLib 2.3.7版本使用Unity 2021.3.27标准渲染管线源码包含完整的UI交互和模型加载逻辑既能学习运行时导入机制也可作为模型替换功能的基础框架。目前已有270人学习下载对于需要集成同类功能的开发者具备直接借鉴价值。1. 运行时导入模型为什么我不再用 AssetBundle做工业仿真项目时客户提了个需求用户在软件里直接点选本地的一个 3D 模型文件FBX/OBJ/GLTF程序要立刻把它加载进场景、替换掉当前显示的设备模型——全程不经过编辑器也不做二次打包。这个需求直接把 AssetBundle 方案否掉了因为 AB 包必须在编辑器里提前 Build没法处理任意路径下的用户文件。后来我用了 TriLib 这个运行时模型加载插件配合 C# 写了整套加载、替换、内存管理逻辑。这套基于 Unity3D 和 C# 的源码工程解决的正是这类场景运行时模型导入、模型替换、实时更新模型适合做工业预览、仿真演示、模型导入工具的人直接抄作业。2. TriLib 加载流程从文件路径到场景 GameObject 的完整链路2.1 加载前的选型AssetLoaderOptions 决定了导入产物的形态TriLib 的核心入口是AssetLoader静态类但它本身并不智能——模型进来之后是否生成碰撞体、是否自动缩放、材质怎么处理全部由AssetLoaderOptions控制。我一般习惯先创建一份全局复用的配置而不是每次加载都 new 一个新的这样能避免不同加载请求之间参数漂移。using TriLib; using UnityEngine; public class RuntimeModelLoader : MonoBehaviour { // 全局复用的加载配置 private AssetLoaderOptions loaderOptions; private void Awake() { loaderOptions AssetLoaderOptions.CreateInstance(); loaderOptions.AutoGenerateColliders false; // 不自动生成碰撞体由外部按需添加 loaderOptions.MarkAssetsAsLoaded true; // 加载完成后立即标记资产为已加载状态 loaderOptions.Scale Vector3.one; // 加载时全局缩放 loaderOptions.Rotation Quaternion.identity; // 加载时全局旋转 loaderOptions.ImportMeshes true; // 导入网格数据 loaderOptions.ImportMaterials true; // 导入材质数据 loaderOptions.UseFileScale true; // 读取文件内记录的单位缩放 } }这段配置里最关键的两个参数是UseFileScale和AutoGenerateColliders。UseFileScale开启后TriLib 会读取模型文件里携带的单位信息FBX 会写单位OBJ 通常没有避免出现「在 3ds Max 里是 1 米进 Unity 变成 0.01 米」这种尺寸翻车。AutoGenerateColliders默认关掉是因为运行时导入模型通常用于展示碰撞体可以在后续按需用MeshCollider补直接让 TriLib 生成会多出一层 MeshCollider 组件重叠时物理计算开销翻倍。2.2 同步与异步加载代码签名、回调和执行时机加载文件最常见的方式是LoadModelFromFile同步加载和LoadModelFromFileAsync异步加载。严格说 TriLib 的「异步」并不是多线程加载网格数据而是把加载过程拆成多个步骤分发到主线程的帧循环里执行避免一帧卡死。项目中我建议优先用异步尤其是加载面数在几十万级别的模型时同步加载会有肉眼可见的白屏卡顿。public void LoadModel(string filePath) { if (string.IsNullOrEmpty(filePath)) { Debug.LogError(文件路径为空); return; } AssetLoader.LoadModelFromFileAsync( filePath, OnModelLoaded, // 加载完成回调 OnModelProgress, // 进度回调 OnModelError, // 错误回调 loaderOptions, null); // 外部传入的 CancellationToken } private void OnModelLoaded(AssetLoaderContext context) { GameObject loadedObject context.LoadedGameObject; if (loadedObject null) { Debug.LogError(加载完成但返回的 GameObject 为空); return; } // 挂载到当前组件所在节点下保持场景层级干净 loadedObject.transform.SetParent(transform, false); loadedObject.transform.localPosition Vector3.zero; loadedObject.transform.localRotation Quaternion.identity; } private void OnModelProgress(AssetLoaderContext context, float progress) { // progress 取值范围 0f ~ 1f可以接到 UI 进度条上 Debug.Log(加载进度: (progress * 100f).ToString(F1) %); } private void OnModelError(AssetLoaderContext context) { Debug.LogError(模型加载失败: context.Error); }注意SetParent(transform, false)这里的false是worldPositionStays参数意思是保持局部坐标不变。加载出来的模型根节点在场景里默认是世界原点如果不做这一步模型会直接出现在坐标原点而不是你指定的位置。回调时序上OnModelProgress会在加载过程中多次触发不要在里面做重操作只更新 UI 文本即可。2.3 加载产物处理层级结构、Transform 与父节点挂载TriLib 加载回来的loadedObject是一个根节点下面往往挂着多层子物体。FBX 导入后通常是一层空节点下面套网格节点OBJ 则基本都是单层网格。处理时我一般会先清理掉根节点上的多余组件再统一设置 Layer避免加载出来的模型和默认场景物体混在一起。private void SetupLoadedRoot(GameObject root) { // 移除加载时自动附加的 AudioSource 等多余组件 var audio root.GetComponentAudioSource(); if (audio ! null) Destroy(audio); // 设置层级用于碰撞检测和相机渲染裁剪 SetLayerRecursively(root, LayerMask.NameToLayer(ModelLayer)); // 记录模型原始包围盒用于后续自动摆正和缩放 var bounds CalculateBounds(root); Debug.Log(模型尺寸: bounds.size.ToString(F3)); } private void SetLayerRecursively(GameObject go, int layer) { go.layer layer; for (int i 0; i go.transform.childCount; i) { SetLayerRecursively(go.transform.GetChild(i).gameObject, layer); } } private Bounds CalculateBounds(GameObject root) { var renderers root.GetComponentsInChildrenRenderer(); if (renderers.Length 0) return new Bounds(); var bounds renderers[0].bounds; for (int i 1; i renderers.Length; i) { bounds.Encapsulate(renderers[i].bounds); } return bounds; }CalculateBounds这个方法在模型替换场景里很实用——你可以在加载完成后立刻知道模型的实际尺寸然后决定是手动缩放还是弹窗提示用户「模型过大」。我见过很多项目在运行时导入模型后不做任何尺寸检查结果一个 10 米高的设备模型直接撑爆相机近裁剪面画面全黑。3. 封装一个可复用的运行时导入组件参数配置与内存管理3.1 组件设计把加载、替换、卸载收敛到一个类里直接在外层脚本里散落着调用AssetLoader的代码后期会很难维护。我习惯把加载逻辑全部收敛到一个RuntimeModelImporter组件里对外只暴露三个方法LoadFromFile、ReplaceWithFile、UnloadCurrent。这样 UI 层和业务层不需要关心 TriLib 的存在后续如果要换成别的加载方案只需要改这一个类。using System; using TriLib; using UnityEngine; public class RuntimeModelImporter : MonoBehaviour { public event ActionGameObject OnModelLoaded; public event Actionstring OnModelFailed; private AssetLoaderOptions loaderOptions; private GameObject currentModel; [SerializeField] private Transform modelParent; private void Awake() { if (modelParent null) modelParent transform; loaderOptions AssetLoaderOptions.CreateInstance(); loaderOptions.AutoGenerateColliders false; loaderOptions.MarkAssetsAsLoaded true; } public void LoadFromFile(string filePath) { UnloadCurrent(); AssetLoader.LoadModelFromFileAsync( filePath, context { currentModel context.LoadedGameObject; AttachToParent(currentModel); OnModelLoaded?.Invoke(currentModel); }, null, context OnModelFailed?.Invoke(context.Error.ToString()), loaderOptions, null); } public void ReplaceWithFile(string filePath) { LoadFromFile(filePath); // 内部先 Unload 再加载 } public void UnloadCurrent() { if (currentModel ! null) { Destroy(currentModel); currentModel null; Resources.UnloadUnusedAssets(); } } private void AttachToParent(GameObject model) { model.transform.SetParent(modelParent, false); model.transform.localPosition Vector3.zero; model.transform.localRotation Quaternion.identity; } }这里的核心设计是「当前模型只有一个」的假设。ReplaceWithFile并没有单独实现替换逻辑而是调用LoadFromFile因为LoadFromFile内部第一步就是UnloadCurrent。这样的好处是保证任何时刻场景里最多只有一个运行时导入的模型不会出现替换失败、新旧模型同时存在的脏状态。3.2 关键参数逐项说明哪些配置直接影响加载行为TriLib 的AssetLoaderOptions属性非常多但实际高频调整的就那么几个。以下是我在不同项目里总结出的参数表参数默认值建议值说明ScaleVector3.one按需缩放会直接乘到每个顶点上加载后再改 Transform 不会影响网格数据RotationQuaternion.identity按需用于修正模型朝向比如 OBJ 需要绕 X 轴旋转 -90 度AutoGenerateCollidersfalsefalse运行时导入的展示模型碰撞体应延迟到业务需要时再添加ImportMaterialstrue按需如果只需要模型形状如碰撞检测用关掉可以省内存ImportMeshestruetrue关掉的话模型只剩空节点几乎没人这么用UseFileScalefalsetrue读取文件内置单位避免尺寸不符MarkAssetsAsLoadedfalsetrue加载完成后立即释放导入过程中的临时中间数据SplitStaticMeshesfalsefalse把合并的静态网格拆成多个子网格通常不需要ReadEnabledfalsetrue开启后网格数据可读取配合MeshCollider使用必须开启ReadEnabled是一个隐蔽的坑——如果你打算给加载出来的模型挂MeshCollider但加载时没开这个参数碰撞体会显示为「Mesh 不可读写」而无法正常工作。这个参数不在 TriLib 的编辑器界面顶层很容易漏掉。3.3 内存与生命周期卸载时机和残留引用运行时加载模型最容易翻车的就是内存只增不减。TriLib 加载过程中会创建网格、材质、纹理的中间副本如果加载完成后没有正确标记释放这些中间资产会一直挂在内存里。打开MarkAssetsAsLoaded true是第一步第二步是确保卸载时调用了Resources.UnloadUnusedAssets。public void UnloadCurrent() { if (currentModel null) return; // 先销毁场景对象 Destroy(currentModel); currentModel null; // 异步释放未被引用的资源 Resources.UnloadUnusedAssets(); System.GC.Collect(); }这里有一个细节Resources.UnloadUnusedAssets是一个异步操作它只会释放「没有被任何对象引用」的资源。如果你的业务层某个变量还保存着旧模型的网格引用这个模型永远不会被真正卸载。所以我在UnloadCurrent里首先把currentModel置空再从根上切断引用链。System.GC.Collect()不建议主动调用但如果你的项目里有第三方插件持有静态引用这一步能兜底把那些该回收的托管对象收掉。TriLib 文档里对性能敏感场景的建议也是「先从引用上断开再让 Unity 自己在合适时机回收」——强行GC.Collect反而可能引起瞬时卡顿。4. 模型替换实战从换对象到换材质的完整流程4.1 替换策略对比先销毁后加载与增量替换模型替换有两种常见策略。第一种是「先销毁、再加载」即卸载旧模型等新模型加载完成后再挂载。优点是不会出现新旧模型同时在场的状态缺点是加载过程中场景是空的视觉效果上会闪一下。第二种是「新模型加载完成后再销毁旧模型」这样场景里始终有模型但加载新模型期间会出现两个模型重叠。两者没有绝对优劣。public void ReplaceWithFile(string filePath) { if (currentModel ! null) { // 策略一先销毁旧模型 Destroy(currentModel); currentModel null; } AssetLoader.LoadModelFromFileAsync( filePath, context { currentModel context.LoadedGameObject; AttachToParent(currentModel); // 策略二加载成功后销毁旧模型 // if (oldModel ! null) Destroy(oldModel); OnModelLoaded?.Invoke(currentModel); }, null, context OnModelFailed?.Invoke(context.Error.ToString()), loaderOptions, null); }我个人的习惯是采用策略二保留旧模型直到新模型加载完成。尤其在做工业设备替换预览时用户看到的是「新模型压在旧模型上然后旧模型消失」的过渡效果比「场景突然空白再突然弹出模型」的体感好得多。代价是替换期间内存峰值会高一些但现在的设备普遍能扛住几百万面量级的内存开销。4.2 材质与 ShaderURP 与 Standard 管线的材质修正TriLib 加载材质时会根据模型文件里的材质定义创建对应的 Unity Material但它默认使用的 Shader 大概率是 Standard。如果你的项目跑在 URP 或 HDRP 渲染管线里加载出来的模型可能显示粉色或紫色。这不是贴图丢了而是 Shader 不兼容。解决方式是在加载完成后遍历所有 Renderer把材质 Shader 替换成当前管线的对应 Shader。private void FixShaders(GameObject root) { var renderers root.GetComponentsInChildrenRenderer(); foreach (var renderer in renderers) { for (int i 0; i renderer.materials.Length; i) { // 从当前工程里查找 URP Lit Shader Shader urpLit Shader.Find(Universal Render Pipeline/Lit); if (urpLit ! null renderer.materials[i].shader.name ! urpLit.name) { renderer.materials[i].shader urpLit; } } } }这里需要说明一点直接替换 Shader 只能保证渲染不报错无法保证贴图和颜色表现完全还原。TriLib 的材质转换器Material Converter才是处理完整材质还原的方案它会尝试把源模型的 PBR 参数映射到目标 Shader 的属性上。但配置 Material Converter 需要额外几步操作而且不同管线之间属性名差异很大。如果项目对视觉效果要求不高直接换 Shader 是最快的手段如果要求高建议在编辑阶段就调试好 Material Converter 的映射表运行时直接复用。4.3 碰撞体与交互组件运行时导入后如何补物理加载出来的模型默认只有一个纯粹的渲染层级没有碰撞体。如果需要鼠标点击拾取模型或者让模型参与物理碰撞需要在加载完成后按需添加MeshCollider或BoxCollider。这里要注意一个性能取舍。private void AddColliders(GameObject root, bool useSimpleCollider) { if (useSimpleCollider) { // 方案一用包围盒做近似碰撞体 var bounds CalculateBounds(root); var box root.AddComponentBoxCollider(); box.center bounds.center - root.transform.position; box.size bounds.size; } else { // 方案二给每个 MeshRenderer 挂 MeshCollider var meshFilters root.GetComponentsInChildrenMeshFilter(); foreach (var filter in meshFilters) { var collider filter.gameObject.AddComponentMeshCollider(); collider.sharedMesh filter.sharedMesh; } } }方案一适合只需要拾取、不需要精确碰撞的预览场景方案二适合需要模型表面精确交互的场景。但如果模型是几十万面的高模方案二会直接让物理引擎崩溃——物理引擎对高面数 MeshCollider 的处理极其吃力。所以我在这种场景的做法是「加载时保留原始模型用于渲染用 T 级减面模型给 MeshCollider 用」。如果项目里没有减面条件那优先用 BoxCollider 兜底。5. TriLib 常见问题排查五个坑与对应解法5.1 模型加载成功但场景里看不到现象OnModelLoaded回调正常触发currentModel不为空Log 里也没有报错但场景里就是看不到模型。原因最常见的原因是加载出来的 GameObject 被挂到了一个被隐藏的父节点下或者模型加载到了世界原点而相机并没有看向原点。其次是模型的 LOD 设置导致相机距离太远时被裁剪了。解决加载完成后立即执行一次「归位三连」——SetParent、localPosition归零、localRotation归零然后用 Gizmos 画一次包围盒确认模型实际位置。如果确认位置没问题检查相机farClipPlane和nearClipPlane有时候模型尺寸太大整个模型在视锥体之外。5.2 模型朝向不对坐标系差异与修正现象加载完的模型是「躺」着的或者整体绕某个轴旋转了 90 度。原因Unity 使用左手坐标系且 Y 轴向上而 3ds Max 习惯 Z 轴向上。FBX 文件内部带有轴信息TriLib 会读取并处理但 OBJ 文件是纯几何数据没有轴信息加载时直接按坐标原样映射就会出现 90 度翻转。解决如果是 OBJ直接在AssetLoaderOptions里设置Rotation Quaternion.Euler(-90f, 0f, 0f)这是最常见的修正值。如果是某个软件导出的特殊格式先做一次旋转变体测试。遇到个别模型转了 90 度但同格式其他模型正常那大概率是源文件本身轴设置不统一我在加载完成后会用context.LoadedGameObject的原始旋转值和预期旋转值做校验不一致时自动补偿。5.3 Android 真机上加载本地文件失败现象在编辑器里加载C:/xxx/model.fbx一切正常打包到 Android 真机后同样的代码读取路径却报「文件不存在」。原因Android 平台有沙盒机制应用不能像桌面一样直接读取任意路径。Application.persistentDataPath才是应用可读写的目录而Application.streamingAssetsPath在 Android 上是压缩包内部路径不能直接传给 TriLib 当作普通文件路径解析。解决先把文件复制到沙盒目录再从这个目录加载。项目中我一般用UnityWebRequest把文件从streamingAssetsPath读出二进制写入persistentDataPath最后把新路径传给 TriLib。另外Android 6.0 以上读取外部存储需要动态申请存储权限用NativeGallery或平台的权限 API 处理。5.4 模型显示成紫红色或材质丢失现象模型加载进来了形状也对但表面是紫红色或者贴图全部变成白色。原因紫红色一定是 Shader 不兼容。贴图变白通常是纹理加载失败——TriLib 在解析材质引用的贴图路径时如果模型文件旁边的纹理文件不存在或文件名对不上就会跳过贴图加载。解决逐层排查。先确认贴图文件和模型文件放在同一目录下且文件名必须与模型内部记录的名字完全一致包括大小写。再确认 Shader 在当前渲染管线里存在URP 项目不要直接生成 Standard 材质。替换 Shader 后如果贴图还是白检查纹理导入设置的sRGB和Max Size是否限制了加载。5.5 反复替换模型后内存持续上涨现象连续替换 10 次模型内存占用从 100MB 涨到 800MB没有回落趋势。原因只有一种可能——有代码持有了旧模型的引用。最常见的是事件回调没有注销比如某个 UI 按钮监听了模型的某个事件旧模型已经被Destroy但事件处理器还挂在旧模型的组件上。解决在UnloadCurrent里Destroy(currentModel)之前先用GetComponentsInChildrenMonoBehaviour()把所有脚本的enabled设为 false 并注销事件。另外对贴图和材质做一次引用检查如果业务层缓存了material实例Resources.UnloadUnusedAssets永远不会回收它。项目里我现在强制约定任何对运行时模型的引用不能超过一个帧循环的生命周期用完即置空。6. 验证加载结果用日志和 Gizmos 做可视化检查写一个ModelDebugger辅助类挂在根节点上自动输出模型关键信息。加载完成后打印顶点数、三角面数、材质数和子物体数这些是最基本的健康指标。对于动态导入的模型日志里还应该包含网格是否可读写、是否有碰撞体、Shader 名字。因为这些信息在编辑器里看一眼 Inspector 就能确认但在真机上只能靠日志定位。public static class ModelDebugUtils { public static void DumpModelInfo(GameObject root) { var filters root.GetComponentsInChildrenMeshFilter(); int verts 0; int tris 0; foreach (var filter in filters) { if (filter.sharedMesh ! null) { verts filter.sharedMesh.vertexCount; tris filter.sharedMesh.triangles.Length / 3; } } var renderers root.GetComponentsInChildrenRenderer(); var materialNames new System.Collections.Generic.Liststring(); foreach (var renderer in renderers) { foreach (var mat in renderer.sharedMaterials) { if (mat ! null) materialNames.Add(mat.shader.name); } } Debug.Log($[ModelDebug] 顶点数{verts} 三角面{tris} 材质数{materialNames.Count}); Debug.Log($[ModelDebug] Shader列表: {string.Join(, , materialNames.ToArray())}); } }调用时机放在OnModelLoaded里加载完成立刻执行。这样每次模型加载完控制台里会自动出现一行模型的体质报告。顶点数几百和几十万的加载耗时当然不一样Shader 是 Standard 还是 URP Lit 也一目了然不需要再打开 Profiler 去翻。Gizmos 画包围盒是另一个我每做必用的验证手段。用OnDrawGizmos在场景视图里画出当前模型的Bounds这样可以直观地检查模型有没有被错误地缩放到一个奇怪的比例或者是否整个模型偏移到了预期位置之外。真机上虽然看不到 Gizmos但把包围盒的center和size打到日志里也能在后台排查。private void OnDrawGizmos() { var bounds CalculateBounds(gameObject); Gizmos.color Color.yellow; Gizmos.DrawWireCube(bounds.center, bounds.size); }从那以后我每次做运行时模型加载功能都会强制走一遍「日志看顶点数、Gizmos 看包围盒、Profiler 看内存曲线」的验证流程。这套流程救了我好几次——有一次模型文件本身没问题但代码里误乘了一个 0.5 的缩放如果不是 Gizmos 画包围盒时发现模型缩小了一半这个问题可能真机跑几轮都发现不了。希望帮到你。本文还有配套的精品资源点击获取