Skip to content

组件函数

组件上的API函数名及描述如下:

序号函数名函数描述
1GetGameObject(...)获取该组件挂载的对象实例
2GetGameObjectId(...)获取组件挂载的对象实例id
3IsValid(...)获取组件是否有效
4AddComponent(...)在组件所在的对象上添加指定组件
5RemoveComponent(...)删除在组件所在的对象上的指定组件
6GetComponent(...)获取组件所在对象上的指定组件
7PushCustomEvent(...)发送自定义消息(异步)
8PushCustomEventSync(...)发送自定义消息(同步)
9AddCustomEvent(...)监听自定义消息(广播)
10RemoveCustomEvent(...)移除自定义事件监听
11AddTriggerEvent(...)添加触发事件
12RemoveTriggerEvent(...)移除触发事件监听
13PushEvent(...)发送对象事件(异步)
14PushEventSync(...)发送对象事件(同步)
15AddEvent(...)监听对象事件
16RemoveEvent(...)移除对象的事件监听
17DoTaskInTime(...)启动定时器在指定时间执行任务
18DoPeriodicTask(...)启动定时器周期性执行任务
19ClearAllTask(...)清除所有定时器任务
20SetEventIsEnable(...)设置是否启用事件
21ThreadWork(...)启动新协程
22ThreadWait(...)线程等待

GetGameObject

  • 参数及类型:
  • 返回值及类型:
    • ret:GameObject 挂载对象
  • 该方法的主要作用: 获取该组件挂载的对象实例
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()
        -- 该组件挂载的对象实例
        local object = self:GetGameObject()

        -- 可以使用 object 直接操作对象
        -- 例如:给对象打上标签
        object:AddTag("这是恐龙类型")
        
    end
    
    return Script

GetGameObjectId

  • 参数及类型:
  • 返回值及类型:
    • ret:GameObject 挂载对象
  • 该方法的主要作用: 获取组件挂载的对象实例id
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()
        -- 该组件挂载的对象实例
        --ui 获取的是ui的工程id, 方块获取的是方块的类型id, 其他类型获取的是对象的实例id
        local id = self:GetGameObjectId()
        
    end
    
    return Script

IsValid

  • 参数及类型:
  • 返回值及类型:
  • 该方法的主要作用: 获取组件是否有效
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()
        
        local isValid = self:IsValid()

        if isValid then
            print("组件有效")
        else
            print("组件无效")
        end

        -- 操作缓存的其他组件的,需要先判断组件是否有效,避免相关组件被销毁后,操作无效
        if self.otherCmp and self.otherCmp:IsValid() then
            self.otherCmp:DoSomething()
        end
        
    end
    
    return Script

AddComponent

  • 参数及类型:
  • 返回值及类型:
    • ret:component 组件对象
  • 该方法的主要作用:在组件所在的对象上添加指定组件(对象已经存在相同id组件的则添加不上)
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 获取组件 
        local cmp = self:AddComponent("组件id")

        if cmp then
            print("组件添加成功")
            cmp:DoSomething()
        else
            print("组件添加失败")
        end
    end
    
    return Script

RemoveComponent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:删除在组件所在的对象上的指定组件
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 删除组件 
        self:RemoveComponent("组件id")

    end
    
    return Script

GetComponent

  • 参数及类型:
  • 返回值及类型:
    • ret:component 组件对象
  • 该方法的主要作用:获取组件所在对象上的指定组件
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 添加组件 
        local cmp = self:GetComponent("组件id")

        if cmp then
            print("获取到组件")
            cmp:DoSomething()
        else
            print("获取组件失败")
        end
    end
    
    return Script

PushCustomEvent

  • 参数及类型:
    • string 消息id
    • 多个基本数据类型 消息内容
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:发送自定义消息(异步)
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 发送自定义消息 id为 消息id, 3个参数:"消息参数1", 100, true
        self:PushCustomEvent("消息id", "消息参数1", 100, true)

        -- 自定义消息id 使用触发器的广播id 则触发器也能收到消息,
        -- 参数类型需要跟触发器广播的定义对应上
    end
    
    return Script

PushCustomEventSync

  • 参数及类型:
    • string 消息id
    • 多个基本数据类型 消息内容
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:发送自定义消息(同步)
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 发送自定义消息 id为 消息id, 3个参数:"消息参数1", 100, true
        self:PushCustomEventSync("消息id", "消息参数1", 100, true)
        
        -- 自定义消息id 使用触发器的广播id 则触发器也能收到消息, 
        --参数类型需要跟触发器广播的定义对应上
    end
    
    return Script

AddCustomEvent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:监听自定义消息(广播)
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 第一种写法
        -- 自定义消息id 使用触发器的广播id 则触发器发送的消息会触发回调函数
        self:AddCustomEvent("消息id", self.OnCustomEvent)

        -- 第二种写法
        self:AddCustomEvent("消息id", function(cmp,eventId, param1, param2, param3)
            print("收到自定义消息", eventId, param1, param2, param3)
        end)
        
    end

    
    function Script:OnCustomEvent(eventId, param1, param2, param3)
        -- 假如广播发了3个参数, 1,2,3
        -- 则param1, param2, param3 的值分别为 1, 2, 3
        print("收到自定义消息", eventId, param1, param2, param3)
    end
    
    return Script

