Package com.jme3.bullet.control

Class BetterCharacterControl

java.lang.Object
com.jme3.bullet.control.AbstractPhysicsControl
com.jme3.bullet.control.BetterCharacterControl
All Implemented Interfaces:
PhysicsControl, PhysicsTickListener, com.jme3.export.Savable, com.jme3.scene.control.Control, com.jme3.util.clone.JmeCloneable, Cloneable
public class BetterCharacterControl extends AbstractPhysicsControl implements PhysicsTickListener
This class is intended to replace the CharacterControl class.

A rigid body with an offset CapsuleCollisionShape is used. Its linear velocity is updated continuously. A sweep test is used to determine whether the character is on the ground.

The character maintains a local coordinate system in which gravity determines the Y axis.

Motion in the local X-Z plane is damped.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Logger
    logger2
    message logger for this class

    Fields inherited from class com.jme3.bullet.control.AbstractPhysicsControl

    added, logger

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    BetterCharacterControl()
    No-argument constructor needed by SavableClassUtil.
     
    BetterCharacterControl(float radius, float height, float mass)
    Instantiate an enabled Control with the specified properties.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    addPhysics()
    Add all managed physics objects to the PhysicsSpace.
    protected void
    calculateNewForward(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f direction, com.jme3.math.Vector3f worldUpVector)
    Adjust the specified direction vector so it is perpendicular to the specified local "up" direction.
    protected boolean
    checkCanUnDuck()
    Determine whether the character can emerge from the ducked state at its current location.
    protected void
    checkOnGround()
    Update the internal onGround status.
    void
    cloneFields(com.jme3.util.clone.Cloner cloner, Object original)
    Callback from Cloner to convert this shallow-cloned Control into a deep-cloned one, using the specified Cloner and original to resolve copied fields.
    protected void
    createSpatialData(com.jme3.scene.Spatial spatial)
    Create spatial-dependent data.
    float
    getDuckedFactor()
    Return the collision-shape height multiplier for ducking.
    protected float
    getFinalHeight()
    Return the scaled height of the collision shape, including both hemispheres and the cylindrical part.
    protected float
    getFinalRadius()
    Return the scaled radius of the collision shape.
    com.jme3.math.Vector3f
    getGravity(com.jme3.math.Vector3f storeResult)
    Copy the character's gravity vector.
    float
    getInitialHeight()
    Return the the initial height of the collision shape.
    float
    getInitialRadius()
    Return the the initial radius of the collision shape.
    com.jme3.math.Vector3f
    getJumpForce(com.jme3.math.Vector3f storeResult)
    Copy the impulse applied at the start of each jump.
    float
    getPhysicsDamping()
    Return the damping factor for horizontal motion.
    PhysicsRigidBody
    getRigidBody()
    Access the rigid body managed by this control.
    protected CollisionShape
    getShape()
    Create a CollisionShape based on the scale parameter.
    com.jme3.math.Vector3f
    getVelocity()
    For compatibility with the jme3-jbullet library.
    com.jme3.math.Vector3f
    getVelocity(com.jme3.math.Vector3f storeResult)
    Copy the character's linear velocity.
    com.jme3.math.Vector3f
    getViewDirection()
    For compatibility with the jme3-jbullet library.
    com.jme3.math.Vector3f
    getViewDirection(com.jme3.math.Vector3f storeResult)
    Copy the character's view direction.
    com.jme3.math.Vector3f
    getWalkDirection(com.jme3.math.Vector3f storeResult)
    Copy the character's walk velocity.
    boolean
    isDucked()
    Determine whether the character is in a ducked state, either due to user input or because an overhead obstacle prevents it from unducking.
    boolean
    isKinematic()
    Test whether the character is in kinematic mode.
    boolean
    isOnGround()
    Test whether the character is supported by another collision object.
    void
    jump()
    Apply a jump impulse during the next simulation step if the character is on ground and not in kinematic mode.
    void
    physicsTick(PhysicsSpace space, float timeStep)
    Callback from Bullet, invoked just after the physics has been stepped.
    void
    prePhysicsTick(PhysicsSpace space, float timeStep)
    Callback from Bullet, invoked just before the physics is stepped.
    void
    read(com.jme3.export.JmeImporter importer)
    De-serialize this Control from the specified importer, for example when loading from a J3O file.
    protected void
    removePhysics()
    Remove all managed physics objects from the PhysicsSpace.
    protected void
    removeSpatialData(com.jme3.scene.Spatial spatial)
    Destroy spatial-dependent data.
    void
    resetForward(com.jme3.math.Vector3f vec)
    Alter the character's forward (+Z) direction, provided it's in dynamic mode.
    void
    setDucked(boolean newState)
    Alter the character's ducking state.
    void
    setDuckedFactor(float factor)
    Alter the collision-shape height multiplier for ducking.
    void
    setGravity(com.jme3.math.Vector3f newGravity)
    Alter the gravity acting on this character.
    protected void
    setHeightPercent(float fraction)
    Alter the height of the collision shape.
    void
    setJumpForce(com.jme3.math.Vector3f newImpulse)
    Alter the impulse applied at the start of each jump.
    void
    setKinematic(boolean newSetting)
    Transition the character from kinematic mode to dynamic mode or vice versa.
    void
    setPhysicsDamping(float newFactor)
    Alter the damping factor for horizontal motion.
    protected void
    setPhysicsLocation(com.jme3.math.Vector3f newLocation)
    Translate the character instantly to the specified location.
    protected void
    setPhysicsRotation(com.jme3.math.Quaternion newOrientation)
    Rotate the character's viewpoint to the specified orientation.
    void
    setViewDirection(com.jme3.math.Vector3f newDirection)
    Alter the character's view direction, provided it's in dynamic mode.
    void
    setWalkDirection(com.jme3.math.Vector3f newVelocity)
    Alter the character's walk velocity.
    void
    update(float tpf)
    Update this Control.
    protected void
    updateLocalCoordinateSystem()
    Update the local coordinate system from the localForward and localUp vectors, adapts localForward and localToWorld.
    protected void
    updateLocalViewDirection()
    Update the character's viewpoint.
    void
    warp(com.jme3.math.Vector3f newLocation)
    Translate the character instantly to the specified location, provided it's in dynamic mode.
    void
    write(com.jme3.export.JmeExporter exporter)
    Serialize this Control to the specified exporter, for example when saving to a J3O file.

    Methods inherited from class com.jme3.bullet.control.AbstractPhysicsControl

    applyPhysicsTransform, cloneForSpatial, getPhysicsSpace, getSpatial, getSpatialRotation, getSpatialTranslation, isApplyPhysicsLocal, isEnabled, jmeClone, render, setApplyPhysicsLocal, setEnabled, setPhysicsSpace, setSpatial

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • logger2

      public static final Logger logger2
      message logger for this class

  • Constructor Details

    • BetterCharacterControl

      protected BetterCharacterControl()
      No-argument constructor needed by SavableClassUtil.

    • BetterCharacterControl

      public BetterCharacterControl(float radius, float height, float mass)
      Instantiate an enabled Control with the specified properties.

      The height must exceed 2x the radius, even when ducked.

      Parameters:
      radius - the initial radius for the character's collision shape (in physics-space units, >0)
      height - the initial height for the character's collision shape (in physics-space units, >2*radius)
      mass - the character's mass (≥0)

  • Method Details

    • getDuckedFactor

      public float getDuckedFactor()
      Return the collision-shape height multiplier for ducking.
      Returns:
      the factor by which the initial height will be multiplied (>0, ≤1)

    • getGravity

      public com.jme3.math.Vector3f getGravity(com.jme3.math.Vector3f storeResult)
      Copy the character's gravity vector.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an acceleration vector in physics-space coordinates (either storeResult or a new vector, not null)

    • getInitialHeight

      public float getInitialHeight()
      Return the the initial height of the collision shape.
      Returns:
      the height (in physics-space units, >2*radius)

    • getInitialRadius

      public float getInitialRadius()
      Return the the initial radius of the collision shape.
      Returns:
      the radius (in physics-space units, >0)

    • getJumpForce

      public com.jme3.math.Vector3f getJumpForce(com.jme3.math.Vector3f storeResult)
      Copy the impulse applied at the start of each jump.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an impulse vector in local coordinates (either storeResult or a new vector, not null)

    • getPhysicsDamping

      public float getPhysicsDamping()
      Return the damping factor for horizontal motion.
      Returns:
      the damping factor for motion in the local X-Z plane (applied before each simulation step, 0→no damping, 1=horizontal forces have no effect, ≥0, ≤1)

    • getRigidBody

      public PhysicsRigidBody getRigidBody()
      Access the rigid body managed by this control.
      Returns:
      the pre-existing rigid body (not null)

    • getVelocity

      public com.jme3.math.Vector3f getVelocity()
      For compatibility with the jme3-jbullet library. The jme3-jbullet version returns a pre-existing vector instead of a new one.
      Returns:
      a new velocity vector

    • getVelocity

      public com.jme3.math.Vector3f getVelocity(com.jme3.math.Vector3f storeResult)
      Copy the character's linear velocity.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a velocity vector (either storeResult or a new vector, not null)

    • getViewDirection

      public com.jme3.math.Vector3f getViewDirection()
      For compatibility with the jme3-jbullet library. The jme3-jbullet version returns a pre-existing vector instead of a new one.
      Returns:
      a new direction vector (in physics-space coordinates)

    • getViewDirection

      public com.jme3.math.Vector3f getViewDirection(com.jme3.math.Vector3f storeResult)
      Copy the character's view direction.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a direction vector (in local coordinates, either storeResult or a new vector, not null)

    • getWalkDirection

      public com.jme3.math.Vector3f getWalkDirection(com.jme3.math.Vector3f storeResult)
      Copy the character's walk velocity. The length of the vector defines the requested speed.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a velocity vector (in physics-space coordinates, either storeResult or a new vector, not null)

    • isDucked

      public boolean isDucked()
      Determine whether the character is in a ducked state, either due to user input or because an overhead obstacle prevents it from unducking.
      Returns:
      true if ducking, otherwise false

    • isKinematic

      public boolean isKinematic()
      Test whether the character is in kinematic mode.
      Returns:
      true if in kinematic mode, otherwise false (in dynamic mode)

    • isOnGround

      public boolean isOnGround()
      Test whether the character is supported by another collision object.
      Returns:
      true if supported, otherwise false

    • jump

      public void jump()
      Apply a jump impulse during the next simulation step if the character is on ground and not in kinematic mode.

    • resetForward

      public void resetForward(com.jme3.math.Vector3f vec)
      Alter the character's forward (+Z) direction, provided it's in dynamic mode.
      Parameters:
      vec - the desired direction (in physics-space coordinates) or null for (0,0,1)

    • setDucked

      public void setDucked(boolean newState)
      Alter the character's ducking state. When ducked, the character's collision-shape height is scaled by duckedFactor to make it shorter. Before unducking, the character performs a sweep test; it grows taller only if there's room above its head. You can test the state using isDucked().
      Parameters:
      newState - true→duck, false→unduck

    • setDuckedFactor

      public void setDuckedFactor(float factor)
      Alter the collision-shape height multiplier for ducking.
      Parameters:
      factor - the factor by which the initial height will be multiplied (>0, ≤1, default=0.6)

    • setGravity

      public void setGravity(com.jme3.math.Vector3f newGravity)
      Alter the gravity acting on this character. Note that this also realigns the local coordinate system of the character so that continuous changes in gravity direction are possible while maintaining a sensible control over the character.
      Parameters:
      newGravity - the desired acceleration vector (in physics-space coordinates, not null, finite, unaffected)

    • setJumpForce

      public void setJumpForce(com.jme3.math.Vector3f newImpulse)
      Alter the impulse applied at the start of each jump.
      Parameters:
      newImpulse - the desired impulse (in local coordinates, not null, finite, unaffected, default=5*mass in +Y direction)

    • setKinematic

      public void setKinematic(boolean newSetting)
      Transition the character from kinematic mode to dynamic mode or vice versa.
      Parameters:
      newSetting - true→set kinematic mode, false→set dynamic mode (default=false)

    • setPhysicsDamping

      public void setPhysicsDamping(float newFactor)
      Alter the damping factor for horizontal motion.
      Parameters:
      newFactor - the desired damping factor for motion in the local X-Z plane (applied before each simulation step, 0→no damping, 1=horizontal forces have no effect, ≥0, ≤1, default=0.9)

    • setViewDirection

      public void setViewDirection(com.jme3.math.Vector3f newDirection)
      Alter the character's view direction, provided it's in dynamic mode. View direction is used to orient the rigid body.
      Parameters:
      newDirection - a direction vector in local coordinates (not null, not zero, unaffected)

    • setWalkDirection

      public void setWalkDirection(com.jme3.math.Vector3f newVelocity)
      Alter the character's walk velocity. The length of the vector determines the requested speed, in physics-space units per second.
      Parameters:
      newVelocity - the requested velocity (in physics-space coordinates, not null, unaffected)

    • warp

      public void warp(com.jme3.math.Vector3f newLocation)
      Translate the character instantly to the specified location, provided it's in dynamic mode.
      Parameters:
      newLocation - the desired location of the base (in physics-space coordinates, not null, finite, unaffected)

    • addPhysics

      protected void addPhysics()
      Add all managed physics objects to the PhysicsSpace.
      Specified by:
      addPhysics in class AbstractPhysicsControl

    • cloneFields

      public void cloneFields(com.jme3.util.clone.Cloner cloner, Object original)
      Callback from Cloner to convert this shallow-cloned Control into a deep-cloned one, using the specified Cloner and original to resolve copied fields.
      Specified by:
      cloneFields in interface com.jme3.util.clone.JmeCloneable
      Overrides:
      cloneFields in class AbstractPhysicsControl
      Parameters:
      cloner - the Cloner that's cloning this Control (not null, modified)
      original - the instance from which this Control was shallow-cloned (not null, unaffected)

    • createSpatialData

      protected void createSpatialData(com.jme3.scene.Spatial spatial)
      Create spatial-dependent data. Invoked when this Control is added to a Spatial.
      Specified by:
      createSpatialData in class AbstractPhysicsControl
      Parameters:
      spatial - the controlled Spatial (not null, alias created)

    • read

      public void read(com.jme3.export.JmeImporter importer) throws IOException
      De-serialize this Control from the specified importer, for example when loading from a J3O file.
      Specified by:
      read in interface com.jme3.export.Savable
      Overrides:
      read in class AbstractPhysicsControl
      Parameters:
      importer - (not null)
      Throws:
      IOException - from the importer

    • removePhysics

      protected void removePhysics()
      Remove all managed physics objects from the PhysicsSpace.
      Specified by:
      removePhysics in class AbstractPhysicsControl

    • removeSpatialData

      protected void removeSpatialData(com.jme3.scene.Spatial spatial)
      Destroy spatial-dependent data. Invoked when this Control is removed from its Spatial.
      Specified by:
      removeSpatialData in class AbstractPhysicsControl
      Parameters:
      spatial - the Spatial to which this Control was added (unused)

    • setPhysicsLocation

      protected void setPhysicsLocation(com.jme3.math.Vector3f newLocation)
      Translate the character instantly to the specified location.
      Specified by:
      setPhysicsLocation in class AbstractPhysicsControl
      Parameters:
      newLocation - the desired location of the base (in physics-space coordinates, not null, finite, unaffected)

    • setPhysicsRotation

      protected void setPhysicsRotation(com.jme3.math.Quaternion newOrientation)
      Rotate the character's viewpoint to the specified orientation.

      We don't set the body orientation here, but the view rotation, which might be changed by the calculateNewForward() method.

      Specified by:
      setPhysicsRotation in class AbstractPhysicsControl
      Parameters:
      newOrientation - the desired orientation (in physics-space coordinates, not null, not zero, unaffected)

    • update

      public void update(float tpf)
      Update this Control. Invoked once per frame during the logical-state update, provided the Control is added to a scene. Do not invoke directly from user code.
      Specified by:
      update in interface com.jme3.scene.control.Control
      Parameters:
      tpf - the time interval between frames (in seconds, ≥0)

    • write

      public void write(com.jme3.export.JmeExporter exporter) throws IOException
      Serialize this Control to the specified exporter, for example when saving to a J3O file.
      Specified by:
      write in interface com.jme3.export.Savable
      Overrides:
      write in class AbstractPhysicsControl
      Parameters:
      exporter - (not null)
      Throws:
      IOException - from the exporter

    • physicsTick

      public void physicsTick(PhysicsSpace space, float timeStep)
      Callback from Bullet, invoked just after the physics has been stepped.
      Specified by:
      physicsTick in interface PhysicsTickListener
      Parameters:
      space - the space that was just stepped (not null)
      timeStep - the duration of the simulation step (in seconds, ≥0)

    • prePhysicsTick

      public void prePhysicsTick(PhysicsSpace space, float timeStep)
      Callback from Bullet, invoked just before the physics is stepped.
      Specified by:
      prePhysicsTick in interface PhysicsTickListener
      Parameters:
      space - the space that's about to be stepped (not null)
      timeStep - the duration of the simulation step (in seconds, ≥0)

    • calculateNewForward

      protected void calculateNewForward(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f direction, com.jme3.math.Vector3f worldUpVector)
      Adjust the specified direction vector so it is perpendicular to the specified local "up" direction.
      Parameters:
      rotation - storage for an orientation in which worldUpVector is +Y and direction is +Z (modified if not null)
      direction - the direction in physics-space coordinates (modified if not null)
      worldUpVector - the local "up" direction in physics-space coordinates (not null, not zero, unaffected)

    • checkCanUnDuck

      protected boolean checkCanUnDuck()
      Determine whether the character can emerge from the ducked state at its current location.
      Returns:
      true if able to unduck, otherwise false

    • checkOnGround

      protected void checkOnGround()
      Update the internal onGround status.

    • getFinalHeight

      protected float getFinalHeight()
      Return the scaled height of the collision shape, including both hemispheres and the cylindrical part.
      Returns:
      the height (in physics-space units, >0)

    • getFinalRadius

      protected float getFinalRadius()
      Return the scaled radius of the collision shape.
      Returns:
      the radius (in physics-space units, >0)

    • getShape

      protected CollisionShape getShape()
      Create a CollisionShape based on the scale parameter.
      Returns:
      a new compound shape containing a capsule (not null)

    • setHeightPercent

      protected void setHeightPercent(float fraction)
      Alter the height of the collision shape.
      Parameters:
      fraction - the desired height, as a fraction of the initial height (default=1)

    • updateLocalCoordinateSystem

      protected void updateLocalCoordinateSystem()
      Update the local coordinate system from the localForward and localUp vectors, adapts localForward and localToWorld.

    • updateLocalViewDirection

      protected void updateLocalViewDirection()
      Update the character's viewpoint.