# zframework

**Repository Path**: Wnity/zframework

## Basic Information

- **Project Name**: zframework
- **Description**: framework framework framework
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: unitask
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2022-01-10
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: zframework

## README

# zframework

zframework 是一个为 Unity 开发者设计的轻量级框架，旨在用UniTask简化资源管理、对象池、精灵图集生成等功能。它提供了一系列工具类和管理器，帮助开发者快速实现常见的游戏开发需求。

视频教程：
[zframework视频教程](https://space.bilibili.com/627098864/lists/6817103?type=season)

<br/>

## 功能特性
- **资源加载管理**：通过 `UnityResMgr` 和`GlobalResMgr` 类支持同步和异步加载资源，支持多种加载方式。
- **下载管理**：通过 `DownloadFileMgr` 类实现文件的下载功能。
- **网络请求管理**：通过 `WebRequestMgr` 类实现简单的网络请求。
- **精灵图集生成**：通过 `SpriteAtlasGenerator` 类和`UISpriteAtlasCreator` 类在编辑器中生成精灵图集。
- **精灵管理**：通过 `SpriteAtlasMgr` 类管理精灵图集的加载与使用。
- **异步加载sprite和texture扩展**：通过 `SpriteRendererExtend`,`RendererExtend`,`MaterialExtend`,`UGUI_Extend` 类实现 sprite 和texture 资源的异步加载。
- **对象池管理**：通过 `ObjectPool` 类实现高效的对象创建与回收，减少频繁的垃圾回收压力。
- **Coroutine 扩展**：通过 `CoroutineUtil` 类和 `CoroutineUtilUGUI` 类扩展协程功能，能让协程有返回值功能和等待按钮点击功能。
- **单例**：包含MonoBehavior和ScriptableObject的单例泛型实现，和快速生成单例资源功能。
- **SafeArea UI适配器**：可以多种方式适配手机浏海和安全区。


<br/>

## 安装

1. 若要把zframework全部功能加载到项目中，下面的文本加到Packages/manifest.json里：
   ```
       "com.wnity.zframework": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework",
   ```

2. 若只要zframework的部分功能，把下面文本中需要用到的功能加到Packages/manifest.json里：
   ```
    "com.wnity.zframework.singleton": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/Singleton",
    "com.wnity.zframework.resutil": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/ResUtil",
    "com.wnity.zframework.spriteatlasutil": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/SpriteAtlasUtil",
    "com.wnity.zframework.uguiextend": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/UGUI_Extend",
    "com.wnity.zframework.objectpool": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/ObjectPool",
    "com.wnity.zframework.coroutineutil": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/CoroutineUtil",
    "com.wnity.zframework.coroutineutilugui": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/CoroutineUtilUGUI",
    "com.wnity.zframework.safeareautil": "https://gitee.com/Wnity/zframework.git?path=Assets/zframework/SafeAreaUtil",
   ```

3.

<br/>

## 使用示例

<br/>


### 资源加载

```csharp
// 异步加载资源
async UniTask Test()
{
    //ResMgr可用于加载Addressable和Resouces的资源，如果加载Shader，也会使用Shader.Find查找
    var prefab = await UnityResMgr.Instance.LoadAssetAsync<GameObject>("texture_addresssable_path");
    


    //LoadAssetMgr可用于加载http,streamingAsset,external,Addressable,Resources的资源
    var texture = await GlobalResMgr.Instance.LoadTextureAsync("https://texture.path");
    var texture = await GlobalResMgr.Instance.LoadTextureAsync(Application.streamingAssetsPath + "/texture.path");
    var texture = await GlobalResMgr.Instance.LoadTextureAsync(Application.persistentDataPath + "/texture.path");
    var texture = await GlobalResMgr.Instance.LoadTextureAsync("/texture_resources_path");
    var texture = await GlobalResMgr.Instance.LoadTextureAsync("/texture_addresssable_path");
    
    
    // 同步加载资源
    var texture = GlobalResMgr.Instance.LoadTexture("https://texture.path");
    var texture = UnityResMgr.Instance.LoadAsset<Texture2D>("https://texture.path");


    //SpriteRenderer,Image有接受字符串路径的异步加载方式,可接受addressable和resources
    spriteRenderer.SetSprite("resouces_spritePath");
    image.SetSprite("addressable_spritePath");


    //Renderer,Material,RawImage有接受字符串路径的异步加载方式,可接受http,streamingAsset,external, addressable和resources
    renderer.SetTexture("https://texturePath");
    material.SetTexture(Application.streamAssetsPath + "/texturePath");
    rawImage.SetTexture(Application.persistentDataPath + "/texturePath");
    renderer.SetTexture("resouces_spritePath");
    material.SetTexture("addressable_spritePath");
    

    //同步和异步加载场景，都支持加载Addressable和BuildSettings的场景
    bool success = UnityResMgr.LoadScene("sceneNameOrScenePath");
    bool success = await UnityResMgr.LoadSceneAsync("sceneNameOrScenePath");
    

    //GlobalResMgr加载文件的文本或byte[]，支持http,磁盘，streamingAsset,Addressable,Resources的资源，
    var text = await GlobalResMgr.instance.LoadTextAsync("http://textpath");
    var bytes = await GlobalResMgr.instance.LoadBytesAsync("http://textpath");
    

    //也有同步方法
    var text = GlobalResMgr.instance.LoadText("http://textpath");
    var bytes = GlobalResMgr.instance.LoadBytes("http://textpath");
    
    
    //还支持https://github.com/TLabAltoh/Unity-SDF-UI-Toolkit 的异步同步加载texture和sprite
    SDFUI ui = ...;
    ui.SetTexture("texturePath");
    ui.SetSprite("SpritePath");
}

```

<br/>

### 下载文件

```csharp
// 异步下载文件，把会文件下到本地，并返回本地文件路径
async UniTask Test()
{
    //下载
    var localFilePath = await DownloadFileMgr.Instance.DownloadAsync("http://example.com/file.txt");
    //使用
    System.IO.File.ReadAllText(localFilePath);
}
```

<br/>


### 对象池使用

```csharp
// 从对象池中获取对象
GameObject prefab = Resources.Load<GameObject>("prefabPath");
GameObject obj = ObjectPool.InstantiateFromPool(prefab);

// 将对象回收到对象池
obj.RecycleToPool();
```

<br/>

### SpriteAtlas生成
1. 在project 视图中点鼠标右键出菜单项，点选Create => zframework => CreateUISpriteAtlas创建 `SpriteAtlasGenerator` 资源。
2. 配置参数。
```
Atlas Infos：图集信息
    include in build: 是SpriteAtlas的include in build,如非勾选，需用Unity的SpriteAtlasManager.atlasRequested注册手动创建图集事件,zframework的SpriteAtlasLateBindingMgr就是干这个的
    Auto Add to Addressable: 自动加到Addressable
    Addressable Group Name: 图集要加入到addressable的组名
    Paths: Sprite或目录的路径
    Objs: Sprite或目录的Asset
Atlas OutputPath: 生成输出路径
```
3. 点击菜单项 zframework => SpriteAtlasUtil => GenerateAtlases" 按钮生成精灵图集。

<br/>


### 分析UI prefab生成图集配值信息(SpriteAtlasGenerator)和图集:
1. 在project 视图中点鼠标右键出菜单项，点选Create=>zframework=>CreateUISpriteAtlas创建 `UISpriteAtlasCreator` 资源。
2. 配置参数。
```
UI Prefab Paths：需要分析prefab目录
UI Frame Paths: ui边框图的目录
Altas Output Path: 图集输出路径
Enable Common Atlas: 是否生成公共图集
Auto Add to Addressable: 自己动把图集加到Addressables
Separate Addressable group: 是否一个图集一个group
```
3. 点击菜单项 zframework => SpriteAtlasUtil => CreateUISpriteAtlas" 按钮生成图集配值信息(SpriteAtlasGenerator)和图集。

<br/>


### SpriteAtlasLateBindingMgr
这是图集 late binding管理器，会自动收集非include in build并可被addressable或resources读取的图集，在运行时会注册SpriteAtlasManager.atlasRequested方法帮助读取图集

<br/>

### 协程工具CoroutineUtil和CoroutineUtilUGUI
这两个工具主要是为了替代UniTask不适合使用的情况：
1.使用UniTask返回结果要使用泛型，不利于某些环境，例如hybirdclr的一些特定热更情况
```
//这两个工具主要提供了下面的协程返回值的功能
//返回结果
public IEnumerator TestWithResult()
{
    IEnumerator ReturnResult()
    {
        yield return new WaitForSeconds(1);
        yield return 1; //返回结果，但不能返回null。yield return null代表停一帧
    }

    var c = ReturnResult().WithResult();
    yield return c;
    var result = (int)c.Current;

    Assert.AreEqual(1, result);
}


//Button的WaitOnClick示例
public IEnumerator TestWaitOnClick()
{
    var btn = this.gameObject.GetComponent<Button>();
    yield return btn.WaitOnClick(); //等待按钮被点击，和UniTask的OnClickAsync类似
    Debug.Log("btn clicked");
}
```
另还有不依赖MonoBehaviour的StartCoroutine()和WaitAll, WaitAny，类似UniTask的WhenAll,WhenAny。看项目的UnitTest了解使用细节。


<br/>

### 单例
有时我们可能想单例可用到MonoBehaviour和ScriptableObject的功能，例如序列化，Update,LateUpdate,协程的功能。
所以编写了MonoBehaviourSingleton和ScriptableObjectSingleton，并且对单例脚本使用菜单项 Assets => Create => zframework => CreateSingletonAsset可在Asset/Resources目录下立即创建资源，在运行时会自动读取

<br/>

### SafeArea UI适配器(SafeAreaAdapter)
支持三种适配模式，无适改动代码，只需要改UI的anchor就会自动选择对应的模式，详细可看UnitTest里的TestSafeAreaUtil:

模式一：
运行前:
<img src="https://gitee.com/Wnity/zframework/raw/unitask/preview_imgs/mode-0_beforeplay.png" height="100"/>
 => 运行后：<img src="https://gitee.com/Wnity/zframework/raw/unitask/preview_imgs/mode-0_afterplay.png" height="100"/>

模式二：
运行前:
<img src="https://gitee.com/Wnity/zframework/raw/unitask/preview_imgs/mode-1_beforeplay.png" height="100"/>
 => 运行后：<img src="https://gitee.com/Wnity/zframework/raw/unitask/preview_imgs/mode-1_afterplay.png" height="100"/>

模式三：
运行前:
<img src="https://gitee.com/Wnity/zframework/raw/unitask/preview_imgs/mode-2_beforeplay.png" height="100"/>
 => 运行后：<img src="https://gitee.com/Wnity/zframework/raw/unitask/preview_imgs/mode-2_afterplay.png" height="100"/>

<br/>

### 单元测试
单元测试用例在目录Assets/UnitTest，分Editor Mode用例和Play Mode用例,运行测试用例需打开菜单项Window=>General=>TestRunner
参考：https://docs.unity3d.com/Packages/com.unity.test-framework@1.4/manual/index.html

<br/>

## Unity技术讨论群
qq:  **951129597** 

<br/>

## 贡献

欢迎贡献代码和提出建议！请通过 [GitHub Issues](https://gitee.com/Wnity/zframework/issues) 提交问题或建议。

<br/>

## 许可证

本项目使用 MIT 许可证。详情请查看 [LICENSE](LICENSE) 文件。