RemoveCustomEvent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:移除自定义事件监听
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 删除组件中监听的自定义消息(删除该组件全部 "消息id" 的监听)
        self:RemoveCustomEvent("消息id") 
    end
    
    return Script

AddTriggerEvent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:添加触发事件(该函数只在ui跟世界类型组件有效)可以监听的事件列表参考触发器事件管理
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()
        -- 添加点击方块事件
        self:AddTriggerEvent(TriggerEvent.PlayerClickBlock, self.OnPlayerClickBlock)
    end

    function Script:OnPlayerClickBlock(event)
        -- event.blockid 事件中的方块类型
        -- event.x 事件中的x坐标
        -- event.y 事件中的y坐标
        -- event.z 事件中的z坐标
        print("玩家点击方块")
    end
    
    return Script

RemoveTriggerEvent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:移除触发事件监听
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()
        -- 删除组件中监听点击方块事件
        self:RemoveTriggerEvent(TriggerEvent.PlayerClickBlock) 
    end
    
    return Script

PushEvent

  • 参数及类型:
    • string 自定义事件类型
    • 多个基本数据类型 事件内容
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:发送对象事件(异步), 只有同个对象上监听的组件才能收到事件
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 发送自定义消息 id为 自定义事件类型, 3个参数:"参数1", 100, true
        self:PushEvent("自定义事件类型1", "参数1", 100, true)
    end
    
    return Script

PushEventSync

  • 参数及类型:
    • string 自定义事件类型
    • 多个基本数据类型 消息内容
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:发送对象事件(同步), 只有同个对象上监听的组件才能收到事件
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 发送自定义消息 id为 自定义事件类型, 3个参数:"参数1", 100, true
        self:PushEventSync("自定义事件类型1", "参数1", 100, true)
    end
    
    return Script

AddEvent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:监听对象事件(可以监听自定义的,也能监听官方内置对象事件)可以监听的事件列表参考组件事件管理
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 监听此对象收到伤害事件
        self:AddEvent(ObjectEvent.ObjectBeHurt, self.OnObjectBeHurt)

        -- 监听对象自定义事件
        self:AddEvent("自定义事件类型1", self.OnEvent)

    end
    
    function Script:OnObjectBeHurt(event)
        print("此对象(玩家/生物)受到伤害")
    end

    function Script:OnEvent(event)    
        print("收到自定义事件")
    end
    
    return Script

RemoveEvent

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:移除对象的事件监听
  • 具体使用案例如下:
lua
    local Script = {}

    function Script:OnStart()

        self:RemoveEvent(ObjectEvent.ObjectBeHurt) 

    end
    
    return Script

DoTaskInTime

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:启动定时器在指定时间执行任务
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 10秒后执行回调函数
        local task = self:DoTaskInTime(self.OnTime, 10)

        --task:Pause()    -- 暂停定时器
        --task:Resume()   -- 恢复定时器
        --task:Cancel()   -- 取消定时器
    end
    
    function Script:OnTime()
        print("10秒后执行")
    end

    return Script

DoPeriodicTask

  • 参数及类型:
    • function 回调函数
    • number 间隔时间(秒)
    • number 延迟开始第一次执行时间(默认0)
    • number 执行次数(默认无限次)
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:启动定时器周期性执行任务
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 每10秒执行一次
        local task = self:DoPeriodicTask(self.OnTask, 10)

        --task:Pause()    -- 暂停定时器
        --task:Resume()   -- 恢复定时器
        --task:Cancel()   -- 取消定时器
    end
    
    function Script:OnTask()
        print("10秒执行一次")
    end

    return Script

ClearAllTask

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:清除所有定时器任务
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()

        -- 清除所有定时器任务
        self:ClearAllTask()

    end
    
    return Script

SetEventIsEnable

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:设置是否启用事件
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()   

        self:AddTriggerEvent(TriggerEvent.PlayerClickBlock, self.OnPlayerClickBlock)

        -- 暂时不需要触发事件的,可以设置事件不会被触发, 也可以通过删除事件屏蔽
        self:SetEventIsEnable(self.OnPlayerClickBlock, false)

    end

    function Script:OnPlayerClickBlock(event)
        print("玩家点击方块")
    end
    
    
    return Script

ThreadWork

  • 参数及类型:
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:启动新协程
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()   

        -- 启动线程
        self:ThreadWork(function()
            print("线程启动")

        end)
    end
    
    return Script

ThreadWait

  • 参数及类型:
    • number 等待时间(默认一帧)
  • 返回值及类型:
    • ret: 无
  • 该方法的主要作用:启动新协程
  • 具体使用案例如下:
lua
    local Script = {}

    -- 组件启动时调用
    function Script:OnStart()   
        -- 等待1秒
        self:ThreadWait(1)
    end
    
    return Script