CharacterVirtual.h

Go to the documentation of this file.

// Jolt Physics Library (https://github.com/jrouwe/JoltPhysics)
// SPDX-FileCopyrightText: 2021 Jorrit Rouwe
// SPDX-License-Identifier: MIT
 
#pragma once
 
#include <Jolt/Physics/Character/CharacterBase.h>
#include <Jolt/Physics/Body/MotionType.h>
#include <Jolt/Physics/Body/BodyFilter.h>
#include <Jolt/Physics/Collision/BroadPhase/BroadPhaseLayer.h>
#include <Jolt/Physics/Collision/ObjectLayer.h>
#include <Jolt/Core/STLTempAllocator.h>
 
JPH_NAMESPACE_BEGIN
 
class CharacterVirtual;
 
class JPH_EXPORT CharacterVirtualSettings : public CharacterBaseSettings
{
public:
    JPH_OVERRIDE_NEW_DELETE
 
    float                               mMass = 70.0f;
 
    float                               mMaxStrength = 100.0f;
 
    Vec3                                mShapeOffset = Vec3::sZero();
 
    EBackFaceMode                       mBackFaceMode = EBackFaceMode::CollideWithBackFaces;    
    float                               mPredictiveContactDistance = 0.1f;                      
    uint                                mMaxCollisionIterations = 5;                            
    uint                                mMaxConstraintIterations = 15;                          
    float                               mMinTimeRemaining = 1.0e-4f;                            
    float                               mCollisionTolerance = 1.0e-3f;                          
    float                               mCharacterPadding = 0.02f;                              
    uint                                mMaxNumHits = 256;                                      
    float                               mHitReductionCosMaxAngle = 0.999f;                      
    float                               mPenetrationRecoverySpeed = 1.0f;                       
};
 
class CharacterContactSettings
{
public:
    bool                                mCanPushCharacter = true;                               
    bool                                mCanReceiveImpulses = true;                             
};
 
class JPH_EXPORT CharacterContactListener
{
public:
    virtual                             ~CharacterContactListener() = default;
 
    virtual void                        OnAdjustBodyVelocity(const CharacterVirtual *inCharacter, const Body &inBody2, Vec3 &ioLinearVelocity, Vec3 &ioAngularVelocity) { /* Do nothing, the linear and angular velocity are already filled in */ }
 
    virtual bool                        OnContactValidate(const CharacterVirtual *inCharacter, const BodyID &inBodyID2, const SubShapeID &inSubShapeID2) { return true; }
 
    virtual void                        OnContactAdded(const CharacterVirtual *inCharacter, const BodyID &inBodyID2, const SubShapeID &inSubShapeID2, RVec3Arg inContactPosition, Vec3Arg inContactNormal, CharacterContactSettings &ioSettings) { /* Default do nothing */ }
 
    virtual void                        OnContactSolve(const CharacterVirtual *inCharacter, const BodyID &inBodyID2, const SubShapeID &inSubShapeID2, RVec3Arg inContactPosition, Vec3Arg inContactNormal, Vec3Arg inContactVelocity, const PhysicsMaterial *inContactMaterial, Vec3Arg inCharacterVelocity, Vec3 &ioNewCharacterVelocity) { /* Default do nothing */ }
};
 
class JPH_EXPORT CharacterVirtual : public CharacterBase
{
public:
    JPH_OVERRIDE_NEW_DELETE
 
                                        CharacterVirtual(const CharacterVirtualSettings *inSettings, RVec3Arg inPosition, QuatArg inRotation, uint64 inUserData, PhysicsSystem *inSystem);
 
                                        CharacterVirtual(const CharacterVirtualSettings *inSettings, RVec3Arg inPosition, QuatArg inRotation, PhysicsSystem *inSystem) : CharacterVirtual(inSettings, inPosition, inRotation, 0, inSystem) { }
 
    void                                SetListener(CharacterContactListener *inListener)       { mListener = inListener; }
 
    CharacterContactListener *          GetListener() const                                     { return mListener; }
 
    Vec3                                GetLinearVelocity() const                               { return mLinearVelocity; }
 
