Unity 的图片最终通常会被打进图集但业务代码仍然需要处理图集加载、Sprite 查找、引用持有和资源释放。MyFramework 使用AtlasManager同时封装SpriteAtlas v2和传统 Multi Sprite 图集并通过AtlasRef管理图集引用避免图片仍在使用时图集被提前卸载。项目地址https://github.com/ZHOURUIH/MyFramework一、AtlasManager 解决什么问题直接使用 Unity 图集时业务层需要考虑图集资源如何加载 如何通过名称查找 Sprite 多个界面共享图集时何时卸载 异步加载完成时界面是否还存在 SpriteAtlas 在真机上如何响应 atlasRequested TexturePacker 图集和 SpriteAtlas 如何使用统一接口AtlasManager将这些操作统一为加载图集 ↓ 获得 AtlasRef ↓ 通过名称获取 Sprite ↓ 界面或对象持有 AtlasRef ↓ 使用结束后释放引用 ↓ 引用数量为 0 时自动卸载业务层不需要区分当前图集来自SpriteAtlas还是一张设置为 Multiple 的纹理。二、同步加载图集图集路径相对于Assets/GameResources并且必须带后缀。例如图集位于Assets/GameResources/UI/Common.spriteatlasv2加载方式为using static FrameBaseHotFix; protected AtlasRef mCommonAtlas; protected void loadAtlas() { mCommonAtlas mAtlasManager.getAtlas( UI/Common.spriteatlasv2); if (mCommonAtlas null || !mCommonAtlas.isValid()) { return; } Sprite buttonSprite mCommonAtlas.getSprite(ButtonNormal); }getAtlas()首先检查图集是否已经加载。已经存在时只创建一份新的AtlasRef不存在时才通过ResourceManager加载图集资源并解析其中的 Sprite。三、AtlasRef 表示一次独立引用AtlasRef并不只是包装AtlasBase它还会为每个持有者生成独立凭证public void setAtlas(AtlasBase atlas) { mAtlas atlas; mToken generateToken(); mAtlas.addReference(mToken); }图集内部保存全部引用凭证protected HashSetlong mReferenceTokenList new();同一个图集被三个界面使用时结构类似Common.spriteatlasv2 ├── AtlasRef主界面 ├── AtlasRef背包界面 └── AtlasRef商店界面关闭背包界面只会释放背包自己的引用不会影响主界面和商店界面。因此不要把一份AtlasRef同时交给多个生命周期不同的对象。每一个独立持有者都应该通过getAtlas()获得自己的引用。四、释放图集引用不再使用图集时调用mAtlasManager.unloadAtlas( ref mCommonAtlas);unloadAtlas()会校验 AtlasRef 是否有效 移除当前引用凭证 回收 AtlasRef 把变量设置为 null不要直接卸载底层纹理或SpriteAtlasResources.UnloadAsset(texture); Object.Destroy(sprite);这些操作会绕过AtlasManager的引用记录可能让其他仍在显示图片的界面失去资源。五、为 UI 动态切换图集需要运行时切换图片的节点应使用myUGUIImage例如一个专门显示物品图标的节点public class UIItemDetail : LayoutScript { protected myUGUIImage mItemIcon; protected AtlasRef mItemAtlas; public override void assignWindow() { newObject( out mItemIcon, Background/ItemIcon); } public override void onGameState() { base.onGameState(); mItemAtlas mAtlasManager.getAtlas( UI/Item.spriteatlasv2); mItemIcon.setAtlas(mItemAtlas, true); mItemIcon.setSpriteName(Item_Sword); } public override void onHide() { mItemIcon.setAtlas(null, true); mAtlasManager.unloadAtlas( ref mItemAtlas); base.onHide(); } }myUGUIImage.setAtlas()只负责切换当前使用的图集并不会接管外部传入图集的释放。因此动态加载的AtlasRef仍然需要由业务对象保存并在生命周期结束时主动卸载。六、为什么需要 ImageAtlasPath运行时只通过一个Sprite无法可靠得知它来自哪个资源路径或哪个图集。所以 MyFramework 为需要切换图片的节点提供了ImageAtlasPath它会在编辑模式下记录当前图片所在图集public string mAtlasPath;myUGUIImage.init()中会读取这个路径并获取初始图集引用Image ↓ ImageAtlasPath 记录图集路径 ↓ myUGUIImage 初始化 ↓ AtlasManager 加载初始图集因此需要使用myUGUIImage动态切换 Sprite 的节点应确保存在 Image 组件 存在 ImageAtlasPath 组件 ImageAtlasPath 中记录的路径正确普通静态图片不需要在代码中切换时可以继续使用myUGUIImageSimple。七、异步安全加载图集图集较大或者界面需要异步打开时可以使用getAtlasAsyncSafe示例protected AtlasRef mItemAtlas; protected void loadAtlasAsync() { mAtlasManager.getAtlasAsyncSafe( this, UI/Item.spriteatlasv2, (atlas) { mItemAtlas atlas; mItemIcon.setAtlas( mItemAtlas, true); mItemIcon.setSpriteName( Item_Sword); }); }第一个参数需要实现IRecyclable。开始加载时框架会记录对象当前的AssignID。完成后再次检查AssignID 没有变化 执行回调 对象已销毁或被对象池重新分配 不执行旧回调这样可以避免界面已经关闭后旧的图集加载结果又设置到被复用的界面对象上。八、相同图集的异步请求会被合并AtlasManager内部维护protected Dictionary string, ListAtlasLoadParam mLoadRequestList new(); protected Dictionary string, ListAtlasLoadParam mLoadingList new();当多个对象同时请求同一个图集时不会重复发起多次资源加载。流程为界面A请求 Item.spriteatlasv2 ↓ 开始加载图集 界面B再次请求同一路径 ↓ 只把回调加入等待列表 图集加载完成 ↓ 创建一个 AtlasBase ↓ 依次为所有请求创建 AtlasRef ↓ 分别执行回调同时加载的不同图集数量最多为protected const int MAX_LOADING_COUNT 20;超过上限的请求会暂时保留等待其他图集完成后再开始。九、统一支持两种图集格式图集加载完成后AtlasManager会根据后缀决定解析方式。SpriteAtlas v2后缀为.spriteatlasv2创建AtlasUGUI atlas new(mainAsset);然后通过spriteAtlas.GetSprites(spriteList);取出图集中的全部 Sprite并以名称缓存。Multi Sprite 图集其他包含多个 Sprite 的纹理会创建AtlasTP atlas new(mainAsset);加载结果中Texture2D 用于保存实际图集纹理 Sprite 逐个加入名称缓存最终两者都继承AtlasBase业务层始终使用atlasRef.getSprite(spriteName);不需要为不同图集格式分别编写代码。十、图集如何自动卸载AtlasManager每隔两秒检查一次已加载图集protected const float CHECK_INTERVAL 2.0f;满足以下条件时自动销毁AtlasRef 引用数量为 0 并且 图集不在常驻列表中核心判断为if (atlas.getReferenceCount() 0 allowUnloadAtlas(atlasPath)) { atlas.destroy(); mAtlasList.remove(atlasPath); }销毁时会清空 Sprite 名称缓存 释放主资源 ResourceRef 从 AtlasManager 中移除图集高频使用、不希望反复卸载的图集可以设置为常驻mAtlasManager.addDontUnloadAtlas( UI/Common.spriteatlasv2);常驻图集仍然需要正确释放AtlasRef只是引用归零后不会被自动卸载。十一、真机上的 SpriteAtlas 加载Unity 在运行时可能通过SpriteAtlasManager.atlasRequested请求某个SpriteAtlas。AtlasManager.init()中会注册SpriteAtlasManager.atlasRequested onAtlasRequested;收到请求后框架通过AtlasPathConfig.txt把图集名称转换为资源路径再使用ResourceManager加载对应的SpriteAtlas。这一步主要用于保证真机上 Prefab 或场景中的 Sprite 能正确绑定到动态加载的图集。AtlasPathConfig.txt应由框架的资源流程生成和维护业务代码不需要手动响应atlasRequested。十二、总结MyFramework 的图集管理流程是加载 SpriteAtlas 或 Multi Sprite ↓ 统一解析为 AtlasBase ↓ 缓存全部 Sprite ↓ 为每个持有者创建 AtlasRef ↓ 通过名称获取 Sprite ↓ 使用结束后释放 AtlasRef ↓ 引用归零后自动卸载图集常用接口包括mAtlasManager.getAtlas(...); mAtlasManager.getAtlasAsyncSafe(...); atlasRef.getSprite(...); mAtlasManager.unloadAtlas(ref atlasRef); mAtlasManager.addDontUnloadAtlas(...);AtlasManager的核心并不只是通过名字查找图片而是把图集加载、格式兼容、异步请求合并、引用计数和自动卸载统一起来。业务层只需要明确使用哪个图集、获取哪张图片以及什么时候结束持有。
Unity 的图片最终通常会被打进图集但业务代码仍然需要处理图集加载、Sprite 查找、引用持有和资源释放。MyFramework 使用AtlasManager同时封装SpriteAtlas v2和传统 Multi Sprite 图集并通过AtlasRef管理图集引用避免图片仍在使用时图集被提前卸载。项目地址https://github.com/ZHOURUIH/MyFramework一、AtlasManager 解决什么问题直接使用 Unity 图集时业务层需要考虑图集资源如何加载 如何通过名称查找 Sprite 多个界面共享图集时何时卸载 异步加载完成时界面是否还存在 SpriteAtlas 在真机上如何响应 atlasRequested TexturePacker 图集和 SpriteAtlas 如何使用统一接口AtlasManager将这些操作统一为加载图集 ↓ 获得 AtlasRef ↓ 通过名称获取 Sprite ↓ 界面或对象持有 AtlasRef ↓ 使用结束后释放引用 ↓ 引用数量为 0 时自动卸载业务层不需要区分当前图集来自SpriteAtlas还是一张设置为 Multiple 的纹理。二、同步加载图集图集路径相对于Assets/GameResources并且必须带后缀。例如图集位于Assets/GameResources/UI/Common.spriteatlasv2加载方式为using static FrameBaseHotFix; protected AtlasRef mCommonAtlas; protected void loadAtlas() { mCommonAtlas mAtlasManager.getAtlas( UI/Common.spriteatlasv2); if (mCommonAtlas null || !mCommonAtlas.isValid()) { return; } Sprite buttonSprite mCommonAtlas.getSprite(ButtonNormal); }getAtlas()首先检查图集是否已经加载。已经存在时只创建一份新的AtlasRef不存在时才通过ResourceManager加载图集资源并解析其中的 Sprite。三、AtlasRef 表示一次独立引用AtlasRef并不只是包装AtlasBase它还会为每个持有者生成独立凭证public void setAtlas(AtlasBase atlas) { mAtlas atlas; mToken generateToken(); mAtlas.addReference(mToken); }图集内部保存全部引用凭证protected HashSetlong mReferenceTokenList new();同一个图集被三个界面使用时结构类似Common.spriteatlasv2 ├── AtlasRef主界面 ├── AtlasRef背包界面 └── AtlasRef商店界面关闭背包界面只会释放背包自己的引用不会影响主界面和商店界面。因此不要把一份AtlasRef同时交给多个生命周期不同的对象。每一个独立持有者都应该通过getAtlas()获得自己的引用。四、释放图集引用不再使用图集时调用mAtlasManager.unloadAtlas( ref mCommonAtlas);unloadAtlas()会校验 AtlasRef 是否有效 移除当前引用凭证 回收 AtlasRef 把变量设置为 null不要直接卸载底层纹理或SpriteAtlasResources.UnloadAsset(texture); Object.Destroy(sprite);这些操作会绕过AtlasManager的引用记录可能让其他仍在显示图片的界面失去资源。五、为 UI 动态切换图集需要运行时切换图片的节点应使用myUGUIImage例如一个专门显示物品图标的节点public class UIItemDetail : LayoutScript { protected myUGUIImage mItemIcon; protected AtlasRef mItemAtlas; public override void assignWindow() { newObject( out mItemIcon, Background/ItemIcon); } public override void onGameState() { base.onGameState(); mItemAtlas mAtlasManager.getAtlas( UI/Item.spriteatlasv2); mItemIcon.setAtlas(mItemAtlas, true); mItemIcon.setSpriteName(Item_Sword); } public override void onHide() { mItemIcon.setAtlas(null, true); mAtlasManager.unloadAtlas( ref mItemAtlas); base.onHide(); } }myUGUIImage.setAtlas()只负责切换当前使用的图集并不会接管外部传入图集的释放。因此动态加载的AtlasRef仍然需要由业务对象保存并在生命周期结束时主动卸载。六、为什么需要 ImageAtlasPath运行时只通过一个Sprite无法可靠得知它来自哪个资源路径或哪个图集。所以 MyFramework 为需要切换图片的节点提供了ImageAtlasPath它会在编辑模式下记录当前图片所在图集public string mAtlasPath;myUGUIImage.init()中会读取这个路径并获取初始图集引用Image ↓ ImageAtlasPath 记录图集路径 ↓ myUGUIImage 初始化 ↓ AtlasManager 加载初始图集因此需要使用myUGUIImage动态切换 Sprite 的节点应确保存在 Image 组件 存在 ImageAtlasPath 组件 ImageAtlasPath 中记录的路径正确普通静态图片不需要在代码中切换时可以继续使用myUGUIImageSimple。七、异步安全加载图集图集较大或者界面需要异步打开时可以使用getAtlasAsyncSafe示例protected AtlasRef mItemAtlas; protected void loadAtlasAsync() { mAtlasManager.getAtlasAsyncSafe( this, UI/Item.spriteatlasv2, (atlas) { mItemAtlas atlas; mItemIcon.setAtlas( mItemAtlas, true); mItemIcon.setSpriteName( Item_Sword); }); }第一个参数需要实现IRecyclable。开始加载时框架会记录对象当前的AssignID。完成后再次检查AssignID 没有变化 执行回调 对象已销毁或被对象池重新分配 不执行旧回调这样可以避免界面已经关闭后旧的图集加载结果又设置到被复用的界面对象上。八、相同图集的异步请求会被合并AtlasManager内部维护protected Dictionary string, ListAtlasLoadParam mLoadRequestList new(); protected Dictionary string, ListAtlasLoadParam mLoadingList new();当多个对象同时请求同一个图集时不会重复发起多次资源加载。流程为界面A请求 Item.spriteatlasv2 ↓ 开始加载图集 界面B再次请求同一路径 ↓ 只把回调加入等待列表 图集加载完成 ↓ 创建一个 AtlasBase ↓ 依次为所有请求创建 AtlasRef ↓ 分别执行回调同时加载的不同图集数量最多为protected const int MAX_LOADING_COUNT 20;超过上限的请求会暂时保留等待其他图集完成后再开始。九、统一支持两种图集格式图集加载完成后AtlasManager会根据后缀决定解析方式。SpriteAtlas v2后缀为.spriteatlasv2创建AtlasUGUI atlas new(mainAsset);然后通过spriteAtlas.GetSprites(spriteList);取出图集中的全部 Sprite并以名称缓存。Multi Sprite 图集其他包含多个 Sprite 的纹理会创建AtlasTP atlas new(mainAsset);加载结果中Texture2D 用于保存实际图集纹理 Sprite 逐个加入名称缓存最终两者都继承AtlasBase业务层始终使用atlasRef.getSprite(spriteName);不需要为不同图集格式分别编写代码。十、图集如何自动卸载AtlasManager每隔两秒检查一次已加载图集protected const float CHECK_INTERVAL 2.0f;满足以下条件时自动销毁AtlasRef 引用数量为 0 并且 图集不在常驻列表中核心判断为if (atlas.getReferenceCount() 0 allowUnloadAtlas(atlasPath)) { atlas.destroy(); mAtlasList.remove(atlasPath); }销毁时会清空 Sprite 名称缓存 释放主资源 ResourceRef 从 AtlasManager 中移除图集高频使用、不希望反复卸载的图集可以设置为常驻mAtlasManager.addDontUnloadAtlas( UI/Common.spriteatlasv2);常驻图集仍然需要正确释放AtlasRef只是引用归零后不会被自动卸载。十一、真机上的 SpriteAtlas 加载Unity 在运行时可能通过SpriteAtlasManager.atlasRequested请求某个SpriteAtlas。AtlasManager.init()中会注册SpriteAtlasManager.atlasRequested onAtlasRequested;收到请求后框架通过AtlasPathConfig.txt把图集名称转换为资源路径再使用ResourceManager加载对应的SpriteAtlas。这一步主要用于保证真机上 Prefab 或场景中的 Sprite 能正确绑定到动态加载的图集。AtlasPathConfig.txt应由框架的资源流程生成和维护业务代码不需要手动响应atlasRequested。十二、总结MyFramework 的图集管理流程是加载 SpriteAtlas 或 Multi Sprite ↓ 统一解析为 AtlasBase ↓ 缓存全部 Sprite ↓ 为每个持有者创建 AtlasRef ↓ 通过名称获取 Sprite ↓ 使用结束后释放 AtlasRef ↓ 引用归零后自动卸载图集常用接口包括mAtlasManager.getAtlas(...); mAtlasManager.getAtlasAsyncSafe(...); atlasRef.getSprite(...); mAtlasManager.unloadAtlas(ref atlasRef); mAtlasManager.addDontUnloadAtlas(...);AtlasManager的核心并不只是通过名字查找图片而是把图集加载、格式兼容、异步请求合并、引用计数和自动卸载统一起来。业务层只需要明确使用哪个图集、获取哪张图片以及什么时候结束持有。
