Character
Runtime character object. This object usually represents the player. Contrary to the Character class it doesn't use a rigid body but moves doing collision checks only (hence the name virtual). The advantage of this is that you can determine when the character moves in the frame (usually this has to happen at a very particular point in the frame) but the downside is that other objects don't see this virtual character. To make a CharacterVirtual visible to the simulation, you can optionally create an inner rigid body through CharacterVirtualSettings::mInnerBodyShape. A CharacterVirtual is not tracked by the PhysicsSystem so you need to update it yourself. This also means that a call to PhysicsSystem::SaveState will not save its state, you need to call CharacterVirtual::SaveState yourself.
C++ JPH::CharacterVirtual.
Constructors
Properties
Access to the internal list of contacts that the character has found. Note that only contacts that have their mHadCollision flag set are actual contacts.
Calculates the transform for this character's center of mass
Character padding
Get the character settings that can recreate this character
Set to indicate that extra effort should be made to try to remove ghost contacts (collisions with internal edges of a mesh). This is more expensive but makes bodies move smoother over a mesh with convex edges.
BodyID of the object the character is standing on. Note may have been removed!
Material that the character is standing on
Get the contact normal with the ground
Get the contact point with the ground
Current ground state
Sub part of the body that we're standing on.
User data value of the body that we're standing on
Velocity in world space of ground
Cos(angle) where angle is the maximum angle between two hits contact normals that are allowed to be merged during hit reduction. Default is around 2.5 degrees. Set to -1 to turn off.
The ID of this character
Optional inner rigid body that proxies the character in the world. Can be used to update body properties.
Returns true if the player is supported by normal or steep ground
Get the linear velocity of the character (m / s)
Get the current contact listener
Returns if we exceeded the maximum number of hits during the last collision check and had to discard hits based on distance. This can be used to find areas that have too complex geometry for the character to navigate properly. To solve you can either increase the max number of hits or simplify the geometry. Note that the character simulation will try to do its best to select the most relevant contacts to avoid the character from getting stuck.
Max num hits to collect in order to avoid excess of contact points collection
Maximum force with which the character can push other bodies (N)
This value governs how fast a penetration will be resolved, 0 = nothing is resolved, 1 = everything in one update
An extra offset applied to the shape in local space. This allows applying an extra offset to the shape in local space. Note that setting it on the fly can cause the shape to teleport into collision.
Get the transformed shape that represents the volume of the character, can be used for collision checks.
Calculate the world transform of the character
Functions
This function can be called prior to calling Update() to convert a desired velocity into a velocity that won't make the character move further onto steep slopes. This velocity can then be set on the character using SetLinearVelocity()
This function will return true if the character has moved into a slope that is too steep (e.g. a vertical wall). You would call WalkStairs to attempt to step up stairs.
Get all contacts for the character at a particular location. When colliding with another character virtual, this pointer will be provided through CollideShapeCollector::SetUserContext before adding a hit.
This function combines Update, StickToFloor and WalkStairs. This function serves as an example of how these functions could be combined. Before calling, call SetLinearVelocity to update the horizontal/vertical speed of the character, typically this is:
This call triggers contact removal callbacks and is used in conjunction with StartTrackingContactChanges.
Check if the character is currently in contact with or has collided with another body in the last operation (e.g. Update or WalkStairs)
Check if the character is currently in contact with or has collided with another character in the last time step (e.g. Update or WalkStairs)
Check if the normal of the ground surface is too steep to walk on
This function can be used after a character has teleported to determine the new contacts with the world.
Set the character vs character collision interface
Updates the shape of the inner rigid body. Should be called after a successful call to SetShape.
Set the maximum angle of slope that character can still walk on (radians)
Switch the shape of the character (e.g. for stance).
This function is internally called by Update, WalkStairs, StickToFloor and ExtendedUpdate and is responsible for tracking if contacts are added, persisted or removed. If you want to do multiple operations on a character (e.g. first Update then WalkStairs), you can surround the code with a StartTrackingContactChanges and FinishTrackingContactChanges pair to only receive a single callback per contact on the CharacterContactListener. If you don't do this then you could for example receive a contact added callback during the Update and a contact persisted callback during WalkStairs.
This function can be used to artificially keep the character to the floor. Normally when a character is on a small step and starts moving horizontally, the character will lose contact with the floor because the initial vertical velocity is zero while the horizontal velocity is quite high. To prevent the character from losing contact with the floor, we do an additional collision check downwards and if we find the floor within a certain distance, we project the character onto the floor.
This is the main update function. It moves the character according to its current velocity (the character is similar to a kinematic body in the sense that you set the velocity and the character will follow unless collision is blocking the way). Note it's your own responsibility to apply gravity to the character velocity! Different surface materials (like ice) can be emulated by getting the ground material and adjusting the velocity and/or the max slope angle accordingly every frame.
Use the ground body ID to get an updated estimate of the ground velocity. This function can be used if the ground body has moved / changed velocity and you want a new estimate of the ground velocity. It will not perform collision detection, so is less accurate than RefreshContacts but a lot faster.
When stair walking is needed, you can call the WalkStairs function to cast up, forward and down again to try to find a valid position