README.md · Nomat/LunLuaFramework

# lun-framework框架

`lun-framework`是基于tolua的Unity热更新框架，通过使用Lua脚本组件替代C#脚本组件的方式实现热更新。因此使用此框架在开发流程上不会有改变，非常适合于习惯C#脚本组件开发流程的开发者使用此框架实现游戏的热更新功能。同样也可以把完成后的游戏通过替换脚本的方式渐进实现热更新，如此不用把所有C#脚本替换为Lua脚本就可以一步一步调试运行，避免代码修改过多造成调试困难。

实例项目； 
[Unity官方Tanks项目热更新重写](https://gitee.com/nomat/unity-game-tanks) 
[lun-framework框架功能示例](https://gitee.com/nomat/lun-framework-examples)

## 开发者须知

1. 由于框架基于`tolua`实现，因此开发者应该比较熟悉`Lua`语言。并且最好对`tolua`的类绑定有一定了解，毕竟在开发过程中可能会添加新类以便在`Lua`中进行操作。

## 框架安装配置流程

### 1、把框架`lun-framework-client`目录和`tolua`的`Plugins`目录放到项目`Assets`目录下
        框架目录内的文件除非有特殊需求，一般不需要更改。
        tolua的Plugins目录，可以在Demo或者例子工程中找到。

### 2、在`Resources`目录（如果没有自行创建）下右键选择`Create -> CreateLunLuaConfig`创建配置资源文件`LunLuaConfig.asset`，点击文件打开检查器并配置。
![avatar](./docs/images/createframeworkconfig.png)
![avatar](./docs/images/frameworkconfiginspector.png)

* `ToLua生成路径` 为`tolua`绑定文件生成目录，默认为`ToLuaGenerate`，也可以修改在`Assets`目录下，框架目录外的任意位置。
* `启用AssetBundle` 仅表示在编辑器中使用真实的AssetBundle，所以需要确保在`StreamingAssets`目录中存在`AssetBundles`，一般用于游戏开发完成后在编辑器中测试热更新使用。**提示：框架发布后就是用这种方式使用资源**
* `启用AssetBundle模拟` 仅表示在编辑器中使用`AssetLabel`加载资源。一般在构建`AssetBundles`后，就会自动配置所有资源配置路径内资源的`AssetLabel`。这个选项可以用于在编辑器中模拟其他目录内的`AssetLabel`资源。
* `启用资源配置路径` 表示在编辑器中直接使用资源配置路径表中的资源。一般在开发的时候使用这种资源使用模式。
* `资源配置路径表` 在编辑器中表示资源的搜索路径表，每个配置目录类似Unity中的Resources目录，通过路径加载资源。同时在构建`AssetBundles`时，资源配置路径表中所有的文件都会自动设置`AssetLabel`，并且同目录中的所有资源设置为同一资源包，因此每个场景文件需要分开放在单独目录中。

### 3、在顶部菜单栏中选择`LunLua -> ToLua -> Generate All`生成`tolua`绑定文件，生成的文件放在配置的`ToLua生成路径`目录内。
![avatar](./docs/images/genluawarps.png) 
如果需要添加新绑定类，可以在`Editor`目录（如果没有自行创建）内添加`ToLuaSettings.cs`，并且根据下面的示例编辑；
```
 using System.Collections;
 using System.Collections.Generic;
 using UnityEngine;

namespace LuaEditor
 {
 public static partial class ToLuaSettings
 {
 static ToLuaSettings()
 {
 // 添加代理绑定
 //customDelegateList.Add(_DT(typeof(System.Action<int,int>)));

// 添加绑定类型
                //customTypeList.Add(_GT(typeof(ParticleSystem.MainModule)));

// 添加类成员过滤（不生成此成员绑定）
                //memberFilter.Add("MeshRenderer.receiveGI");

// 添加不需要绑定的类
                //dropType.Add(typeof(Plane));
            }
        }
    }
```
然后依次点击`Clear warp files`和`Generate All`重新生成所有绑定文件。

## 框架使用流程

### 1、添加资源配置路径
在开始使用前，请确保`资源配置路径表`中配置了工作路径。配置的路径中的资源和Lua代码才能热更新

### 2、LuaMonoBehaviour组件检查器说明
`LuaMonoBehaviour`组件被设计成可以替换其他C#脚本组件，所以检查器面板功能相似。具体如下实例说明；
![avatar](./docs/images/luacomponentinspector.png)

* `使用主引擎` 框架支持多引擎，但是一般使用主引擎就可以。
* `Lua组件模块` 对应Lua代码中的组件实现文件`require`路径，在编辑器中可以拖动对应的Lua文件到此处以自动设置。
* `启用Update` 由于效率问题所以Update类函数，是在Lua端实现的。只有启用Update Lua实现组件才会回调`Update()`
* `启用LateUpdate` 同上
* `启用FixedUpdate` 同上
* `变量绑定` 可以绑定数值、字符串、布尔值、对象、游戏对象，组件、颜色、向量和LayerMask等到Lua实现组件里面，通过变量名称直接调用。 
1、 如果绑定的变量是`LuaMonoBehaviour`组件，则对应在Lua实现组件里面绑定是该`LuaMonoBehaviour`组件对应的Lua实现组件实例。说明这两个组件在Lua里面可以直接调用（需要在相同引擎中）。 
2、如果想绑定复杂数据类型，可以通过修饰变量名称实现。 例如数组；
 ```
 数组类型使用 名称#序号

变量名称 var#1 -> 123
        变量名称 var#2 -> "test"

在Lua实现组件里面使用

self.var -> [ 123, "test" ]
    ```
    例如对象；
    ```
        对象类型使用 名称.成员

变量名称 var.t1 -> 123
        变量名称 var.t2 -> "test"

在Lua实现组件里面使用
        
        self.var -> { t1 = 123, t2 = "test" }
    ```
    例如更复杂对象或数组；
    ```
        变量名称 var#1.t -> 123
        变量名称 var#2.t -> "test"

在Lua实现组件里面使用

self.var -> [ { t = 123 }, { t = "test" } ]
    ```
    更复杂的对象可以自己尝试组合

对比下面的C#实现的组件，面板上的功能基本一致。
![avatar](./docs/images/cscomponentinspector.png)

### 3、LuaMonoBehaviour组件对应的Lua实现说明
`LuaMonoBehaviour`组件在Lua中都应该有对应的实现，也就是`Lua组件模块`所对应的文件。 
例如下面`Scripts/Managers/GameManager`组件模块所对应的文件内容；
```
 local GameManager = class("GameManager", require("unity.LuaMonoBehaviour"))

function GameManager:Start()
        self:SpawnAllTanks()
        self:SetCameraTargets()
        coroutine.start(function()
            self:GameLoop()
        end)
    end

...

return GameManager
```
`unity.LuaMonoBehaviour`是Lua实现组件的基类，`class`是框架中模拟类的函数。`Start()`等生命周期函数和C#组件中的一致。 
对比下面的C#实现的组件，基本一致。
```
public class GameManager : MonoBehaviour
{
 private void Start()
 {
 // Lua有更方便的协程处理方式，这里在Lua中不需要
 m_StartWait = new WaitForSeconds(m_StartDelay);
 m_EndWait = new WaitForSeconds(m_EndDelay);

SpawnAllTanks();
        SetCameraTargets();

StartCoroutine(GameLoop());
 }
 ...
}
```
框架中的协程实现如下，基本完全可以替代C#的协程使用；

* `coroutine.start(fn)` 使用指定函数启动协程。
* `coroutine.sleep(time)` 在协程中等待指定时间。
* `coroutine.step(frame)` 在协程中等待指定帧数。
* `coroutine.waitasync(ao)` 在协程中等待异步操作完成。
* `coroutine.waituntil(fn)` 在协程中等待直到fn函数返回true。

可以在`lun-framework-client/Source/Lua`中查看源码，了解更多功能。

### 4、框架Lua中资源检查更新与加载释放
框架Lua使用`AssetManager`管理资源，通过`local assetManager = require("unity.AssetManager")`引入。资源管理器有如下功能；
* `检查更新` 通过调用`assetManager:CheckUpdateAsync(remoteURL)`或者`assetManager:CheckUpdate(remoteURL)`完成。 
特别注意：`AssetManager`中的函数通常有两种实现方式，以后缀`Async`表示的异步实现和没有后缀表示的同步实现。特别注意`Async`异步实现需要在协程中调用。例如;
 ```
 coroutine.start(function()
 local result = assetManager:CheckUpdateAsync("http://localhost/AssetBundles/PC/")
 if result then
 print("需要更新")
 end
 end)
 ```

* `更新资源` 通过调用`assetManager:UpdateAssetsAsync(OnProgress, OnMessage)`或者`assetManager:UpdateAssets(OnProgress, OnMessage)`完成。

* `加载场景` 通过调用`assetManager:LoadSceneAsync(assetPath, isAdditive)`或者`assetManager:LoadScene( assetPath, isAdditive)`完成。 `assetPath`表示资源路径，类似Resources.Load使用方式。 
特别注意`assetPath`路径中的目录解析为`assetBundleName`，文件解析为`assetName`。

* `加载资源` 通过调用`assetManager:LoadAssetAsync(assetPath)`或者`assetManager:LoadAsset(assetPath)`完成。也可以通过`assetManager:LoadAssetsAsync(assetPaths)`或者`assetManager:LoadAssets(assetPaths)`加载多个资源。

* `卸载资源包` 通过调用`assetManager:UnloadAssetBundle(assetBundleName, unloadObjects)`完成。但是只能卸载通过加载场景或者资源触发的资源包。

Nomat/LunLuaFramework

简介

发行版

贡献者

近期动态

Nomat/LunLuaFramework .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Nomat/LunLuaFramework