LuaInterface 技术说明文档

1. 类概述

LuaInterface 是一个静态类，作为 Unity 客户端中 C# 与 Lua 之间的桥梁，提供了丰富的接口供 Lua 脚本调用 C# 功能。该类使用 [LuaCallCSharp] 注解标记可被 Lua 调用的成员，实现了 C# 与 Lua 之间的双向通信、事件处理、UI 操作、游戏状态管理等功能。

2. 命名空间

Global

3. 类成员列表

4. 详细成员说明

4.1 AddLuaCallback

[LuaCallCSharp]
public static Guid AddLuaCallback(LuaFunction lua, SysEvent evt, object arg)

功能描述

向指定的系统事件添加一个 Lua 回调函数，当该事件触发时，将调用注册的 Lua 函数。

参数类型及说明

返回值类型及说明

使用示例

-- 监听背包变化事件
local callbackId = LuaInterface.AddLuaCallback(function(eventArg, arg)
    -- eventArg 包含背包变化的物品和变化类型
    -- arg 是注册时传递的额外参数
    print("背包发生变化", arg)
end, SysEvent.InventoryChangeEvent, "背包监听器")

注意事项

• 必须保存返回的 Guid，以便在不需要监听时使用 RemoveLuaCallback 移除回调，避免内存泄漏
• 回调函数的参数顺序固定：第一个参数是事件数据，第二个参数是注册时传递的额外参数

4.2 RemoveLuaCallback

[LuaCallCSharp]
public static void RemoveLuaCallback(SysEvent evt, Guid id)

功能描述

从指定的系统事件中移除一个已注册的 Lua 回调函数。

参数类型及说明

使用示例

-- 移除之前注册的背包变化事件回调
LuaInterface.RemoveLuaCallback(SysEvent.InventoryChangeEvent, callbackId)

注意事项

• 如果指定的 id 不存在于事件的回调列表中，该方法不会产生任何效果
• 调用此方法后，回调函数将不再被触发

4.3 GetUserPanel

[LuaCallCSharp]
public static double GetUserPanel(int panelID)

功能描述

获取用户面板数据，返回指定面板 ID 对应的数值。

参数类型及说明

返回值类型及说明

使用示例

-- 获取用户生命值
local health = LuaInterface.GetUserPanel(1)  -- 假设 1 是生命值面板 ID
print("当前生命值:", health)

注意事项

• 面板 ID 的具体含义由游戏逻辑定义，需要参考相关文档
• 确保传入有效的面板 ID，否则可能返回错误值

4.4 GetUserInfo

[LuaCallCSharp]
public static string GetUserInfo(int infoID)

功能描述

获取用户信息，返回指定信息 ID 对应的字符串值。

参数类型及说明

返回值类型及说明

使用示例

-- 获取用户名称
local userName = LuaInterface.GetUserInfo(0)  -- 假设 0 是用户名信息 ID
print("用户名:", userName)

注意事项

• 信息 ID 的具体含义由游戏逻辑定义，需要参考相关文档
• 确保传入有效的信息 ID，否则可能返回错误值

4.5 CallBackendLua

[LuaCallCSharp]
public static void CallBackendLua(string fileName, string functionName, string[] args)

功能描述

调用后端 Lua 函数，将请求发送到服务器执行指定的 Lua 函数。

参数类型及说明

使用示例

-- 调用后端 Lua 函数
local args = {"param1", "param2"}
LuaInterface.CallBackendLua("gameLogic.lua", "processGameEvent", args)

注意事项

• 后端必须存在指定的 Lua 文件和函数
• 参数数组中的元素必须都是字符串类型
• 该方法是异步调用，不会立即返回结果

4.6 SetGlobal

[LuaCallCSharp]
public static void SetGlobal(string key, Object value)

功能描述

设置全局变量，将指定的键值对存储在全局字典中，供后续使用。

参数类型及说明

使用示例

-- 设置全局变量
local myElement = someVisualElement
LuaInterface.SetGlobal("MyGlobalElement", myElement)

注意事项

• 只有 Unity 的 Object 类型或其子类可以存储为全局变量
• 重复设置相同的键会覆盖之前的值

4.7 GetGlobal

[LuaCallCSharp]
public static Object GetGlobal(string key)

功能描述

获取全局变量，根据指定的键名从全局字典中获取对应的值。

参数类型及说明

返回值类型及说明

使用示例

-- 获取全局变量
local myElement = LuaInterface.GetGlobal("MyGlobalElement")
if myElement then
    -- 使用获取到的元素
    myElement.visible = true
end

异常处理

• 如果指定的键不存在，可能会抛出异常，建议在使用前进行空值检查

注意事项

• 返回的值需要根据实际类型进行转换后使用

4.8 OpenWindow

[LuaCallCSharp]
public static void OpenWindow(string filePath, string windowName = "DefaultWindow")

功能描述

打开一个新窗口，从指定的文件路径加载 UI 元素并显示。

