# LuaProUtil

**Repository Path**: PXY2333/lua-pro-util

## Basic Information

- **Project Name**: LuaProUtil
- **Description**: 一个基于XLua和Addressables的辅助工具，使用前请下载Addressables依赖
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


<div align="center">

<h1>
  <img src="https://img.shields.io/badge/LuaProUtil-unity-blue?style=flat-square&logo=unity" alt="LuaProUtil">
</h1>

<p>
  <b>🔥 基于 XLua & Addressables 的 Unity Lua 开发工具链 🔥</b>
</p>

<p>
  <a href="#依赖安装">依赖安装</a> ·
  <a href="#快速开始">快速开始</a> ·
  <a href="#功能特性">功能特性</a> ·
  <a href="#API文档">API</a>
</p>

<br>

</div>

---

## ⚙️ 依赖安装

使用 LuaProUtil 前需要安装以下依赖：

### 1. Addressables（必须）

1. 打开 Unity 菜单 `Window > Package Manager`
2. 点击左上角 `+` 按钮，选择 `Add package by name...`
3. 输入 `com.unity.addressables`，点击 Install
4. 安装完成后，打开 `Window > Asset Management > Addressables > Groups` 初始化 Addressables

### 2. XLua（必须）

确保项目中已导入 XLua 插件（本项目已包含在 `Assets/XLua/`）

---

## ✨ 功能特性

### 🐲 LuaMgr - Lua 环境管理器

- **单例模式**：继承自 `BaseMgr`，全局唯一实例
- **自定义加载器**：支持 Addressables 加载 Lua 脚本
- **全局库支持**：可配置 Global Head 脚本，自动执行初始化
- **生命周期管理**：安全的 Dispose 流程，避免回调泄露

### 📦 ABMgr - Addressables 资源管理器

- **资源加载**：异步加载任意类型资源，支持 Key + Label 组合
- **场景管理**：支持 Single/Additive 场景加载、卸载
- **缓存机制**：自动缓存已加载资源，避免重复加载
- **内存管理**：提供 Release、ReleaseAll 等释放接口

### 🎭 LuaBehaviour - Lua 脚本组件

- **拖拽绑定**：直接把 .lua 文件拖到 GameObject 上自动绑定
- **生命周期映射**：Awake/Start/Update/OnDestroy 等完整的 Unity 生命周期
- **开关控制**：可单独控制 Update/FixedUpdate/LateUpdate 是否执行
- **热重载**：支持运行时 Reload 脚本

### ⚙️ 编辑器工具

- **Lua 脚本创建器**：`Assets > Create > Lua 脚本` 一键创建带模板的 Lua 文件
- **Lua 拖拽绑定**：Hierarchy 窗口拖拽 .lua 文件到 GameObject 自动添加 LuaBehaviour
- **Lua 导入器**：自动识别 .lua 文件为 TextAsset

---

## 🚀 快速开始

### 1. 初始化 Lua 环境

在场景中创建一个 GameObject，挂载 `LuaMgr` 组件。可选配置 `Global Library` 字段设置全局初始化脚本。

### 2. 编写 Lua 脚本

右键 Project 窗口 `Create > Lua 脚本`，创建新脚本：

```lua
-- Example.lua
function Awake(go)
    print("Hello LuaProUtil! GameObject: " .. go.name)
end

function Start(go)
    print("Start called")
end

function Update(go)
    -- 每帧更新逻辑
end
```

### 3. 绑定到 GameObject

- **方式一**：把 `.lua` 文件直接拖拽到 Hierarchy 窗口的 GameObject 上
- **方式二**：手动添加 `LuaBehaviour` 组件，拖拽 Lua 文件到 `Lua File` 字段

### 4. 加载资源

```csharp
// 在 C# 中加载资源
AbMgr.Instance.LoadAsync<GameObject>("PlayerPrefab", "Prefabs", obj => {
    Instantiate(obj);
});

// 加载场景
AbMgr.Instance.LoadSceneSingleAsync("GameScene", "Scenes");
```

---

## 📖 API 文档

### LuaMgr

| 方法                                                    | 说明                                      |
| ------------------------------------------------------- | ----------------------------------------- |
| `DoLua(string keyName)`                                 | 通过 Addressables Key 加载并执行 Lua 脚本 |
| `DoLua(string keyName, string labelName)`               | 通过 Key + Label 加载 Lua 脚本            |
| `DoString(string luaCode, string chunkName = "LuaMgr")` | 直接执行 Lua 代码字符串                   |
| `DisposeLuaEnv()`                                       | 释放 Lua 环境                             |
| `ReInit()`                                              | 重新初始化 Lua 环境                       |
| `ClearLuaCache()`                                       | 清空 Lua 脚本缓存                         |

### ABMgr

| 方法                                                                                            | 说明               |
| ----------------------------------------------------------------------------------------------- | ------------------ |
| `LoadAsync<T>(string keyName, string labelName = null, Action<T> callback = null)`              | 异步加载资源       |
| `LoadSceneSingleAsync(string keyName, string labelName = null, Action<bool> callback = null)`   | 单场景模式加载     |
| `LoadSceneAdditiveAsync(string keyName, string labelName = null, Action<bool> callback = null)` | 附加模式加载场景   |
| `UnloadSceneAsync(string keyName, string labelName = null, Action<bool> callback = null)`       | 卸载场景           |
| `Release(UnityEngine.Object obj)`                                                               | 释放指定资源       |
| `ReleaseByKey(string keyName, string labelName = null)`                                         | 通过 Key 释放资源  |
| `ReleaseAll()`                                                                                  | 释放所有已加载资源 |

### LuaBehaviour (Lua API)

| 函数              | 说明                                          |
| ----------------- | --------------------------------------------- |
| `Awake(go)`       | 脚本实例化时调用                              |
| `OnEnable(go)`    | 对象启用时调用                                |
| `Start(go)`       | 第一帧 Update 前调用                          |
| `Update(go)`      | 每帧调用（需 enableUpdate = true）            |
| `FixedUpdate(go)` | 固定时间步调用（需 enableFixedUpdate = true） |
| `LateUpdate(go)`  | Update 后调用（需 enableLateUpdate = true）   |
| `OnDisable(go)`   | 对象禁用时调用                                |
| `OnDestroy(go)`   | 对象销毁时调用                                |

---

## 📁 目录结构

```
LuaProUtil/
├── Base/
│   └── BaseMgr.cs          # 单例基类
├── Runtime/
│   ├── LuaMgr.cs           # Lua 环境管理
│   ├── ABMgr.cs            # Addressables 资源管理
│   └── LuaBehaviour.cs     # Lua 脚本组件
├── Editor/
│   ├── LuaScriptCreator.cs # Lua 脚本创建器
│   ├── LuaDragToGameObject.cs  # 拖拽绑定工具
│   └── LuaImporter.cs      # Lua 文件导入器
└── GlobalLibary/
    └── GlobalHead.lua      # 全局库示例
```

---

<div align="center">
  <b>Made with ❤️ for Unity Developers</b>
</div>