MonoBehaviour Event Functions

Event Components

There are some special event functions for users to implement on MonoBehaviours, Yahaha provides predefined event components for listerning to the events. Below shows the event components and the corresponding APIs, with examples to use them.

PhysicsEventListener

Methods

• RegisterCollisionEnter(Action<UnityEngine.Collision> listener)

  Registers a listener for the CollisionEnter event on the current GameObject. This event is triggered when the collider or rigidbody of the GameObject begins to make contact with another collider or rigidbody. The provided listener is called with the Collision information when the event occurs.

• UnregisterCollisionEnter(Action<UnityEngine.Collision> listener)

  Unregisters a previously registered listener for the CollisionEnter event. This stops the listener from being called when the event occurs.

• RegisterCollisionStay(Action<UnityEngine.Collision> listener)

  Registers a listener for the CollisionStay event on the current GameObject. This event triggers every frame while the collider or rigidbody is in contact with another collider or rigidbody. The provided listener is called with the Collision information for each frame the collision persists.|

• UnregisterCollisionStay(Action<UnityEngine.Collision> listener)

  Unregisters a previously registered listener for the CollisionStay event, preventing the listener from being invoked during ongoing collisions.

• RegisterCollisionExit(Action<UnityEngine.Collision> listener)

  Registers a listener for the CollisionExit event on the current GameObject. This event is triggered when the collider or rigidbody stops making contact with another collider or rigidbody. The provided listener is called with the Collision information at the moment the contact ends.

• UnregisterCollisionExit(Action<UnityEngine.Collision> listener)

  Unregisters a previously registered listener for the CollisionExit event, stopping the listener from being called when the collision ends.

• RegisterTriggerEnter(Action<UnityEngine.Collision> listener)

  Registers a listener for the TriggerEnter event on the current GameObject. This event is triggered when the collider of the GameObject enters a trigger collider attached to another GameObject. The provided listener is called with the Collision information at the moment of entry.

• UnregisterTriggerEnter(Action<UnityEngine.Collision> listener)

  Unregisters a previously registered listener for the TriggerEnter event, preventing the listener from being invoked when the GameObject enters a trigger.

• RegisterTriggerStay(Action<UnityEngine.Collision> listener)

  Registers a listener for the TriggerStay event on the current GameObject. This event is called once per physics update while the collider is inside a trigger collider. The provided listener is called with the Collision information for each frame the trigger condition is met.

• UnregisterTriggerStay(Action<UnityEngine.Collision> listener)

  Unregisters a previously registered listener for the TriggerStay event, stopping the listener from being called while the GameObject remains within the trigger.

• RegisterTriggerExit(Action<UnityEngine.Collision> listener)

  Registers a listener for the TriggerExit event on the current GameObject. This event is triggered when the collider exits a trigger collider attached to another GameObject. The provided listener is called with the Collision information at the moment of exit.

• UnregisterTriggerExit(Action<UnityEngine.Collision> listener)

  Unregisters a previously registered listener for the TriggerExit event, preventing the listener from being invoked when the GameObject exits the trigger.

Example

local PhysicsEventListenerType = typeof(PhysicsEventListener)

--Attempt to get PhysicsEventListener
local success,component = gameObject:TryGetComponent(PhysicsEventListenerType ,nil)
if not success then
    component = gameObject:AddComponent(PhysicsEventListenerType )
end

local function OnTriggerEnter(collision)
    print("On Trigger Enter:".. collision.gameObject.name)
end

component:RegisterTriggerEnter(OnTriggerEnter)

AnimatorEventListener

Methods

• RegisterOnAnimatorMove(Action listener)

  Registers a listener for the OnAnimatorMove event on the Animator component. This event is a callback for processing animation movements, allowing you to modify the root motion of the animated GameObject. When the event is triggered, the provided listener will be called to apply any necessary adjustments.

• UnregisterOnAnimatorMove(Action listener)

  Unregisters a previously registered listener for the OnAnimatorMove event, stopping the listener from being invoked when the animator processes movement updates.

• RegisterOnAnimatorIKEvent(Action<int> listener)

  Registers a listener for the OnAnimatorIK event on the Animator component. This event serves as a callback for setting up animation Inverse Kinematics (IK). When this event is triggered, the provided listener will be called with an integer parameter representing the layer index of the IK setup, allowing for customized IK adjustments.

• UnregisterOnAnimatorIKEvent(Action<int> listener)

  Unregisters a previously registered listener for the OnAnimatorIK event, preventing the listener from being called when the animator processes IK adjustments.

