Character update

The character controller update happens at two different points in the frame, and is executed by the combination of a character aspect (KinematicCharacterAspect) and a character processor (IKinematicCharacterProcessor).

Update groups

Two system groups are available as sensible defaults where character update logic should be executed:

• KinematicCharacterPhysicsUpdateGroup: updates at a fixed timestep, after the physics update. This is where the character physics update should take place (detecting ground, assigning a velocity, detecting movement collisions, etc...).
• KinematicCharacterVariableUpdateGroup: updates every frame, after the fixed update and before transforms. This is the best place to update the character rotation, because it will be perfectly in sync with rendering, and will therefore result in a rotation that feels more responsive.

Keep in mind, however, that updating characters as part of these groups is merely a suggestion; not a requirement. For example: if you wanted to, you could choose to update character rotation as part of the KinematicCharacterPhysicsUpdateGroup instead of the KinematicCharacterVariableUpdateGroup, and interpolate character rotation between the fixed updates.

The character aspect

The KinematicCharacterAspect holds all the data required for character updates, and contains methods for major character update steps and utilities.

These are the main steps for a typical character update, available in KinematicCharacterAspect:

Method	Description
Update_Initialize	Clears and initializes core character data and buffers at the start of the update.
Update_ParentMovement	Moves the character based on its assigned ParentEntity, if any.
Update_Grounding	Detects character grounding.
Update_PreventGroundingFromFutureSlopeChange	Cancels a character's grounded status based on the definitions in the BasicStepAndSlopeHandlingParameters given to the method. For example, cancel grounding if the character is heading towards a ledge.
Update_GroundPushing	Applies a constant force to the current ground entity, if the entity is dynamic.
Update_MovementAndDecollisions	Moves the character with its velocity and solves collisions.
Update_MovingPlatformDetection	Detects valid moving platform entities, and assigns them as the character's ParentEntity. For more information, see the documentation on Parenting.
Update_ParentMomentum	Preserves the velocity momentum when a character is detached from a parent body.
Update_ProcessStatefulCharacterHits	Fills the StatefulKinematicCharacterHit buffer on the character entity with character hits that have an Enter, Exit, or Stay state.

The standard characters that come with the package already take care of calling these in the correct order and at the correct time, in order to solve character physics.

The KinematicCharacterAspect also contains various methods for querying the world with the character's shape and collision filtering. For example:

• CastColliderClosestCollisions
• CastColliderAllCollisions
• RaycastClosestCollisions
• RaycastAllCollisions
• CalculateDistanceClosestCollisions
• CalculateDistanceAllCollisions

The character processor

The character processor is a user-implemented aspect that implements the IKinematicCharacterProcessor interface. It serves two main purposes:

• Provide a way to customize the logic executed by the update steps of the KinematicCharacterAspect.
• Provide a way for users to define additional components that can be accessed during the character updates.

In the standard characters, an initial version of this processor aspect is already created, and it is meant to be customized by users. Both the fixed character physics update and the character variable update use this processor aspect in order to gain access to all of the data and methods that they could require.

The character processor is able to customize the logic executed by the update steps of the KinematicCharacterAspect by passing itself as a parameter to these functions, which in turn call functions on the character processor. In these "callbacks", users can modify the default implementation to suit their needs. In summary, systems will schedule jobs iterating on the processor aspect implementing IKinematicCharacterProcessor, which will then call character update steps in the KinematicCharacterAspect, which will then call back to functions of IKinematicCharacterProcessor.

The following character processor methods can be used to customize character logic. For full descriptions of each of these methods see the IKinematicCharacterProcessor API documentation:

Method	Description
UpdateGroundingUp	Updates the up direction that a character compares slope normals with. You must write this direction to KinematicCharacterBody.GroundingUp.
CanCollideWithHit	Checks if the character can collide with a hit. Returns true if the character can collide, and false otherwise.
OnMovementHit	Determines what happens when the character collider casts have detected a hit during the movement iterations. By default, this should call KinematicCharacterAspect.Default_OnMovementHit.
IsGroundedOnHit	Determines if the character is grounded on the hit or not. By default, it calla KinematicCharacterAspect.Default_IsGroundedOnHit, which checks the slope angle and velocity direction to determine the final result.
OverrideDynamicHitMasses	Modifies the mass ratios between the character and another dynamic body when they collide. This is only called for characters that have KinematicCharacterProperties.SimulateDynamicBody set to true. You can leave this method empty if you don't want to modify the mass ratio.
ProjectVelocityOnHits	Determines how the character velocity gets projected on hits, based on all hits so far this frame. By default, you should call KinematicCharacterAspect.Default_ProjectVelocityOnHits here. You shouldn't need to change this callback, unless you want to make your character bounce on certain surfaces, for example.