参数类型及说明

使用示例

-- 打开一个新窗口
LuaInterface.OpenWindow("UI/Windows/MyWindow.uxml", "MyCustomWindow")

注意事项

• 如果指定名称的窗口已存在，将先移除旧窗口再创建新窗口
• 窗口会被自动添加到全局变量中，可通过 GetGlobal(windowName) 获取

4.9 LoadXML

[LuaCallCSharp]
public static VisualElement LoadXML(string filePath)

功能描述

从指定的文件路径加载 XML 文件，并解析为 VisualElement 对象。

参数类型及说明

返回值类型及说明

使用示例

-- 加载 XML 文件
local element = LuaInterface.LoadXML("UI/Components/MyComponent.uxml")
-- 将元素添加到某个父容器中
parentElement:Add(element)

注意事项

• 确保指定的文件路径正确，否则可能返回 null
• 解析后的 VisualElement 需要手动添加到 UI 层级中才能显示

4.10 LoadXMLString

[LuaCallCSharp]
public static VisualElement LoadXMLString(string xmlString)

功能描述

将 XML 字符串解析为 VisualElement 对象。

参数类型及说明

返回值类型及说明

使用示例

-- 解析 XML 字符串
local xmlString = [[
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
    <ui:Label text="Hello World" />
</ui:UXML>]]
local element = LuaInterface.LoadXMLString(xmlString)

注意事项

• 确保 XML 字符串格式正确，否则可能返回 null 或抛出异常
• 解析后的 VisualElement 需要手动添加到 UI 层级中才能显示

4.11 LoadMainUI

[LuaCallCSharp]
public static VisualElement LoadMainUI(string filePath)

功能描述

加载主 UI，从指定的文件路径加载 UI 元素并设置为游戏的主 UI。

参数类型及说明

返回值类型及说明

使用示例

-- 加载主 UI
local mainUI = LuaInterface.LoadMainUI("UI/MainUI.uxml")

注意事项

• 此方法会替换当前的主 UI
• 加载的主 UI 会自动显示在游戏中

4.12 RemoveDialog

[LuaCallCSharp]
public static void RemoveDialog(VisualElement dialog)

功能描述

移除指定的对话框，将其从 UI 层级中移除。

参数类型及说明

使用示例

-- 移除对话框
local dialog = LuaInterface.GetGlobal("MyDialog")
if dialog then
    LuaInterface.RemoveDialog(dialog)
end

注意事项

• 确保传入的对话框元素确实存在于 UI 层级中
• 移除后，对话框将不再显示

4.13 NewMapRule

[LuaCallCSharp]
public static void NewMapRule(string key, string value)

功能描述

添加新的映射规则，将指定的键值对添加到资源管理器的映射规则中。

参数类型及说明

使用示例

-- 添加新的映射规则
LuaInterface.NewMapRule("Map1001", "rule1,rule2,rule3")

注意事项

• 映射规则的具体格式和用途由游戏逻辑定义
• 重复添加相同的键可能会覆盖之前的值

4.14 Restart

[LuaCallCSharp]
public static void Restart()

功能描述

重新开始游戏，注销当前用户并重新登录。

使用示例

-- 重新开始游戏
LuaInterface.Restart()

注意事项

• 此方法会中断当前游戏会话
• 会触发一系列网络请求，包括注销和重新登录

4.15 AutoPilotTo

[LuaCallCSharp]
public static void AutoPilotTo(int x, int y, LuaFunction onCancel, LuaFunction onComplete)

功能描述

自动导航到指定的坐标位置。

参数类型及说明

使用示例

-- 自动导航到指定坐标
LuaInterface.AutoPilotTo(100, 200, 
    function() print("导航已取消") end, 
    function() print("导航已完成") end)

注意事项

• 确保指定的坐标在当前地图范围内
• 导航过程中可能会被各种因素中断
• 回调函数是可选的，可以传入 nil

5. 系统事件类型（SysEvent）

LuaInterface 中使用的 SysEvent 枚举定义了以下系统事件：

6. 事件类型（EventType）

LuaInterface 中使用的 EventType 枚举定义了以下事件类型：

7. 最佳实践

1. 回调管理：始终保存 AddLuaCallback 返回的 Guid，并在适当的时候调用 RemoveLuaCallback 移除回调，避免内存泄漏。

2. 全局变量使用：谨慎使用全局变量，避免命名冲突，建议使用唯一的命名前缀。

3. UI 操作：在操作 UI 元素时，确保元素存在且已正确加载。

4. 错误处理：在调用可能抛出异常的方法时，使用 try-catch 块进行错误处理。

5. 性能考虑：避免频繁调用耗时的方法，如 LoadXML 和 LoadXMLString。

6. 异步调用：注意 CallBackendLua 等异步方法的使用，不要期望立即返回结果。

8. 版本历史

9. 联系方式

如有任何问题或建议，请联系开发团队。