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 providedlistener
is called with theCollision
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 providedlistener
is called with theCollision
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 providedlistener
is called with theCollision
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 providedlistener
is called with theCollision
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 providedlistener
is called with theCollision
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 providedlistener
is called with theCollision
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 providedlistener
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 providedlistener
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)