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

Class Character

java.lang.Object
com.github.stephengold.joltjni.JoltPhysicsObject
com.github.stephengold.joltjni.NonCopyable
com.github.stephengold.joltjni.CharacterBase
com.github.stephengold.joltjni.Character
All Implemented Interfaces:
ConstCharacter, ConstCharacterBase, ConstJoltPhysicsObject, RefTarget, AutoCloseable, Comparable<JoltPhysicsObject>
public class Character extends CharacterBase implements ConstCharacter
A character implemented using a kinematic rigid body.

  • Constructor Details

    • Character

      public Character(ConstCharacterSettings settings, RVec3Arg location, QuatArg orientation, long userData, PhysicsSystem system)
      Instantiate a character with the specified properties.
      Parameters:
      settings - the settings to use (not null, unaffected)
      location - the desired initial location (in system coordinates, not null, unaffected)
      orientation - the desired initial orientation (in system coordinates, not null, unaffected)
      userData - the desired user-data value
      system - where to add the body (not null)

  • Method Details

    • activate

      public void activate()
      Wake up the character using the locking body interface.

    • activate

      public void activate(boolean lockBodies)
      Wake up the character.
      Parameters:
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • addImpulse

      public void addImpulse(Vec3Arg impulse)
      Apply an impulse to the character's center of mass, using the locking body interface.
      Parameters:
      impulse - the impulse vector (kilogram.meters per second in system coordinates, not null, unaffected)

    • addImpulse

      public void addImpulse(Vec3Arg impulse, boolean lockBodies)
      Apply an impulse to the character's center of mass.
      Parameters:
      impulse - the impulse vector (kilogram.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)

    • addLinearVelocity

      public void addLinearVelocity(Vec3Arg deltaV)
      Add to the character's linear velocity, using the locking body interface.
      Parameters:
      deltaV - the change in velocity (meters per second in system coordinates, not null, unaffected)

    • addLinearVelocity

      public void addLinearVelocity(Vec3Arg deltaV, boolean lockBodies)
      Add to the character's linear velocity.
      Parameters:
      deltaV - the change in 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)

    • 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 (in meters)

    • 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 (in meters)
      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)

    • setLayer

      public void setLayer(int layer)
      Alter the character's object layer, using the locking body interface.
      Parameters:
      layer - the index of the desired layer (default=0)

    • setLayer

      public void setLayer(int layer, boolean lockBodies)
      Alter the character's object layer.
      Parameters:
      layer - the index of the desired layer (default=0)
      lockBodies - true → use the locking body interface, false → use the non-locking body interface (default=true)

    • setLinearAndAngularVelocity

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

    • setLinearAndAngularVelocity

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

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

    • setPosition

      public void setPosition(RVec3Arg location)
      Relocate and activate the character using the locking body interface.
      Parameters:
      location - the desired location (in system coordinates, not null, unaffected)

    • setPosition

      public void setPosition(RVec3Arg location, EActivation activation)
      Relocate the character, optionally activating it, using the locking body interface.
      Parameters:
      location - the desired location (in system coordinates, not null, unaffected)
      activation - whether to activate the character (not null, default=Activate)

    • setPosition

      public void setPosition(RVec3Arg location, EActivation activation, boolean lockBodies)
      Relocate the character, optionally activating it.
      Parameters:
      location - the desired location (in system coordinates, not null, unaffected)
      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)

    • setPositionAndRotation

      public void setPositionAndRotation(RVec3Arg location, QuatArg orientation)
      Reposition and activate the character using the locking body interface.
      Parameters:
      location - the desired location (in system coordinates, not null, unaffected)
      orientation - the desired orientation (in system coordinates, not null, unaffected)

    • setPositionAndRotation

      public void setPositionAndRotation(RVec3Arg location, QuatArg orientation, EActivation activation)
      Reposition the character, optionally activating it.
      Parameters:
      location - the desired location (in system coordinates, not null, unaffected)
      orientation - the desired orientation (in system coordinates, not null, unaffected)
      activation - whether to activate the character (not null, default=Activate)

    • setPositionAndRotation

      public void setPositionAndRotation(RVec3Arg location, QuatArg orientation, EActivation activation, boolean lockBodies)
      Reposition the character, optionally activating it.
      Parameters:
      location - the desired location (in system coordinates, not null, unaffected)
      orientation - the desired orientation (in system coordinates, not null, unaffected)
      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)

    • setRotation

      public void setRotation(QuatArg orientation)
      Re-orient and activate the character using the locking body interface.
      Parameters:
      orientation - the desired orientation (in system coordinates, not null, unaffected)

    • setRotation

      public void setRotation(QuatArg orientation, EActivation activation)
      Re-orient the character, optionally activating it.
      Parameters:
      orientation - the desired orientation (in system coordinates, not null, unaffected)
      activation - whether to activate the character (not null, default=Activate)

    • setRotation

      public void setRotation(QuatArg orientation, EActivation activation, boolean lockBodies)
      Re-orient the character, optionally activating it.
      Parameters:
      orientation - the desired orientation (in system coordinates, not null, unaffected)
      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)

    • 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

    • toRef

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

    • 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

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

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

    • 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

    • 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

    • toRefC

      public CharacterRefC toRefC()
      Create a counted reference to the native Character.
      Specified by:
      toRefC in interface ConstCharacter
      Returns:
      a new JVM object with a new native object assigned