GitHub:YMoonRiver/hybridclr_addressable: 開箱即用的商業(yè)游戲框架，集成了主流的開發(fā)工具。將主流的GameFramework修改，支持Addressable和AssetBundle，已完善打包工具和流程。 (github.com)

# 新增GameFramework Addressables 開箱即用
# 新增循環(huán)列表

### UnityGameFramework ?

**此框架參考:** ??

`GameFramework`：[https://github.com/EllanJiang/GameFramework](https://github.com/EllanJiang/GameFramework) ?
`UniRx`: [https://github.com/neuecc/UniRx](https://github.com/neuecc/UniRx) ?
`UniTask`: [https://github.com/Cysharp/UniTask](https://github.com/Cysharp/UniTask) ??

---

### Package

`Addressable` `1.17.17+`

### 內(nèi)置模塊介紹

---

### DataTable
DataTable為了配置修改不再動態(tài)生成或修改對應(yīng)的序列化的類，進行全動態(tài)的解析。
為了做到通用性解析，配置表有一定的規(guī)則，以Excel操作的配置表為例。
* 每一行前面第一列帶`#`號代表忽略。前面四行是固定的
* 第一行是配置表的名稱;
* 第二行是配置表的鍵值;
* 第三行為當(dāng)前列的數(shù)據(jù)類型,`[bool,int,long,float,double,string,Vector2,Vector3,Color]`,`Vector2`示例`100,100`,`Color`示例`#F0F`或者`#FF00FF`;
* 第四行是每一列的說明。
* 實際數(shù)據(jù)以第五行,第二列開始，第二列的數(shù)據(jù)一定為`int`類型的唯一識別`id`
* 最后用excel導(dǎo)出為`Unicode 文本`格式即可。

?配置表示例?

||||||||| ?
|-|-|-|-|-|-|-|-| ?
|#|關(guān)卡配置表| ?
|#|Id|LevelSort|UIFormId|LevelName|LevelDesc|Leveldubing|IsHide|
|#|int|int|int|string|string|int|bool|
|#|關(guān)卡Id|關(guān)卡排序|界面編號|關(guān)卡名稱|關(guān)卡描述|配音|是否隱藏|
||20010001|1|300|測試名稱|測試說明|2352|false|
||20010002|2|200|測試名稱02|測試說明02|23521|false|

使用示例

```csharp
//DataTable加載事件監(jiān)聽
GameMode.Event.AddListener<LoadDataTableEventArgs>(OnLoadDataTable);
//加載DataTable
GameMode.DataTable.LoadDataTable("Assets/Game/DataTable/GameCheckpoint.txt");

//DataTable加載事件回調(diào)
private void OnLoadDataTable(object sender,IEventArgs e)
{
? ? LoadDataTableEventArgs ne = e as LoadDataTableEventArgs;
? ? if(ne!=null)
? ? {
? ? ? ? IDataTable idt = ?ne.Data;

? ? ? ? TableData td=idt[20010012]["UIFormId"];
? ? ? ? int uiFormId = (int)td;
? ? ? ??
? ? ? ? Debug.Log($"#################################:{ne.Message}");
? ? ? ? foreach (var item in idt)
? ? ? ? {
? ? ? ? ? ? Debug.Log($"-------------------------------------------------------");
? ? ? ? ? ? TableData td02 = idt[item];
? ? ? ? ? ? foreach (var item02 in td02)
? ? ? ? ? ? {
? ? ? ? ? ? ? ? Debug.Log(item02.ToString());
? ? ? ? ? ? }
? ? ? ? }
? ? }
}

//使用已加載的DataTable
IDataTable idt = GameMode.DataTable.GetDataTable("Assets/Game/DataTable/GameCheckpoint.txt");

```
`IDataTable`是當(dāng)前配置表的所有數(shù)據(jù)的集合，可使用`foreach`獲取到數(shù)據(jù)的`key`值，`TableData`是具體數(shù)據(jù)存儲對象，主要支持上述的第三行的基本類型。

#### 一、事件模塊 `EventManager`

整個框架以事件作為驅(qū)動，以達(dá)到各個功能之間的解耦效果。除了可以自定義擴展事件以外，框架中還會自帶一些事件，后面再詳細(xì)列表。

1. 新建事件，新建一個類并繼承`GameEventArgs`

```csharp
/// <summary>
/// 場景加載中事件
/// </summary>
public class SceneLoadingEventArgs : GameEventArgs<SceneLoadingEventArgs>
{
? ? /// <summary>
? ? /// 場景名稱
? ? /// </summary>
? ? public string SceneName;
? ? /// <summary>
? ? /// 場景加載進度
? ? /// </summary>
? ? public float Progress;
}
```

2. 訂閱事件

```csharp
GameFrameworkMode.GetModule<EventManager>().AddListener<SceneLoadingEventArgs>(OnSceneLoadingCallbak);
```

3. 取消事件訂閱

```csharp
GameFrameworkMode.GetModule<EventManager>().RemoveListener<SceneLoadingEventArgs>(OnSceneLoadingCallbak);
```

4. 事件回調(diào)的函數(shù)實現(xiàn)

```csharp
private void OnSceneLoadingCallbak(object sender, IEventArgs e)
{
? ? SceneLoadingEventArgs ne = (SceneLoadingEventArgs) e;
? ? //...
}
```

5. 事件觸發(fā)

```csharp
//第一種方式 帶參數(shù)觸發(fā)事件
GameFrameworkMode.GetModule<EventManager>()
?? ? ? ? ? ?.Trigger(this, new SceneLoadingEventArgs() {SceneName = "xxx", Progress = 0.85f});
//第二種方式 不帶參數(shù)觸發(fā)事件， 不帶參數(shù)， 就不用生成新的對象，會直接傳null
// GameFrameworkMode.GetModule<EventManager>().Trigger<SceneLoadingEventArgs>(this);
```

---

#### 二、游戲狀態(tài)模塊 `GameStateManager`

游戲狀態(tài)是整個項目的核心邏輯，建議將所有的邏輯都寫再狀態(tài)之中。增加狀態(tài)管理幾乎將各個類型的項目的開發(fā)都能盡量模式話，常用的狀態(tài):版本更新狀態(tài)->配置加載狀態(tài)->資源預(yù)加載->開始游戲->...

1. 增加狀態(tài)，所有的狀態(tài)都需要繼承GameState,并在類名上添加類標(biāo)記[GameState]

```csharp
[GameState]
public class LoadConfigState : GameState
{
? ? /// <summary>
? ? /// 初始化 -- 只執(zhí)行一次
? ? /// </summary>
? ? public override void OnInit()
? ? {
? ? ? ? base.OnInit();
? ? }

? ? /// <summary>
? ? /// 進入狀態(tài)
? ? /// </summary>
? ? /// <param name="parameters">不確定參數(shù)</param>
? ? public override void OnEnter(params object[] parameters)
? ? {
? ? ? ? base.OnEnter(parameters);
? ? }

? ? /// <summary>
? ? /// 退出狀態(tài)
? ? /// </summary>
? ? public override void OnExit()
? ? {
? ? ? ? base.OnExit();
? ? }

? ? /// <summary>
? ? /// 固定幀函數(shù)
? ? /// </summary>
? ? public override void OnFixedUpdate()
? ? {
? ? ? ? base.OnFixedUpdate();
? ? }

? ? /// <summary>
? ? /// 渲染幀函數(shù)
? ? /// </summary>
? ? public override void OnUpdate()
? ? {
? ? ? ? base.OnUpdate();
? ? }
}
```

2. 狀態(tài)的類標(biāo)記有四種類似?

* `[GameState]` 普通狀態(tài)
* `[GameState(GameStateType.Normal)]` 普通狀態(tài)
* `[GameState(GameStateType.Ignore)]` 忽略狀態(tài)，表示在狀態(tài)管理中忽略這個類的存在
* `[GameState(GameStateType.Start)]` 開始狀態(tài)，在運行時，第一個運行的狀態(tài)類標(biāo)記

3. 狀態(tài)切換,每個狀態(tài)都有一個ChangeState函數(shù)

```csharp
//切換到開始狀態(tài)
ChangeState<StartState>();
```

---

#### 三、資源管理模塊 `ResourceManager`

資源加載使用`async-await`來做異步加載資源

1. 資源加載(異步加載 )

```csharp
//加載普通資源
TextAsset textAsset= await GameFrameworkMode.GetModule<ResourceManager>().LoadAsset<TextAsset>("datatable","Assets/TextAssets/test.txt");
//實例化GameObject
GameObject obj = await GameFrameworkMode.GetModule<ResourceManager>().LoadAsset<GameObject>("player","Assets/Players/player.prefab");
GameObject player = Instantiate(obj);
```

2. 資源加載(同步加載)

```csharp
//先加載assetbundle
GameFrameworkMode.GetModule<ResourceManager>().LoadAssetBundle("hotfix");
//再加載資源
GameFrameworkMode.GetModule<ResourceManager>().LoadAssetSync("hotfix","main");
```

3. 內(nèi)置對象池

* 添加預(yù)設(shè)
```csharp
GameFrameworkMode.GetModule<ResourceManager>().AddPrefab("player","Assets/Prefab/Player.prefab",
?? ??? ??? ??? ??? ?new PoolPrefabInfo() {Prefab = playerPrefab,PreloadAmount=3, MaxAmount = 10});
```
* 生成對象
```csharp
GameObject player= GameFrameworkMode.GetModule<ResourceManager>().Spawn("Assets/Prefab/Player.prefab");
```
* 銷毀對象
```csharp
GameFrameworkMode.GetModule<ResourceManager>().Despawn(player);
```

4. 加載場景,場景只支持異步加載

```csharp
AsyncOperation asyncOperation= await GameFrameworkMode.GetModule<ResourceManager>().LoadSceneAsync("mainscene","Assets/Scene/Main.unity");
```

5. 支持編輯器內(nèi)資源的直接讀取和AssetBundle資源讀取兩種方式的一鍵切換，避免測試的時候需要重復(fù)的打包AssetBundle資源

---

#### 四、UI管理模塊 `UIManager`

1. 新建ui預(yù)設(shè)，新建ui類，繼承類`UIView`,綁定并在類名上標(biāo)明預(yù)設(shè)的資源路徑

```csharp
[UIView("ui","Assets/Prefab/UI/LoadingView.prefab")]
public class LoadingUIView : UIView
{
?? ?/// <summary>
?? ?/// 打開界面
?? ?/// </summary>
?? ?/// <param name="parameters">不確定參數(shù)</param>
?? ?public override void OnEnter(params object[] parameters)
?? ?{
?? ??? ?throw new System.NotImplementedException();
?? ?}
?? ?/// <summary>
?? ?/// 退出界面
?? ?/// </summary>
?? ?public override void OnExit()
?? ?{
?? ??? ?throw new System.NotImplementedException();
?? ?}
?? ?/// <summary>
?? ?/// 暫停界面
?? ?/// </summary>
?? ?public override void OnPause()
?? ?{
?? ??? ?throw new System.NotImplementedException();
?? ?}
?? ?/// <summary>
?? ?/// 恢復(fù)界面
?? ?/// </summary>
?? ?public override void OnResume()
?? ?{
?? ??? ?throw new System.NotImplementedException();
?? ?}
}
```

2. 打開ui

```csharp
GameFrameworkMode.GetModule<UIManager>().Push<LoadingUIView>();
```

3. 關(guān)閉ui,在看到`push`&`pop`的時候，就知道`UIManager`是基于堆棧管理`UI`的，`pop`自然關(guān)閉的是最新打開的界面
也可以調(diào)用close接口

```csharp
GameFrameworkMode.GetModule<UIManager>().Pop();
```

---

#### 五、數(shù)據(jù)節(jié)點模塊 `NodeManager`

數(shù)據(jù)節(jié)點只用來存儲在運行中的數(shù)據(jù),用法類似`PlayerPrefs`

1. 存數(shù)據(jù)

```csharp
GameFrameworkMode.GetModule<NodeManager>().SetInt("Level", 10);
```

2. 取數(shù)據(jù)

```csharp
int level= GameFrameworkMode.GetModule<NodeManager>().GetInt("Level");
```

---

#### 六、Http網(wǎng)頁請求模塊 `WebRequestManager`

網(wǎng)頁請求目前主要包含讀取http上的文本文件和下載http服務(wù)器上的資源到本地兩大功能

1. 請求文本

```csharp
//請求文本
GameFrameworkMode.GetModule<WebRequestManager>().RequestText("http://nothing.com/AssetVersion.txt");
```

2. 請求下載

```csharp

```

3. 事件監(jiān)聽

```csharp
//監(jiān)聽文本請求成功
GameFrameworkMode.GetModule<EventManager>().AddListener<HttpReadTextSuccessEventArgs>(OnHttpReadTextSuccess);
//文本請求失敗
GameFrameworkMode.GetModule<EventManager>().AddListener<HttpReadTextFaileEventArgs>(OnHttpReadTextFaile);
//文件下載成功
GameFrameworkMode.GetModule<EventManager>().AddListener<DownloadSuccessEventArgs>(OnDownloadSuccess);
//文件下載失敗
GameFrameworkMode.GetModule<EventManager>().AddListener<DownloadFaileEventArgs>(OnDownloadFaile);
//文件下載進度
?GameFrameworkMode.GetModule<EventManager>().AddListener<DownloadProgressEventArgs>(OnDownloadProgress);
```

--- ?

#### 七、音頻管理器模塊 `AudioManager` ?

統(tǒng)一的聲音播放管理，支持默認(rèn)的背景音樂、ui音效、其他音效已經(jīng)物體綁定的AudioSource多種模式，以下以播放ui音效為例

1. 添加ui音效音頻

```csharp
GameFrameworkMode.GetModule<AudioManager>().AddUISound("soundclip","Assets/Audio/UI/default.wav");
``` ?

2. 播放ui音效

```csharp
GameFrameworkMode.GetModule<AudioManager>().PlayUISound("soundclip","Assets/Audio/UI/default.wav");
```

3. 停止ui音效,默認(rèn)停止當(dāng)前正在播放的音頻

```csharp
GameFrameworkMode.GetModule<AudioManager>().StopUISound();
``` ?

4. 移除ui音效音頻

```csharp
GameFrameworkMode.GetModule<AudioManager>().RemoveUISound("Assets/Audio/UI/default.wav");
``` ?

--- ?

#### 八、本地化管理模塊 `LocalizationManager`

將配置文件中的本地化文件，讀取語言存為字典保存在`LocalizationManager`中，使用`LocalizationText`綁定在`UGUI`的`Text`組件上。
同時支持動態(tài)設(shè)置

```csharp
go.GetComponent<LocalizationText>().Text="GameName";
``` ?

---

#### 九、設(shè)置模塊 `SettingMangaer`

默認(rèn)封裝`PlayerPrefs`,使用方法類似。同時添加了`SetQuality`&`SetAllSoundVolume`&`SetBackgroundMusicVolume`&`SetUISoundVolume`&`SetSoundEffectVolume`等默認(rèn)的設(shè)置 ?
具體使用`GameFrameworkMode.GetModule<SettingMangaer>()`一目了然 ?

--- ?

#### 十、網(wǎng)絡(luò)模塊 `NetworkManager`

正在增加中，首先會封裝局域網(wǎng)內(nèi)的連接通信，互聯(lián)網(wǎng)后面增加。目前使用`kcp`將udp轉(zhuǎn)為可靠傳輸，傳輸協(xié)議使用`Protobuf`

---

### 內(nèi)置工具

---

#### 一、AssetBundle打包工具

* 打包工具兼容unity自身右下角的assetbundle的標(biāo)簽設(shè)計
* 工具欄在`Tools/AssetBundles Options`,快捷鍵為ctrl+shift+o
* 打包當(dāng)前平臺`Tools/Build AssetBundles`,快捷鍵為ctrl+shift+T
* 打包多個平臺`Tools/Build AssetBundles Targets`,快捷鍵為ctrl+shift+Y

二、Addressable打包工具
* 工具欄`AddressableMenu/...`,一鍵打包，一鍵增量打包
* 工具欄`Tools/Asset Management/...`

---

### 編輯器擴展

#### Game Module編輯擴展
* 繼承`ModuleEditorBase`
* 構(gòu)造函數(shù)同`ModuleEditorBase`
* 在類上添加標(biāo)記`CustomModuleEditor`

# HybridCLR 體驗項目

一個示例熱更新項目。

想了解更多，請加 QQ群:?

- HybridCLR c#熱更新 開發(fā)交流群：651188171
- HybridCLR 新手群：428404198

你可以使用發(fā)布的包來體驗HybridCLR熱更新功能。

**示例項目使用 Unity 2020.3.33(任意后綴子版本如f1、f1c1、f1c2都可以) 版本**，2019.4.x、2020.3.x、2021.3.x系列都可以，但為了避免新手無謂的出錯，盡量使用2020.3.33版本來體驗。

## 目錄介紹

- Assets Unity項目目錄
? - Main AOT主包模塊，對應(yīng)常規(guī)項目的主項目，資源更新模塊
? - 剩下代碼在默認(rèn)的全局Assembly-Csharp.dll中，均為熱更新腳本
- HybridCLRData 包含HybridCLR的il2cpp本地安裝目錄
- Packages/com.focus-creative-games/hybridclr_unity 為HybridCLR for Unity包。暫時先作為local package，成熟后做成獨立package。

## 使用介紹

HybridCLR為c++實現(xiàn)，只有打包后才可使用。日常開發(fā)在編輯器下，無需打包。

如何打包出一個可熱更新的包，請先參閱 [快速開始](https://focus-creative-games.github.io/hybridclr/start_up/)。

## 運行流程

本示例演示了如下幾部分內(nèi)容

- 將dll和資源打包成ab
- 熱更新腳本掛載到熱更新資源中，并且正常運行
- 直接反射運行普通熱更新函數(shù)App::Main

進入場景后，Main場景中的LoadDll會按順序加載StreamingAssets目錄下common AssetBundle里的Assembly-Csharp.dll。接著運行App::Main函數(shù)。

## 體驗熱更新

### 通用預(yù)備工作

**===> 安裝必須的Unity版本**

根據(jù)你所使用的Unity年度版本，**還需要額外**安裝2019.4.40、2020.3.33或者2021.3.1版本（必須包含il2cpp模塊），不限 f1、f1c1之類后綴。

**再次提醒** 當(dāng)前Unity版本必須安裝了 il2cpp 組件。如果未安裝，請自行在UnityHub中安裝。新手自行g(shù)oogle或百度。

**===> 安裝 visual studio**

要求必須安裝 `使用c++的游戲開發(fā)` 這個組件

**===> 安裝git**

### Unity版本相關(guān)特殊操作

**===> Unity 2021**

對于使用Unity 2021版本（2019、2020不需要）打包iOS平臺的開發(fā)者，由于HybridCLR需要裁減后的AOT dll，但Unity Editor未提供公開接口可以復(fù)制出target為iOS時的AOT dll，故必須使用修改后的UnityEditor.CoreModule.dll覆蓋Unity自帶的相應(yīng)文件。

具體操作為將 `HybridCLRData/ModifiedUnityAssemblies/2021.3.1/UnityEditor.CoreModule-{Win,Mac}.dll` 覆蓋 `{Editor安裝目錄}/Editor/Data/Managed/UnityEngine/UnityEditor.CoreModule`，具體覆蓋目錄有可能因為操作系統(tǒng)或者Unity版本而有不同。

**由于權(quán)限問題，該操作無法自動完成，需要你手動執(zhí)行。**

這個 UnityEditor.CoreModule.dll 每個Unity小版本都不相同，我們目前暫時只提供了2021.3.1版本，如需其他版本請自己手動制作，詳情請見 [修改UnityEditor.CoreModule.dll](https://focus-creative-games.github.io/hybridclr/modify_unity_dll/)

**===> Unity 2019**

為了支持2019，需要修改il2cpp生成的源碼，因此我們修改了2019版本的il2cpp.exe工具。故Installer的安裝過程多了一個額外步驟：將 `{package}/Data/ModifiedUnityAssemblies/2019.4.40/Unity.IL2CPP.dll` 復(fù)制到 `{package}/Data/LocalIl2CppData/il2cpp/build/deploy/net471/Unity.IL2CPP.dll`

**注意，該操作自動完成，不需要手動操作。**

### 配置

**===> 確保[com.focus-creative-games.hybridclr_unity](https://github.com/focus-creative-games/hybridclr_unity) package已經(jīng)正確安裝**

為了使用HybridCLR，需要安裝hybridclr_unity插件。 不熟悉從url安裝package的請看 [install from git](https://docs.unity3d.com/Manual/upm-ui-giturl.html)。

由于網(wǎng)絡(luò)原因，在unity中可能無法安裝成功。你可以先把 [com.focus-creative-games.hybridclr_unity](https://github.com/focus-creative-games/hybridclr_unity) clone或者下載到本地，然后再 [install from disk](https://docs.unity3d.com/Manual/upm-ui-local.html)

目前需要幾個配置文件

**===> HybridCLRGlobalSettings.asset**

HybridCLR全局配置，單例。 trial項目已經(jīng)創(chuàng)建。新項目請在 Unity Editor的 Project 窗口右鍵 `HybridCLR/GlobalSettings` 創(chuàng)建。

關(guān)鍵參數(shù)介紹：

- Enable。 是否開啟HybridCLR。
- HotUpdateAssmblyDefinitions。 以Assembly Definition形式存在的熱更新模塊。不能與下面的Hotfix Dlls重復(fù)指定模塊。
- HotUpdate Dlls。 以dll形式存在的熱更新模塊。不能與HotUpdateAssmblyDefinitions重復(fù)指定模塊。

**===> HotUpdateAssemblyManifest.asset**

包含了需要補充元數(shù)據(jù)的AOT assembly列表。這個字段原來在 HybridCLRGlobalSettings 中。

### 安裝及打包及熱更新測試

以Win64為例，其他平臺同理。

- 安裝HybridCLR (安裝HybridCLR的原理請看 [快速上手](https://focus-creative-games.github.io/hybridclr/start_up/) )
? ? - 點擊菜單 `HybridCLR/Installer...`，彈出安裝界面。
? ? - 如果安裝界面沒有錯誤或者警告，則說明il2cpp路徑設(shè)置正常，否則需要你手動選擇正確的il2cpp目錄
? ? - 點擊 install 按鈕完成安裝
- 打包主工程
??
? **請確保你已經(jīng)掌握了常規(guī)的il2cpp為backend的打包過程**

? **請確保你已經(jīng)在你電腦上對于一個未使用HybrildCLR的項目成功打包出il2cpp為backend的相應(yīng)包**，也就是打包環(huán)境是正常的！

打包前需要先在 Player Settings里作如下設(shè)置：
- script backend 必須選擇 il2cpp
- Api Compatibility Level 選擇 .NET 4.x（unity 2021 及之后版本這里顯示為 .NET framework）
- 關(guān)閉 增量式gc 選項 (incremental gc)

打包：
- 菜單 HybridCLR/Build/Win64 ，運行完成后，會在Release_Win64目錄下生成程序
- 運行Release_Win64/HybridCLRTrial.exe，會看到打出 hello, HybridCLR.prefab

更新ab包：
? - 修改HotFix項目的PrintHello代碼，比如改成打印 "hello,world"。
? - 運行菜單 HybridCLR/BuildBundles/Win64，重新生成ab
? - 將StreamingAssets下的ab包復(fù)制到Release_Win64\HybridCLRTrial_Data\StreamingAssets。
? - 再將運行，屏幕上會打印"hello,world"。

### HybridCLR相關(guān)Editor菜單介紹

- `Installer...` 打開 安裝器
- `GenerateLinkXml` 自動生成熱更新代碼所需的link.xml。
- `GenerateMethodBridge` 生成橋接函數(shù)
- `GenerateAOTGenericReference` 生成熱更新模塊中用到的AOT泛型實例化
- `GenerateReversePInvokeWrapper` 生成 MonoPInvokeCallbackAttribute的預(yù)留樁函數(shù)
- `GenerateAll` 生成以上所有 GenerateXXX
- `CompileDll` 編譯熱更新dll
- `BuildBundles` 構(gòu)建用于熱更資源和代碼的ab包
- `Build` 一鍵打包相關(guān)快捷命令

### 其他

剩下的體驗之旅，比如各種c#特性，自己體驗吧。