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

Class CharacterRef

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

  • Constructor Details

    • CharacterRef

      public CharacterRef()
      Instantiate an empty reference.

  • Method Details

    • addToPhysicsSystem

      public void addToPhysicsSystem()
      Add the character to its PhysicsSystem and activate it, using the locking body interface.

    • addToPhysicsSystem

      public void addToPhysicsSystem(EActivation activation)
      Add the character to its PhysicsSystem using the locking body interface.
      Parameters:
      activation - whether to activate the character (not null, default=Activate)

    • addToPhysicsSystem

      public void addToPhysicsSystem(EActivation activation, boolean lockBodies)
      Add the character to its PhysicsSystem.
      Parameters:
      activation - whether to activate the character (not null, default=Activate)
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • postSimulation

      public void postSimulation(float maxSeparation)
      Needs to be invoked after every physics update.
      Parameters:
      maxSeparation - the max distance between the floor and the character for standing

    • postSimulation

      public void postSimulation(float maxSeparation, boolean lockBodies)
      Needs to be invoked after every physics update.
      Parameters:
      maxSeparation - the max distance between the floor and the character for standing
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • removeFromPhysicsSystem

      public void removeFromPhysicsSystem()
      Remove the character from its PhysicsSystem using the locking body interface.

    • removeFromPhysicsSystem

      public void removeFromPhysicsSystem(boolean lockBodies)
      Remove the character from its PhysicsSystem.
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • 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 using the locking body interface.
      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(float vx, float vy, float vz, boolean lockBodies)
      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)
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • setLinearVelocity

      public void setLinearVelocity(Vec3Arg velocity)
      Alter the character's linear velocity using the locking body interface.
      Parameters:
      velocity - the desired velocity (meters per second in system coordinates, not null, unaffected)

    • setLinearVelocity

      public void setLinearVelocity(Vec3Arg velocity, boolean lockBodies)
      Alter the character's linear velocity.
      Parameters:
      velocity - the desired velocity (meters per second in system coordinates, not null, unaffected)
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • setShape

      public boolean setShape(ConstShape shape, float maxPenetrationDepth)
      Attempt to replace the character's shape using the locking body interface.
      Parameters:
      shape - the desired shape (not null, unaffected)
      maxPenetrationDepth - the maximum penetration to allow, or MAX_VALUE to skip the penetration check
      Returns:
      true if the replacement succeeded, otherwise false

    • setShape

      public boolean setShape(ConstShape shape, float maxPenetrationDepth, boolean lockBodies)
      Attempt to replace the character's shape.
      Parameters:
      shape - the desired shape (not null, unaffected)
      maxPenetrationDepth - the maximum penetration to allow, or MAX_VALUE to skip the penetration check
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      Returns:
      true if the replacement succeeded, otherwise false

    • getBodyId

      public int getBodyId()
      Return the ID of the body associated with the character. The character is unaffected. (native function: GetBodyID)
      Specified by:
      getBodyId in interface ConstCharacter
      Returns:
      the BodyID value

    • getCenterOfMassPosition

      public RVec3 getCenterOfMassPosition()
      Copy the location of the rigid body's center of mass using the locking body interface. The character is unaffected.
      Specified by:
      getCenterOfMassPosition in interface ConstCharacter
      Returns:
      a new location vector (in system coordinates)

    • getCenterOfMassPosition

      public RVec3 getCenterOfMassPosition(boolean lockBodies)
      Copy the location of the rigid body's center of mass. The character is unaffected.
      Specified by:
      getCenterOfMassPosition in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      Returns:
      a new location vector (in system coordinates)

    • getCharacterSettings

      public CharacterSettings getCharacterSettings()
      Generate settings to reconstruct the character, using the locking body interface. The character is unaffected.
      Specified by:
      getCharacterSettings in interface ConstCharacter
      Returns:
      a new object

    • getCharacterSettings

      public CharacterSettings getCharacterSettings(boolean lockBodies)
      Generate settings to reconstruct the character. The character is unaffected.
      Specified by:
      getCharacterSettings in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface,
      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

    • 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)

    • getLayer

      public int getLayer()
      Return the character's object layer, using the locking body interface. The character is unaffected.
      Specified by:
      getLayer in interface ConstCharacter
      Returns:
      a layer index (≥0)

    • getLayer

      public int getLayer(boolean lockBodies)
      Return the character's object layer. The character is unaffected.
      Specified by:
      getLayer in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      Returns:
      a layer index (≥0)

    • getLinearVelocity

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

    • getLinearVelocity

      public Vec3 getLinearVelocity(boolean lockBodies)
      Copy the linear velocity of the character. The character is unaffected.
      Specified by:
      getLinearVelocity in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      Returns:
      a new velocity vector (meters per second in system coordinates)

    • getPosition

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

    • getPosition

      public RVec3 getPosition(boolean lockBodies)
      Copy the location of the character. The character is unaffected.
      Specified by:
      getPosition in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      Returns:
      a new location vector (in system coordinates)

    • getPositionAndRotation

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

    • getPositionAndRotation

      public void getPositionAndRotation(RVec3 storeLocation, Quat storeOrientation, boolean lockBodies)
      Copy the position of the associated body. The character is unaffected.
      Specified by:
      getPositionAndRotation in interface ConstCharacter
      Parameters:
      storeLocation - storage for the location (in system coordinates, not null, modified)
      storeOrientation - storage for the orientation (in system coordinates, not null, modified)
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • getRefCount

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

    • getRotation

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

    • getRotation

      public Quat getRotation(boolean lockBodies)
      Copy the orientation of the character. The character is unaffected.
      Specified by:
      getRotation in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      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)

    • getTransformedShape

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

    • getTransformedShape

      public TransformedShape getTransformedShape(boolean lockBodies)
      Generate a TransformedShape that represents the volume occupied by the character. The character is unaffected.
      Specified by:
      getTransformedShape in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      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

    • getWorldTransform

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

    • getWorldTransform

      public RMat44 getWorldTransform(boolean lockBodies)
      Calculate the character's local-to-system coordinate transform. The character is unaffected.
      Specified by:
      getWorldTransform in interface ConstCharacter
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)
      Returns:
      a new transform matrix

    • 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 CharacterRefC toRefC()
      Create another counted reference to the native Character.
      Specified by:
      toRefC in interface ConstCharacter
      Returns:
      a new JVM object with a new native object assigned

    • getPtr

      public Character getPtr()
      Temporarily access the referenced Character.
      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 Character. No objects are affected.
      Specified by:
      targetVa in interface ConstJoltPhysicsObject
      Overrides:
      targetVa in class JoltPhysicsObject
      Returns:
      a virtual address (not zero)

    • toRef

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