Example

local AnimatorEventListenerType = typeof(AnimatorEventListener)

--Attempt to get AnimatorEventListener
local success,component = gameObject:TryGetComponent(AnimatorEventListenerType ,nil)
if not success then
    component = gameObject:AddComponent(AnimatorEventListenerType )
end

local function OnAnimatorMove()
    local success,animator = gameObject:TryGetComponent(typeof(UnityEngine.Animator),nil)
    if success then
        print("Animator move:"..tostring(animator.deltaPosition))
    end
end

component:RegisterOnAnimatorMove(OnAnimatorMove)

CharacterControllerEventListener

Methods

• RegisterControllerColliderHit(Action<UnityEngine.ControllerColliderHit> listener)

  Registers a listener for the ControllerColliderHit event on the current GameObject. This event is called when the character controller collides with a collider while performing a movement operation (using the Move method). The provided listener will be invoked with the ControllerColliderHit information, allowing you to handle collision responses or interactions.

• UnregisterControllerColliderHit(Action<UnityEngine.ControllerColliderHit> listener)

  Unregisters a previously registered listener for the ControllerColliderHit event, preventing the listener from being called when the character controller makes contact with a collider during movement.

Example

local PhysicsEventListenerType = typeof(CharacterControllerEventListener)

-- Attempt to get CharacterControllerEventListener
local success,component = gameObject:TryGetComponent(PhysicsEventListenerType ,nil)
if not success then
    component = gameObject:AddComponent(PhysicsEventListenerType )
end

local function ControllerColliderHit(controllerColliderHit)
    print("On Controller Collider Hit:".. controllerColliderHit.collider.gameObject.name)
end

component:RegisterControllerColliderHit(ControllerColliderHit)

Helper APIs

Yahaha also provides builtin helper APIs for easier access to the events.

YaPhysicAPI

Methods

--- Registers a callback function to be called when a collision occurs in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a collision occurs.
--- @return function A function to stop listening for collision events.
function YaPhysicsAPI.OnCollisionEnter(obj, func) end

--- Registers a callback function to be called when a collision persists in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a collision persists.
--- @return function A function to stop listening for collision events.
function YaPhysicsAPI.OnCollisionStay(obj, func) end

--- Registers a callback function to be called when a collision ends in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a collision ends.
--- @return function A function to stop listening for collision events.
function YaPhysicsAPI.OnCollisionExit(obj, func) end

--- Registers a callback function to be called when a trigger event occurs in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a trigger event occurs.
--- @return function A function to stop listening for trigger events.
function YaPhysicsAPI.OnTriggerEnter(obj, func) end

--- Registers a callback function to be called when a trigger event persists in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a trigger event persists.
--- @return function A function to stop listening for trigger events.
function YaPhysicsAPI.OnTriggerStay(obj, func) end

--- Registers a callback function to be called when a trigger event ends in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a trigger event ends.
--- @return function A function to stop listening for trigger events.
function YaPhysicsAPI.OnTriggerExit(obj, func) end

--- Registers a callback function to be called when a controller collision occurs in the physics system.
--- @param obj any The component or GameObject to be monitored.
--- @param func function The function to be triggered when a controller collision occurs.
--- @return function A function to stop listening for controller collision events.
function YaPhysicsAPI.OnControllerColliderHit(obj, func) end

Example

local function OnTriggerEnter(collision)
    print("On Trigger Enter:".. collision.gameObject.name)
end

local cancelFunc = YaPhysicsAPI.OnTriggerEnter(script.gameObject,OnTriggerEnter)

script.OnDispose(function()
    cancelFunc()
end)

YaAnimatorAPI

Methods

---Registers a callback function to be called when processing animation movements for modifying root motion.
---@param obj Animator The animator to be monitored.
---@param func function The function to be triggered.
---@return function A function to stop listening.
function YaAnimator.OnAnimatorMove(obj, func) end


---Registers a callback function to be called when  setting up animation IK (inverse kinematics).
---@param obj Animator The Animator to be monitored.
---@param func function The function to be triggered.
---@return function A function to stop listening.
function YaAnimator.OnAnimatorIK(obj, func) end

Example

local function OnAnimatorMove()
    local success,animator = gameObject:TryGetComponent(typeof(UnityEngine.Animator),nil)
    if success then
        print("Animator move:"..tostring(animator.deltaPosition))
    end
end

local cancelFunc = YaAnimator.OnAnimatorMove(OnAnimatorMove)

script.OnDispose(function()
    cancelFunc()
end)