    void                                SetLinearVelocity(Vec3Arg inLinearVelocity)             { mLinearVelocity = inLinearVelocity; }
 
    RVec3                               GetPosition() const                                     { return mPosition; }
 
    void                                SetPosition(RVec3Arg inPosition)                        { mPosition = inPosition; }
 
    Quat                                GetRotation() const                                     { return mRotation; }
 
    void                                SetRotation(QuatArg inRotation)                         { mRotation = inRotation; }
 
    RMat44                              GetWorldTransform() const                               { return RMat44::sRotationTranslation(mRotation, mPosition); }
 
    RMat44                              GetCenterOfMassTransform() const                        { return GetCenterOfMassTransform(mPosition, mRotation, mShape); }
 
    float                               GetMass() const                                         { return mMass; }
    void                                SetMass(float inMass)                                   { mMass = inMass; }
 
    float                               GetMaxStrength() const                                  { return mMaxStrength; }
    void                                SetMaxStrength(float inMaxStrength)                     { mMaxStrength = inMaxStrength; }
 
    float                               GetPenetrationRecoverySpeed() const                     { return mPenetrationRecoverySpeed; }
    void                                SetPenetrationRecoverySpeed(float inSpeed)              { mPenetrationRecoverySpeed = inSpeed; }
 
    bool                                GetEnhancedInternalEdgeRemoval() const                  { return mEnhancedInternalEdgeRemoval; }
    void                                SetEnhancedInternalEdgeRemoval(bool inApply)            { mEnhancedInternalEdgeRemoval = inApply; }
 
    float                               GetCharacterPadding() const                             { return mCharacterPadding; }
 
    uint                                GetMaxNumHits() const                                   { return mMaxNumHits; }
    void                                SetMaxNumHits(uint inMaxHits)                           { mMaxNumHits = inMaxHits; }
 
    float                               GetHitReductionCosMaxAngle() const                      { return mHitReductionCosMaxAngle; }
    void                                SetHitReductionCosMaxAngle(float inCosMaxAngle)         { mHitReductionCosMaxAngle = inCosMaxAngle; }
 
    bool                                GetMaxHitsExceeded() const                              { return mMaxHitsExceeded; }
 
    Vec3                                GetShapeOffset() const                                  { return mShapeOffset; }
    void                                SetShapeOffset(Vec3Arg inShapeOffset)                   { mShapeOffset = inShapeOffset; }
 
    uint64                              GetUserData() const                                     { return mUserData; }
    void                                SetUserData(uint64 inUserData)                          { mUserData = inUserData; }
 
    Vec3                                CancelVelocityTowardsSteepSlopes(Vec3Arg inDesiredVelocity) const;
 
