LuaFunction

---

描述

LuaFunction（函数类型）是一种可以存储和传递 Lua 函数的数据类型。它允许你将函数作为值来处理，就像处理数字、字符串或表一样。函数可以作为参数传递给其他函数，也可以作为返回值返回，这使得 LuaFunction 成为实现回调、事件处理和异步编程的重要工具。

在 MiniStudio 中，许多 API 方法使用 LuaFunction 作为回调参数，用于在特定事件发生时执行自定义代码。

---

创建函数引用

直接赋值

最简单的方式是将函数直接赋值给变量：

-- 定义一个函数
local function myFunction(x, y)
    return x + y
end

-- 将函数赋值给变量（此时变量持有函数引用）
local func = myFunction

-- 调用函数
local result = func(10, 20)
print(result)  -- 输出: 30

匿名函数

你也可以使用匿名函数（lambda 函数）：

-- 创建匿名函数并赋值给变量
local add = function(a, b)
    return a + b
end

-- 或者直接在调用中使用
local result = (function(x, y) return x * y end)(5, 3)
print(result)  -- 输出: 15

从方法获取函数

如果对象的方法需要作为回调传递，可以使用冒号（:）语法或点（.）语法：

local obj = SandboxNode.New("Model")

-- 方法一：使用点语法，需要手动传递 self
local methodFunc = function(...)
    return obj:SomeMethod(...)
end

-- 方法二：使用冒号语法（隐式 self）
local methodFunc = obj.SomeMethod  -- 注意：这种方式需要确保 self 正确绑定

---

作为参数传递

LuaFunction 最常见的用途是作为回调函数参数传递给 API 方法。

基本回调示例

-- 定义一个回调函数
local function onTextureUploaded(success)
    if success then
        print("纹理上传成功！")
    else
        print("纹理上传失败！")
    end
end

-- 将函数作为参数传递
worldService:UploadTexture(texture, "path/to/texture", "textureName", onTextureUploaded)

使用匿名函数作为回调

你也可以直接在调用时定义匿名函数：

worldService:UploadTexture(
    texture, 
    "path/to/texture", 
    "textureName",
    function(success)
        if success then
            print("上传成功")
        else
            print("上传失败")
        end
    end
)

事件绑定示例

许多服务使用 LuaFunction 来绑定事件处理：

-- 注册每帧执行的函数
local function onTick(deltaTime)
    print("每帧调用，时间间隔:", deltaTime)
end

-- 绑定到 Tick 事件
runService:BindToTickRegister("myTickKey", 1, onTick)

-- 也可以使用匿名函数
runService:BindToTickRegister("myTickKey2", 1, function(deltaTime)
    -- 每帧执行的代码
end)

---

回调函数的参数和返回值

接收参数的回调

根据不同的 API，回调函数可能接收不同数量和类型的参数：

-- 示例：回调函数接收一个参数
local function onComplete(result)
    print("操作完成，结果:", result)
end

someAPI:DoSomething(onComplete)

-- 示例：回调函数接收多个参数
local function onDataReceived(data1, data2, data3)
    print("收到数据:", data1, data2, data3)
end

someAPI:FetchData(onDataReceived)

处理返回值

某些回调可能需要在完成时返回特定值：

-- 回调函数可以返回布尔值表示操作是否成功
local function validateData(data)
    if data and #data > 0 then
        return true  -- 验证通过
    end
    return false  -- 验证失败
end

someAPI:ProcessData(data, validateData)

---

高级用法

函数工厂

你可以创建返回函数的函数（函数工厂）：

-- 创建一个工厂函数，返回一个计数器函数
local function createCounter(initialValue)
    local count = initialValue or 0
    return function()
        count = count + 1
        return count
    end
end

-- 创建两个独立的计数器
local counter1 = createCounter(0)
local counter2 = createCounter(100)

print(counter1())  -- 输出: 1
print(counter1())  -- 输出: 2
print(counter2())  -- 输出: 101
print(counter2())  -- 输出: 102

闭包和状态保持

函数可以访问创建它的作用域中的变量（闭包）：

local function createButton(name)
    local clickCount = 0  -- 局部变量，被闭包捕获
    
    local onClickHandler = function()
        clickCount = clickCount + 1
        print(name .. " 被点击了 " .. clickCount .. " 次")
    end
    
    return onClickHandler
end

local button1Click = createButton("按钮1")
local button2Click = createButton("按钮2")

button1Click()  -- 输出: 按钮1 被点击了 1 次
button1Click()  -- 输出: 按钮1 被点击了 2 次
button2Click()  -- 输出: 按钮2 被点击了 1 次

条件回调

可以根据条件动态选择不同的回调函数：

local function onSuccess()
    print("操作成功")
end

local function onFailure()
    print("操作失败")
end

-- 根据条件选择回调
local callback = condition and onSuccess or onFailure
someAPI:DoOperation(callback)

---

实际应用场景

异步操作回调

-- 上传资源的异步回调
local function handleUploadComplete(success, url)
    if success then
        print("资源已上传到:", url)
        -- 继续后续操作
    else
        print("上传失败，重试...")
    end
end

assetService:UploadAsset(assetData, handleUploadComplete)

定时器回调

-- 创建定时器回调
local function onTimerExpired()
    print("定时器已触发")
    -- 执行定时任务
end

timer:Start(5.0, onTimerExpired)  -- 5秒后触发

事件监听

-- 监听玩家进入区域事件
local function onPlayerEntered(player)
    print("玩家 " .. player.Name .. " 进入了区域")
end

area:OnPlayerEnter(onPlayerEntered)

条件检查回调

-- 数据验证回调
local function validateInput(input)
    if type(input) == "string" and #input > 0 then
        return true
    end
    return false
end

-- 使用验证函数
if validateInput(userInput) then
    processInput(userInput)
end

---

注意事项

函数引用的生命周期

当将函数作为 LuaFunction 传递时，需要注意函数的生命周期：

-- 正确：函数在作用域内保持有效
local function myCallback()
    print("回调执行")
end
api:Register(myCallback)  -- 函数引用被安全保存

-- 注意：局部变量可能在某些情况下失效
do
    local tempCallback = function() print("临时回调") end
    -- 如果 tempCallback 在 do 块外被调用，可能存在问题
end

Nil 检查和错误处理

在调用回调函数之前，建议检查函数是否为 nil：

local function safeCall(callback, ...)
    if callback and type(callback) == "function" then
        return callback(...)
    else
        print("警告：回调函数无效")
    end
end

safeCall(myCallback, arg1, arg2)

避免循环引用

在使用 LuaFunction 时，要注意避免创建循环引用，这可能导致内存泄漏：

-- 错误示例：可能导致内存泄漏
local function createHandler()
    local handler = function()
        -- 使用了 handler 自己，形成循环引用
        handler()  
    end
    return handler
end

---

总结

LuaFunction 是 MiniStudio Lua 编程中的重要数据类型，它提供了：

• 灵活性：函数可以作为值传递和存储
• 回调机制：实现异步操作和事件处理
• 代码复用：通过函数工厂和闭包实现代码复用
• 状态管理：闭包可以保持和访问外部状态

掌握 LuaFunction 的使用方法，能够帮助你编写更加灵活和强大的 Lua 脚本。