Module com.github.stephengold.joltjni
Package com.github.stephengold.joltjni

Class CharacterVirtualRef

java.lang.Object
com.github.stephengold.joltjni.JoltPhysicsObject
com.github.stephengold.joltjni.template.Ref
com.github.stephengold.joltjni.CharacterVirtualRef
All Implemented Interfaces:
ConstCharacterBase, ConstCharacterVirtual, ConstJoltPhysicsObject, AutoCloseable, Comparable<JoltPhysicsObject>
public final class CharacterVirtualRef extends Ref implements ConstCharacterVirtual
A counted reference to a CharacterVirtual. (native type: Ref<CharacterVirtual>)

  • Constructor Details

    • CharacterVirtualRef

      public CharacterVirtualRef()
      Instantiate an empty reference.

  • Method Details

    • extendedUpdate

      public void extendedUpdate(float deltaTime, Vec3Arg gravity, ExtendedUpdateSettings settings, BroadPhaseLayerFilter bpFilter, ObjectLayerFilter olFilter, BodyFilter bodyFilter, ShapeFilter shapeFilter, TempAllocator allocator)
      Apply a combination of Update, StickToFloor, and WalkStairs.
      Parameters:
      deltaTime - the time step to simulate
      gravity - the gravity acceleration vector (in meters per second squared, not null, unaffected)
      settings - settings to use (not null, unaffected)
      bpFilter - to test whether the character collides with a broad-phase layer (not null, unaffected)
      olFilter - to test whether the character collides with an object layer (not null, unaffected)
      bodyFilter - to test whether the character collides with a body (not null, unaffected)
      shapeFilter - to test whether the character collides with a shape (not null, unaffected)
      allocator - for temporary allocations (not null)

    • restoreState

      public void restoreState(StateRecorder recorder)
      Restore the character's state from the specified recorder.
      Parameters:
      recorder - the recorder to restore from (not null)

    • setLinearVelocity

      public void setLinearVelocity(float vx, float vy, float vz)
      Alter the character's linear velocity.
      Parameters:
      vx - the X component of the desired velocity (in meters per second, default=0)
      vy - the Y component of the desired velocity (in meters per second, default=0)
      vz - the Z component of the desired velocity (in meters per second, default=0)

    • setLinearVelocity

      public void setLinearVelocity(Vec3Arg velocity)
      Alter the character's linear velocity.
      Parameters:
      velocity - the desired velocity vector (meters per second in system coordinates, default=(0,0,0))

    • setPosition

      public void setPosition(RVec3Arg location)
      Relocate the character.
      Parameters:
      location - the desired location (in system coordinates, default=(0,0,0))

    • setRotation

      public void setRotation(QuatArg orientation)
      Re-orient the character.
      Parameters:
      orientation - the desired orientation (in system coordinates, default=(0,0,0,1))

    • setShape

      public boolean setShape(ConstShape shape, float maxPenetrationDepth, BroadPhaseLayerFilter broadPhaseLayerFilter, ObjectLayerFilter objectLayerFilter, BodyFilter bodyFilter, ShapeFilter shapeFilter, TempAllocator allocator)
      Alter the character's shape.
      Parameters:
      shape - the desired shape (not null)
      maxPenetrationDepth - the maximum acceptable penetration after the alteration, or Float.MAX_VALUE to skip the check
      broadPhaseLayerFilter - the broadphase filter used to test for collisions (not null)
      objectLayerFilter - the object-layer filter used to test for collisions (not null)
      bodyFilter - the body filter used to test for collisions (not null)
      shapeFilter - the shape filter used to test for collisions (not null)
      allocator - the desired allocator (not null)
      Returns:
      true if successful, otherwise false

    • setInnerBodyShape

      public void setInnerBodyShape(ConstShape shape)
      Alter the shape of the inner body. Invoke this after a successful invocation of setShape().
      Parameters:
      shape - the desired shape (not null, unaffected, default=?)

    • setUp

      public void setUp(Vec3Arg up)
      Alter the character's "up" direction.
      Parameters:
      up - the desired direction (not null, unaffected, default=(0,1,0))

    • updateGroundVelocity

      public void updateGroundVelocity()
      Update the estimated ground velocity.

    • cancelVelocityTowardsSteepSlopes

      public Vec3 cancelVelocityTowardsSteepSlopes(Vec3Arg desiredVelocity)
      Convert the specified velocity to one that won't climb steep slopes. The character is unaffected.
      Specified by:
      cancelVelocityTowardsSteepSlopes in interface ConstCharacterVirtual
      Parameters:
      desiredVelocity - velocity vector (in system coordinates, not null, unaffected)
      Returns:
      a new velocity vector (in system coordinates)

    • canWalkStairs

      public boolean canWalkStairs(Vec3Arg desiredVelocity)
      Test whether the character has moved onto a steep slope. The character is unaffected.
      Specified by:
      canWalkStairs in interface ConstCharacterVirtual
      Parameters:
      desiredVelocity - velocity vector (in system coordinates, not null, unaffected)
      Returns:
      true if too step to walk, otherwise false

    • getActiveContacts

      public ConstContact[] getActiveContacts()
      Copy the list of active contacts. The character is unaffected.
      Specified by:
      getActiveContacts in interface ConstCharacterVirtual
      Returns:
      a new array of new objects

    • getCenterOfMassPosition

      public RVec3 getCenterOfMassPosition()
      Calculate the location of the character's center of mass. The character is unaffected.
      Specified by:
      getCenterOfMassPosition in interface ConstCharacterVirtual
      Returns:
      a new location vector (in system coordinates)

    • getCenterOfMassTransform

      public RMat44 getCenterOfMassTransform()
      Calculate the local-to-system transform of the character's center of mass. The character is unaffected.
      Specified by:
      getCenterOfMassTransform in interface ConstCharacterVirtual
      Returns:
      a new coordinate transform matrix

    • getCharacterPadding

      public float getCharacterPadding()
      Return the thickness of the character's padding. The character is unaffected.
      Specified by:
      getCharacterPadding in interface ConstCharacterVirtual
      Returns:
      the thickness (in meters)

    • getCharacterVirtualSettings

      public CharacterVirtualSettings getCharacterVirtualSettings()
      Generate settings to reconstruct the character. The character is unaffected.
      Specified by:
      getCharacterVirtualSettings in interface ConstCharacterVirtual
      Returns:
      a new object

    • getCosMaxSlopeAngle

      public float getCosMaxSlopeAngle()
      Return the maximum slope the character can walk on. The character is unaffected.
      Specified by:
      getCosMaxSlopeAngle in interface ConstCharacterBase
      Returns:
      the cosine of the slope angle

    • getEnhancedInternalEdgeRemoval

      public boolean getEnhancedInternalEdgeRemoval()
      Test whether enhanced internal edge removal is enabled. The character is unaffected.
      Specified by:
      getEnhancedInternalEdgeRemoval in interface ConstCharacterVirtual
      Returns:
      true if enabled, otherwise false

    • getGroundBodyId

      public int getGroundBodyId()
      Return the body ID of the supporting surface. The character is unaffected.
      Specified by:
      getGroundBodyId in interface ConstCharacterBase
      Returns:
      the BodyID value

    • getGroundMaterial

      public ConstPhysicsMaterial getGroundMaterial()
      Access the material of the supporting surface. The character is unaffected.
      Specified by:
      getGroundMaterial in interface ConstCharacterBase
      Returns:
      a new JVM object with the pre-existing native object assigned, or else null

    • getGroundNormal

      public Vec3 getGroundNormal()
      Copy the normal direction at the point of contact with the supporting surface. The character is unaffected.
      Specified by:
      getGroundNormal in interface ConstCharacterBase
      Returns:
      a new direction vector (in system coordinates)

    • getGroundPosition

      public RVec3 getGroundPosition()
      Copy the location of the point of contact with the supporting surface. The character is unaffected.
      Specified by:
      getGroundPosition in interface ConstCharacterBase
      Returns:
      a new location vector (in system coordinates)

    • getGroundState

      public EGroundState getGroundState()
      Return the relationship between the character and its supporting surface. The character is unaffected.
      Specified by:
      getGroundState in interface ConstCharacterBase
      Returns:
      an enum value (not null)

    • getGroundSubShapeId

      public int getGroundSubShapeId()
      Identify the face on the supporting surface where contact is occurring. The character is unaffected.
      Specified by:
      getGroundSubShapeId in interface ConstCharacterBase
      Returns:
      a SubShapeID value

    • getGroundUserData

      public long getGroundUserData()
      Return the user data of the supporting surface. The character is unaffected.
      Specified by:
      getGroundUserData in interface ConstCharacterBase
      Returns:
      the 64-bit value

    • getGroundVelocity

      public Vec3 getGroundVelocity()
      Copy the world-space velocity of the supporting surface. The character is unaffected.
      Specified by:
      getGroundVelocity in interface ConstCharacterBase
      Returns:
      a new velocity vector (meters per second in system coordinates)

    • getHitReductionCosMaxAngle

      public float getHitReductionCosMaxAngle()
      Return the maximum angle for merging during hit reduction. The character is unaffected.
      Specified by:
      getHitReductionCosMaxAngle in interface ConstCharacterVirtual
      Returns:
      the cosine of the maximum angle, or -1 if hit reduction is disabled

    • getId

      public int getId()
      Return the character's ID. The character is unaffected. (native function: GetID)
      Specified by:
      getId in interface ConstCharacterVirtual
      Returns:
      a CharacterId value

    • getInnerBodyId

      public int getInnerBodyId()
      Return the ID of the inner body. The character is unaffected. (native function: GetInnerBodyID)
      Specified by:
      getInnerBodyId in interface ConstCharacterVirtual
      Returns:
      the BodyID value

    • getLinearVelocity

      public Vec3 getLinearVelocity()
      Copy the linear velocity of the character. The character is unaffected.
      Specified by:
      getLinearVelocity in interface ConstCharacterVirtual
      Returns:
      a new velocity vector (meters per second in system coordinates)

    • getMass

      public float getMass()
      Return the character's mass. The character is unaffected.
      Specified by:
      getMass in interface ConstCharacterVirtual
      Returns:
      the mass (in kilograms)

    • getMaxHitsExceeded

      public boolean getMaxHitsExceeded()
      Test whether the last collision check discarded one or more hits. The character is unaffected.
      Specified by:
      getMaxHitsExceeded in interface ConstCharacterVirtual
      Returns:
      true if discarded hits, otherwise false

    • getMaxNumHits

      public int getMaxNumHits()
      Return the maximum number of hits to be collected. The character is unaffected.
      Specified by:
      getMaxNumHits in interface ConstCharacterVirtual
      Returns:
      the limit (≥0)

    • getMaxStrength

      public float getMaxStrength()
      Return the maximum force applied to other bodies. The character is unaffected.
      Specified by:
      getMaxStrength in interface ConstCharacterVirtual
      Returns:
      the force (in Newtons)

    • getPenetrationRecoverySpeed

      public float getPenetrationRecoverySpeed()
      Return how quickly penetration is resolved. The character is unaffected.
      Specified by:
      getPenetrationRecoverySpeed in interface ConstCharacterVirtual
      Returns:
      the resolution fraction (0=never resolved, 1=all in one update)

    • getPosition

      public RVec3 getPosition()
      Copy the location of the character. The character is unaffected.
      Specified by:
      getPosition in interface ConstCharacterVirtual
      Returns:
      a new location vector (in system coordinates)

    • getPositionAndRotation

      public void getPositionAndRotation(RVec3 storeLocation, Quat storeOrientation)
      Copy the position of the character. The character is unaffected.
      Specified by:
      getPositionAndRotation in interface ConstCharacterVirtual
      Parameters:
      storeLocation - storage for the location (in system coordinates, not null, modified)
      storeOrientation - storage for the orientation (in system coordinates, not null, modified)

    • getRefCount

      public int getRefCount()
      Count the active references to the native CharacterVirtual. The settings are unaffected.
      Specified by:
      getRefCount in interface ConstCharacterBase
      Returns:
      the count (≥0)

    • getRotation

      public Quat getRotation()
      Copy the orientation of the character. The character is unaffected.
      Specified by:
      getRotation in interface ConstCharacterVirtual
      Returns:
      a new rotation quaternion (in system coordinates)

    • getShape

      public ConstShape getShape()
      Access the character's shape. The character is unaffected.
      Specified by:
      getShape in interface ConstCharacterBase
      Returns:
      a new immutable JVM object with the pre-existing native object assigned, or null if none

    • getShape

      public void getShape(ShapeRefC storeRef)
      Update the specified counted reference to refer to the character's shape. The character is unaffected.
      Specified by:
      getShape in interface ConstCharacterBase
      Parameters:
      storeRef - storage for the reference (not null, modified)

    • getShapeOffset

      public Vec3 getShapeOffset()
      Copy the local offset applied to the shape. The character is unaffected.
      Specified by:
      getShapeOffset in interface ConstCharacterVirtual
      Returns:
      a new offset vector (in local coordinates)

    • getTransformedShape

      public TransformedShape getTransformedShape()
      Generate a TransformedShape that represents the volume occupied by the character. The character is unaffected.
      Specified by:
      getTransformedShape in interface ConstCharacterVirtual
      Returns:
      a new object

    • getUp

      public Vec3 getUp()
      Copy the character's "up" direction. The character is unaffected.
      Specified by:
      getUp in interface ConstCharacterBase
      Returns:
      a new direction vector

    • getUserData

      public long getUserData()
      Return the character's user data: can be used for anything. The character is unaffected.
      Specified by:
      getUserData in interface ConstCharacterVirtual
      Returns:
      the value

    • getWorldTransform

      public RMat44 getWorldTransform()
      Calculate the character's local-to-system coordinate transform. The character is unaffected.
      Specified by:
      getWorldTransform in interface ConstCharacterVirtual
      Returns:
      a new transform matrix

    • hasCollidedWith

      public boolean hasCollidedWith(int bodyId)
      Test whether the character is in contact with or collided with the specified body during the previous time step. The character is unaffected.
      Specified by:
      hasCollidedWith in interface ConstCharacterVirtual
      Parameters:
      bodyId - the ID of the body to test against
      Returns:
      true if contact or collision, otherwise false

    • hasCollidedWith

      public boolean hasCollidedWith(ConstCharacterVirtual otherCharacter)
      Test whether the character is in contact with or has collided with the specified character during the previous time step. The current character is unaffected.
      Specified by:
      hasCollidedWith in interface ConstCharacterVirtual
      Parameters:
      otherCharacter - the character to test against (not null, unaffected)
      Returns:
      true if contact or collision, otherwise false

    • isSlopeTooSteep

      public boolean isSlopeTooSteep(Vec3Arg normal)
      Test whether the specified normal direction is too steep. The character is unaffected.
      Specified by:
      isSlopeTooSteep in interface ConstCharacterBase
      Parameters:
      normal - the surface normal to test (not null, unaffected)
      Returns:
      true if too steep, otherwise false

    • isSupported

      public boolean isSupported()
      Test whether the character is supported. The character is unaffected.
      Specified by:
      isSupported in interface ConstCharacterBase
      Returns:
      true if supported, otherwise false

    • saveState

      public void saveState(StateRecorder recorder)
      Save the character's state to the specified recorder. The character is unaffected.
      Specified by:
      saveState in interface ConstCharacterBase
      Parameters:
      recorder - the recorder to save to (not null)

    • toRefC

      public CharacterVirtualRefC toRefC()
      Create another counted reference to the native CharacterVirtual.
      Specified by:
      toRefC in interface ConstCharacterVirtual
      Returns:
      a new JVM object with a new native object assigned

    • getPtr

      public CharacterVirtual getPtr()
      Temporarily access the referenced CharacterVirtual.
      Specified by:
      getPtr in class Ref
      Returns:
      a new JVM object with the pre-existing native object assigned

    • targetVa

      public long targetVa()
      Return the address of the native CharacterVirtual. No objects are affected.
      Specified by:
      targetVa in interface ConstJoltPhysicsObject
      Overrides:
      targetVa in class JoltPhysicsObject
      Returns:
      a virtual address (not zero)

    • toRef

      public CharacterVirtualRef toRef()
      Create another counted reference to the native CharacterVirtual.
      Specified by:
      toRef in class Ref
      Returns:
      a new JVM object with a new native object assigned