    void                                Update(float inDeltaTime, Vec3Arg inGravity, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    bool                                CanWalkStairs(Vec3Arg inLinearVelocity) const;
 
    bool                                WalkStairs(float inDeltaTime, Vec3Arg inStepUp, Vec3Arg inStepForward, Vec3Arg inStepForwardTest, Vec3Arg inStepDownExtra, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    bool                                StickToFloor(Vec3Arg inStepDown, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    struct ExtendedUpdateSettings
    {
        Vec3                            mStickToFloorStepDown { 0, -0.5f, 0 };                                  
        Vec3                            mWalkStairsStepUp { 0, 0.4f, 0 };                                       
        float                           mWalkStairsMinStepForward { 0.02f };                                    
        float                           mWalkStairsStepForwardTest { 0.15f };                                   
        float                           mWalkStairsCosAngleForwardContact { Cos(DegreesToRadians(75.0f)) };     
        Vec3                            mWalkStairsStepDownExtra { Vec3::sZero() };                             
    };
 
    void                                ExtendedUpdate(float inDeltaTime, Vec3Arg inGravity, const ExtendedUpdateSettings &inSettings, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    void                                RefreshContacts(const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    void                                UpdateGroundVelocity();
 
    bool                                SetShape(const Shape *inShape, float inMaxPenetrationDepth, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    void                                CheckCollision(RVec3Arg inPosition, QuatArg inRotation, Vec3Arg inMovementDirection, float inMaxSeparationDistance, const Shape *inShape, RVec3Arg inBaseOffset, CollideShapeCollector &ioCollector, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter) const;
 
    // Saving / restoring state for replay
    virtual void                        SaveState(StateRecorder &inStream) const override;
    virtual void                        RestoreState(StateRecorder &inStream) override;
 
#ifdef JPH_DEBUG_RENDERER
    static inline bool                  sDrawConstraints = false;                               
    static inline bool                  sDrawWalkStairs = false;                                
    static inline bool                  sDrawStickToFloor = false;                              
#endif
 
    // Encapsulates a collision contact
    struct Contact
    {
        // Saving / restoring state for replay
        void                            SaveState(StateRecorder &inStream) const;
        void                            RestoreState(StateRecorder &inStream);
 
        RVec3                           mPosition;                                              
        Vec3                            mLinearVelocity;                                        
        Vec3                            mContactNormal;                                         
        Vec3                            mSurfaceNormal;                                         
        float                           mDistance;                                              
        float                           mFraction;                                              
        BodyID                          mBodyB;                                                 
        SubShapeID                      mSubShapeIDB;                                           
        EMotionType                     mMotionTypeB;                                           
        bool                            mIsSensorB;                                             
        uint64                          mUserData;                                              
        const PhysicsMaterial *         mMaterial;                                              
        bool                            mHadCollision = false;                                  
        bool                            mWasDiscarded = false;                                  
        bool                            mCanPushCharacter = true;                               
    };
 
    using TempContactList = Array<Contact, STLTempAllocator<Contact>>;
    using ContactList = Array<Contact>;
 
    const ContactList &                 GetActiveContacts() const                               { return mActiveContacts; }
 
private:
    // Sorting predicate for making contact order deterministic
    struct ContactOrderingPredicate
    {
        inline bool                     operator () (const Contact &inLHS, const Contact &inRHS) const
        {
            if (inLHS.mBodyB != inRHS.mBodyB)
                return inLHS.mBodyB < inRHS.mBodyB;
 
            return inLHS.mSubShapeIDB.GetValue() < inRHS.mSubShapeIDB.GetValue();
        }
    };
 
    // A contact that needs to be ignored
    struct IgnoredContact
    {
                                        IgnoredContact() = default;
                                        IgnoredContact(const BodyID &inBodyID, const SubShapeID &inSubShapeID) : mBodyID(inBodyID), mSubShapeID(inSubShapeID) { }
 
        BodyID                          mBodyID;                                                
        SubShapeID                      mSubShapeID;                                            
    };
 
    using IgnoredContactList = Array<IgnoredContact, STLTempAllocator<IgnoredContact>>;
 
    // A constraint that limits the movement of the character
    struct Constraint
    {
        Contact *                       mContact;                                               
        float                           mTOI;                                                   
        float                           mProjectedVelocity;                                     
        Vec3                            mLinearVelocity;                                        
        Plane                           mPlane;                                                 
        bool                            mIsSteepSlope = false;                                  
    };
 
    using ConstraintList = Array<Constraint, STLTempAllocator<Constraint>>;
 
    // Collision collector that collects hits for CollideShape
    class ContactCollector : public CollideShapeCollector
    {
    public:
                                        ContactCollector(PhysicsSystem *inSystem, const CharacterVirtual *inCharacter, uint inMaxHits, float inHitReductionCosMaxAngle, Vec3Arg inUp, RVec3Arg inBaseOffset, TempContactList &outContacts) : mBaseOffset(inBaseOffset), mUp(inUp), mSystem(inSystem), mCharacter(inCharacter), mContacts(outContacts), mMaxHits(inMaxHits), mHitReductionCosMaxAngle(inHitReductionCosMaxAngle) { }
 
        virtual void                    AddHit(const CollideShapeResult &inResult) override;
 
        RVec3                           mBaseOffset;
        Vec3                            mUp;
        PhysicsSystem *                 mSystem;
        const CharacterVirtual *        mCharacter;
        TempContactList &               mContacts;
        uint                            mMaxHits;
        float                           mHitReductionCosMaxAngle;
        bool                            mMaxHitsExceeded = false;
    };
 
    // A collision collector that collects hits for CastShape
    class ContactCastCollector : public CastShapeCollector
    {
    public:
                                        ContactCastCollector(PhysicsSystem *inSystem, const CharacterVirtual *inCharacter, Vec3Arg inDisplacement, Vec3Arg inUp, const IgnoredContactList &inIgnoredContacts, RVec3Arg inBaseOffset, Contact &outContact) : mBaseOffset(inBaseOffset), mDisplacement(inDisplacement), mUp(inUp), mSystem(inSystem), mCharacter(inCharacter), mIgnoredContacts(inIgnoredContacts), mContact(outContact) { }
 
        virtual void                    AddHit(const ShapeCastResult &inResult) override;
 
        RVec3                           mBaseOffset;
        Vec3                            mDisplacement;
        Vec3                            mUp;
        PhysicsSystem *                 mSystem;
        const CharacterVirtual *        mCharacter;
        const IgnoredContactList &      mIgnoredContacts;
        Contact &                       mContact;
    };
 
    // Helper function to convert a Jolt collision result into a contact
    template <class taCollector>
    inline static void                  sFillContactProperties(const CharacterVirtual *inCharacter, Contact &outContact, const Body &inBody, Vec3Arg inUp, RVec3Arg inBaseOffset, const taCollector &inCollector, const CollideShapeResult &inResult);
 
    // Move the shape from ioPosition and try to displace it by inVelocity * inDeltaTime, this will try to slide the shape along the world geometry
    void                                MoveShape(RVec3 &ioPosition, Vec3Arg inVelocity, float inDeltaTime, ContactList *outActiveContacts, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator
    #ifdef JPH_DEBUG_RENDERER
        , bool inDrawConstraints = false
    #endif // JPH_DEBUG_RENDERER
        ) const;
 
    // Ask the callback if inContact is a valid contact point
    bool                                ValidateContact(const Contact &inContact) const;
 
    // Tests the shape for collision around inPosition
    void                                GetContactsAtPosition(RVec3Arg inPosition, Vec3Arg inMovementDirection, const Shape *inShape, TempContactList &outContacts, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter) const;
 
    // Remove penetrating contacts with the same body that have conflicting normals, leaving these will make the character mover get stuck
    void                                RemoveConflictingContacts(TempContactList &ioContacts, IgnoredContactList &outIgnoredContacts) const;
 
    // Convert contacts into constraints. The character is assumed to start at the origin and the constraints are planes around the origin that confine the movement of the character.
    void                                DetermineConstraints(TempContactList &inContacts, float inDeltaTime, ConstraintList &outConstraints) const;
 
    // Use the constraints to solve the displacement of the character. This will slide the character on the planes around the origin for as far as possible.
    void                                SolveConstraints(Vec3Arg inVelocity, float inDeltaTime, float inTimeRemaining, ConstraintList &ioConstraints, IgnoredContactList &ioIgnoredContacts, float &outTimeSimulated, Vec3 &outDisplacement, TempAllocator &inAllocator
    #ifdef JPH_DEBUG_RENDERER
        , bool inDrawConstraints = false
    #endif // JPH_DEBUG_RENDERER
        ) const;
 
    // Get the velocity of a body adjusted by the contact listener
    void                                GetAdjustedBodyVelocity(const Body& inBody, Vec3 &outLinearVelocity, Vec3 &outAngularVelocity) const;
 
    // Calculate the ground velocity of the character assuming it's standing on an object with specified linear and angular velocity and with specified center of mass.
    // Note that we don't just take the point velocity because a point on an object with angular velocity traces an arc,
    // so if you just take point velocity * delta time you get an error that accumulates over time
    Vec3                                CalculateCharacterGroundVelocity(RVec3Arg inCenterOfMass, Vec3Arg inLinearVelocity, Vec3Arg inAngularVelocity, float inDeltaTime) const;
 
    // Handle contact with physics object that we're colliding against
    bool                                HandleContact(Vec3Arg inVelocity, Constraint &ioConstraint, float inDeltaTime) const;
 
    // Does a swept test of the shape from inPosition with displacement inDisplacement, returns true if there was a collision
    bool                                GetFirstContactForSweep(RVec3Arg inPosition, Vec3Arg inDisplacement, Contact &outContact, const IgnoredContactList &inIgnoredContacts, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter) const;
 
    // Store contacts so that we have proper ground information
    void                                StoreActiveContacts(const TempContactList &inContacts, TempAllocator &inAllocator);
 
    // This function will determine which contacts are touching the character and will calculate the one that is supporting us
    void                                UpdateSupportingContact(bool inSkipContactVelocityCheck, TempAllocator &inAllocator);
 
    void                                MoveToContact(RVec3Arg inPosition, const Contact &inContact, const BroadPhaseLayerFilter &inBroadPhaseLayerFilter, const ObjectLayerFilter &inObjectLayerFilter, const BodyFilter &inBodyFilter, const ShapeFilter &inShapeFilter, TempAllocator &inAllocator);
 
    // This function returns the actual center of mass of the shape, not corrected for the character padding
    inline RMat44                       GetCenterOfMassTransform(RVec3Arg inPosition, QuatArg inRotation, const Shape *inShape) const
    {
        return RMat44::sRotationTranslation(inRotation, inPosition).PreTranslated(mShapeOffset + inShape->GetCenterOfMass()).PostTranslated(mCharacterPadding * mUp);
    }
 
    // Our main listener for contacts
    CharacterContactListener *          mListener = nullptr;
 
    // Movement settings
    EBackFaceMode                       mBackFaceMode;                                          // When colliding with back faces, the character will not be able to move through back facing triangles. Use this if you have triangles that need to collide on both sides.
    float                               mPredictiveContactDistance;                             // How far to scan outside of the shape for predictive contacts. A value of 0 will most likely cause the character to get stuck as it cannot properly calculate a sliding direction anymore. A value that's too high will cause ghost collisions.
    uint                                mMaxCollisionIterations;                                // Max amount of collision loops
    uint                                mMaxConstraintIterations;                               // How often to try stepping in the constraint solving
    float                               mMinTimeRemaining;                                      // Early out condition: If this much time is left to simulate we are done
    float                               mCollisionTolerance;                                    // How far we're willing to penetrate geometry
    float                               mCharacterPadding;                                      // How far we try to stay away from the geometry, this ensures that the sweep will hit as little as possible lowering the collision cost and reducing the risk of getting stuck
    uint                                mMaxNumHits;                                            // Max num hits to collect in order to avoid excess of contact points collection
    float                               mHitReductionCosMaxAngle;                               // 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.
    float                               mPenetrationRecoverySpeed;                              // This value governs how fast a penetration will be resolved, 0 = nothing is resolved, 1 = everything in one update
    bool                                mEnhancedInternalEdgeRemoval;                           // 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.
 
    // Character mass (kg)
    float                               mMass;
 
    // Maximum force with which the character can push other bodies (N)
    float                               mMaxStrength;
 
    // An extra offset applied to the shape in local space. This allows applying an extra offset to the shape in local space.
    Vec3                                mShapeOffset = Vec3::sZero();
 
    // Current position (of the base, not the center of mass)
    RVec3                               mPosition = RVec3::sZero();
 
    // Current rotation (of the base, not of the center of mass)
    Quat                                mRotation = Quat::sIdentity();
 
    // Current linear velocity
    Vec3                                mLinearVelocity = Vec3::sZero();
 
    // List of contacts that were active in the last frame
    ContactList                         mActiveContacts;
 
    // Remembers the delta time of the last update
    float                               mLastDeltaTime = 1.0f / 60.0f;
 
    // Remember if we exceeded the maximum number of hits and had to remove similar contacts
    mutable bool                        mMaxHitsExceeded = false;
 
    // User data, can be used for anything by the application
    uint64                              mUserData = 0;
};
 
JPH_NAMESPACE_END