BetterCharacterControl (jMonkeyEngine 3.1 jme3-bullet Javadoc)

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, java.lang.Cloneable
```
public class BetterCharacterControl
extends AbstractPhysicsControl
implements PhysicsTickListener, com.jme3.util.clone.JmeCloneable
```
This is intended to be a replacement for the internal bullet character class. A RigidBody with cylinder collision shape is used and its velocity is set continuously, a ray test is used to check if the character is on the ground. The character keeps his own local coordinate system which adapts based on the gravity working on the character so the character will always stand upright. Forces in the local x/z plane are dampened while those in the local y direction are applied fully (e.g. jumping, falling).

Author:

normenhansen

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`ducked`
`protected float`	`duckedFactor`
`protected float`	`height`
`protected boolean`	`jump`
`protected com.jme3.math.Vector3f`	`jumpForce`
`protected com.jme3.math.Vector3f`	`localForward` Local absolute z-forward direction, derived from gravity and UNIT_Z, updated continuously when gravity changes.
`protected com.jme3.math.Quaternion`	`localForwardRotation` Local z-forward quaternion for the "local absolute" z-forward direction.
`protected com.jme3.math.Vector3f`	`localLeft` Local left direction, derived from up and forward.
`protected com.jme3.math.Vector3f`	`localUp` Local up direction, derived from gravity.
`protected com.jme3.math.Vector3f`	`location` Stores final spatial location, corresponds to RigidBody location.
`protected static java.util.logging.Logger`	`logger`
`protected float`	`mass`
`protected boolean`	`onGround`
`protected float`	`physicsDamping`
`protected float`	`radius`
`protected PhysicsRigidBody`	`rigidBody`
`protected com.jme3.math.Vector3f`	`rotatedViewDirection`
`protected com.jme3.math.Quaternion`	`rotation` Stores final spatial rotation, is a z-forward rotation based on the view direction and the current local x/z plane.
`protected com.jme3.math.Vector3f`	`scale`
`protected com.jme3.math.Vector3f`	`velocity`
`protected com.jme3.math.Vector3f`	`viewDirection` Is a z-forward vector based on the view direction and the current local x/z plane.
`protected com.jme3.math.Vector3f`	`walkDirection`
`protected boolean`	`wantToUnDuck`

Fields inherited from class com.jme3.bullet.control.AbstractPhysicsControl
added, applyLocal, enabled, space, spatial

Constructor Summary

Constructors
Constructor and Description
`BetterCharacterControl()` Only used for serialization, do not use this constructor.
`BetterCharacterControl(float radius, float height, float mass)` Creates a new character with the given properties.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`addPhysics(PhysicsSpace space)` This is implemented from AbstractPhysicsControl and called when the control is supposed to add all objects to the physics space.
`protected void`	`calculateNewForward(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f direction, com.jme3.math.Vector3f worldUpVector)` This method works similar to Camera.lookAt but where lookAt sets the priority on the direction, this method sets the priority on the up vector so that the result direction vector and rotation is guaranteed to be perpendicular to the up vector.
`protected boolean`	`checkCanUnDuck()` This checks if the character can go from ducked to unducked state by doing a ray test.
`protected void`	`checkOnGround()` This checks if the character is on the ground by doing a ray test.
`com.jme3.scene.control.Control`	`cloneForSpatial(com.jme3.scene.Spatial spatial)`
`protected void`	`createSpatialData(com.jme3.scene.Spatial spat)` Called when the control is added to a new spatial, create any spatial-dependent data here.
`float`	`getDuckedFactor()` Gets the height multiplication factor for ducking.
`protected float`	`getFinalHeight()` Gets the scaled height.
`protected float`	`getFinalRadius()` Gets the scaled radius.
`com.jme3.math.Vector3f`	`getGravity()` Get the current gravity of the character.
`com.jme3.math.Vector3f`	`getGravity(com.jme3.math.Vector3f store)` Get the current gravity of the character.
`com.jme3.math.Vector3f`	`getJumpForce()` Gets the current jump force.
`float`	`getPhysicsDamping()` Gets how much the physics forces in the local x/z plane should be dampened.
`protected CollisionShape`	`getShape()` Gets a new collision shape based on the current scale parameter.
`com.jme3.math.Vector3f`	`getVelocity()` Get the current linear velocity along the three axes of the character.
`com.jme3.math.Vector3f`	`getViewDirection()` Gets the current view direction, note this doesn't need to correspond with the spatials forward direction.
`com.jme3.math.Vector3f`	`getWalkDirection()` Gets the current walk direction and speed of the character.
`boolean`	`isDucked()` Check if the character is ducking, either due to user input or due to unducking being impossible at the moment (obstacle above).
`boolean`	`isOnGround()` Check if the character is on the ground.
`java.lang.Object`	`jmeClone()`
`void`	`jump()` Makes the character jump with the set jump force.
`void`	`physicsTick(PhysicsSpace space, float tpf)` Used internally, don't call manually
`void`	`prePhysicsTick(PhysicsSpace space, float tpf)` Used internally, don't call manually
`void`	`read(com.jme3.export.JmeImporter im)`
`protected void`	`removePhysics(PhysicsSpace space)` This is implemented from AbstractPhysicsControl and called when the control is supposed to remove all objects from the physics space.
`protected void`	`removeSpatialData(com.jme3.scene.Spatial spat)` Called when the control is removed from a spatial, remove any spatial-dependent data here.
`void`	`render(com.jme3.renderer.RenderManager rm, com.jme3.renderer.ViewPort vp)`
`void`	`resetForward(com.jme3.math.Vector3f vec)` Realign the local forward vector to given direction vector, if null is supplied Vector3f.UNIT_Z is used.
`void`	`setDucked(boolean enabled)` Toggle character ducking.
`void`	`setDuckedFactor(float factor)` Sets the height multiplication factor for ducking.
`void`	`setGravity(com.jme3.math.Vector3f gravity)` Set the gravity for this character.
`protected void`	`setHeightPercent(float percent)` This actually sets a new collision shape to the character to change the height of the capsule.
`void`	`setJumpForce(com.jme3.math.Vector3f jumpForce)` Set the jump force as a Vector3f.
`void`	`setPhysicsDamping(float physicsDamping)` Sets how much the physics forces in the local x/z plane should be dampened.
`protected void`	`setPhysicsLocation(com.jme3.math.Vector3f vec)` This is implemented from AbstractPhysicsControl and called when the spatial is attached for example.
`protected void`	`setPhysicsRotation(com.jme3.math.Quaternion quat)` This is implemented from AbstractPhysicsControl and called when the spatial is attached for example.
`void`	`setViewDirection(com.jme3.math.Vector3f vec)` Sets the view direction for the character.
`void`	`setWalkDirection(com.jme3.math.Vector3f vec)` Sets the walk direction of the character.
`void`	`update(float tpf)`
`protected void`	`updateLocalCoordinateSystem()` Updates the local coordinate system from the localForward and localUp vectors, adapts localForward, sets localForwardRotation quaternion to local z-forward rotation.
`protected void`	`updateLocalViewDirection()` Updates the local x/z-flattened view direction and the corresponding rotation quaternion for the spatial.
`void`	`warp(com.jme3.math.Vector3f vec)` Move the character somewhere.
`void`	`write(com.jme3.export.JmeExporter ex)`

Methods inherited from class com.jme3.bullet.control.AbstractPhysicsControl
applyPhysicsTransform, cloneFields, getPhysicsSpace, getSpatialRotation, getSpatialTranslation, isApplyPhysicsLocal, isEnabled, setApplyPhysicsLocal, setEnabled, setPhysicsSpace, setSpatial

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.jme3.util.clone.JmeCloneable
cloneFields

- Field Detail
  - logger
```
protected static final java.util.logging.Logger logger
```
  - rigidBody
```
protected PhysicsRigidBody rigidBody
```
  - radius
```
protected float radius
```
  - height
```
protected float height
```
  - mass
```
protected float mass
```
  - duckedFactor
```
protected float duckedFactor
```
  - localUp
```
protected final com.jme3.math.Vector3f localUp
```
    Local up direction, derived from gravity.
  - localForward
```
protected final com.jme3.math.Vector3f localForward
```
    Local absolute z-forward direction, derived from gravity and UNIT_Z, updated continuously when gravity changes.
  - localLeft
```
protected final com.jme3.math.Vector3f localLeft
```
    Local left direction, derived from up and forward.
  - localForwardRotation
```
protected final com.jme3.math.Quaternion localForwardRotation
```
    Local z-forward quaternion for the "local absolute" z-forward direction.
  - viewDirection
```
protected final com.jme3.math.Vector3f viewDirection
```
    Is a z-forward vector based on the view direction and the current local x/z plane.
  - location
```
protected final com.jme3.math.Vector3f location
```
    Stores final spatial location, corresponds to RigidBody location.
  - rotation
```
protected final com.jme3.math.Quaternion rotation
```
    Stores final spatial rotation, is a z-forward rotation based on the view direction and the current local x/z plane. See also rotatedViewDirection.
  - rotatedViewDirection
```
protected final com.jme3.math.Vector3f rotatedViewDirection
```
  - walkDirection
```
protected final com.jme3.math.Vector3f walkDirection
```
  - jumpForce
```
protected final com.jme3.math.Vector3f jumpForce
```
  - physicsDamping
```
protected float physicsDamping
```
  - scale
```
protected final com.jme3.math.Vector3f scale
```
  - velocity
```
protected final com.jme3.math.Vector3f velocity
```
  - jump
```
protected boolean jump
```
  - onGround
```
protected boolean onGround
```
  - ducked
```
protected boolean ducked
```
  - wantToUnDuck
```
protected boolean wantToUnDuck
```
- Constructor Detail
  - BetterCharacterControl
```
public BetterCharacterControl()
```
    Only used for serialization, do not use this constructor.
  - BetterCharacterControl
```
public BetterCharacterControl(float radius,
                      float height,
                      float mass)
```
    Creates a new character with the given properties. Note that to avoid issues the final height when ducking should be larger than 2x radius. The jumpForce will be set to an upwards force of 5x mass.
    
    Parameters:
    radius -
    height -
    mass -
- Method Detail
  - update
```
public void update(float tpf)
```
    Specified by:
    
    update in interface com.jme3.scene.control.Control
    
    Overrides:
    
    update in class AbstractPhysicsControl
  - render
```
public void render(com.jme3.renderer.RenderManager rm,
          com.jme3.renderer.ViewPort vp)
```
    Specified by:
    
    render in interface com.jme3.scene.control.Control
    
    Overrides:
    
    render in class AbstractPhysicsControl
  - prePhysicsTick
```
public void prePhysicsTick(PhysicsSpace space,
                  float tpf)
```
    Used internally, don't call manually
    
    Specified by:
    
    prePhysicsTick in interface PhysicsTickListener
    
    Parameters:
    space -
    tpf -
  - physicsTick
```
public void physicsTick(PhysicsSpace space,
               float tpf)
```
    Used internally, don't call manually
    
    Specified by:
    
    physicsTick in interface PhysicsTickListener
    
    Parameters:
    space -
    tpf -
  - warp
```
public void warp(com.jme3.math.Vector3f vec)
```
    Move the character somewhere. Note the character also takes the location of any spatial its being attached to in the moment it is attached.
    
    Parameters:
    vec - The new character location.
  - jump
```
public void jump()
```
    Makes the character jump with the set jump force.
  - setJumpForce
```
public void setJumpForce(com.jme3.math.Vector3f jumpForce)
```
    Set the jump force as a Vector3f. The jump force is local to the characters coordinate system, which normally is always z-forward (in world coordinates, parent coordinates when set to applyLocalPhysics)
    
    Parameters:
    jumpForce - The new jump force
  - getJumpForce
```
public com.jme3.math.Vector3f getJumpForce()
```
    Gets the current jump force. The default is 5 * character mass in y direction.
    
    Returns:
  - isOnGround
```
public boolean isOnGround()
```
    Check if the character is on the ground. This is determined by a ray test in the center of the character and might return false even if the character is not falling yet.
    
    Returns:
  - setDucked
```
public void setDucked(boolean enabled)
```
    Toggle character ducking. When ducked the characters capsule collision shape height will be multiplied by duckedFactor to make the capsule smaller. When unducking, the character will check with a ray test if it can in fact unduck and only do so when its possible. You can check the state of the unducking by checking isDucked().
    
    Parameters:
    enabled -
  - isDucked
```
public boolean isDucked()
```
    Check if the character is ducking, either due to user input or due to unducking being impossible at the moment (obstacle above).
    
    Returns:
  - setDuckedFactor
```
public void setDuckedFactor(float factor)
```
    Sets the height multiplication factor for ducking.
    
    Parameters:
    factor - The factor by which the height should be multiplied when ducking
  - getDuckedFactor
```
public float getDuckedFactor()
```
    Gets the height multiplication factor for ducking.
    
    Returns:
  - setWalkDirection
```
public void setWalkDirection(com.jme3.math.Vector3f vec)
```
    Sets the walk direction of the character. This parameter is framerate independent and the character will move continuously in the direction given by the vector with the speed given by the vector length in m/s.
    
    Parameters:
    vec - The movement direction and speed in m/s
  - getWalkDirection
```
public com.jme3.math.Vector3f getWalkDirection()
```
    Gets the current walk direction and speed of the character. The length of the vector defines the speed.
    
    Returns:
  - setViewDirection
```
public void setViewDirection(com.jme3.math.Vector3f vec)
```
    Sets the view direction for the character. Note this only defines the rotation of the spatial in the local x/z plane of the character.
    
    Parameters:
    vec -
  - getViewDirection
```
public com.jme3.math.Vector3f getViewDirection()
```
    Gets the current view direction, note this doesn't need to correspond with the spatials forward direction.
    
    Returns:
  - resetForward
```
public void resetForward(com.jme3.math.Vector3f vec)
```
    Realign the local forward vector to given direction vector, if null is supplied Vector3f.UNIT_Z is used. Input vector has to be perpendicular to current gravity vector. This normally only needs to be called when the gravity direction changed continuously and the local forward vector is off due to drift. E.g. after walking around on a sphere "planet" for a while and then going back to a y-up coordinate system the local z-forward might not be 100% alinged with Z axis.
    
    Parameters:
    vec - The new forward vector, has to be perpendicular to the current gravity vector!
  - getVelocity
```
public com.jme3.math.Vector3f getVelocity()
```
    Get the current linear velocity along the three axes of the character. This is prepresented in world coordinates, parent coordinates when the control is set to applyLocalPhysics.
    
    Returns:
    The current linear velocity of the character
  - setGravity
```
public void setGravity(com.jme3.math.Vector3f gravity)
```
    Set the gravity for 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:
    gravity -
  - getGravity
```
public com.jme3.math.Vector3f getGravity()
```
    Get the current gravity of the character.
    
    Returns:
  - getGravity
```
public com.jme3.math.Vector3f getGravity(com.jme3.math.Vector3f store)
```
    Get the current gravity of the character.
    
    Parameters:
    store - The vector to store the result in
    
    Returns:
  - setPhysicsDamping
```
public void setPhysicsDamping(float physicsDamping)
```
    Sets how much the physics forces in the local x/z plane should be dampened.
    
    Parameters:
    physicsDamping - The dampening value, 0 = no dampening, 1 = no external force, default = 0.9
  - getPhysicsDamping
```
public float getPhysicsDamping()
```
    Gets how much the physics forces in the local x/z plane should be dampened.
  - setHeightPercent
```
protected void setHeightPercent(float percent)
```
    This actually sets a new collision shape to the character to change the height of the capsule.
    
    Parameters:
    percent -
  - checkOnGround
```
protected void checkOnGround()
```
    This checks if the character is on the ground by doing a ray test.
  - checkCanUnDuck
```
protected boolean checkCanUnDuck()
```
    This checks if the character can go from ducked to unducked state by doing a ray test.
  - getShape
```
protected CollisionShape getShape()
```
    Gets a new collision shape based on the current scale parameter. The created collisionshape is a capsule collision shape that is attached to a compound collision shape with an offset to set the object center at the bottom of the capsule.
    
    Returns:
  - getFinalHeight
```
protected float getFinalHeight()
```
    Gets the scaled height.
    
    Returns:
  - getFinalRadius
```
protected float getFinalRadius()
```
    Gets the scaled radius.
    
    Returns:
  - updateLocalCoordinateSystem
```
protected void updateLocalCoordinateSystem()
```
    Updates the local coordinate system from the localForward and localUp vectors, adapts localForward, sets localForwardRotation quaternion to local z-forward rotation.
  - updateLocalViewDirection
```
protected void updateLocalViewDirection()
```
    Updates the local x/z-flattened view direction and the corresponding rotation quaternion for the spatial.
  - calculateNewForward
```
protected final void calculateNewForward(com.jme3.math.Quaternion rotation,
                       com.jme3.math.Vector3f direction,
                       com.jme3.math.Vector3f worldUpVector)
```
    This method works similar to Camera.lookAt but where lookAt sets the priority on the direction, this method sets the priority on the up vector so that the result direction vector and rotation is guaranteed to be perpendicular to the up vector.
    
    Parameters:
    rotation - The rotation to set the result on or null to create a new Quaternion, this will be set to the new "z-forward" rotation if not null
    direction - The direction to base the new look direction on, will be set to the new direction
    worldUpVector - The up vector to use, the result direction will be perpendicular to this
  - setPhysicsLocation
```
protected void setPhysicsLocation(com.jme3.math.Vector3f vec)
```
    This is implemented from AbstractPhysicsControl and called when the spatial is attached for example.
    
    Specified by:
    
    setPhysicsLocation in class AbstractPhysicsControl
    
    Parameters:
    vec -
  - setPhysicsRotation
```
protected void setPhysicsRotation(com.jme3.math.Quaternion quat)
```
    This is implemented from AbstractPhysicsControl and called when the spatial is attached for example. We don't set the actual physics rotation but the view rotation here. It might actually be altered by the calculateNewForward method.
    
    Specified by:
    
    setPhysicsRotation in class AbstractPhysicsControl
    
    Parameters:
    quat -
  - addPhysics
```
protected void addPhysics(PhysicsSpace space)
```
    This is implemented from AbstractPhysicsControl and called when the control is supposed to add all objects to the physics space.
    
    Specified by:
    
    addPhysics in class AbstractPhysicsControl
    
    Parameters:
    space -
  - removePhysics
```
protected void removePhysics(PhysicsSpace space)
```
    This is implemented from AbstractPhysicsControl and called when the control is supposed to remove all objects from the physics space.
    
    Specified by:
    
    removePhysics in class AbstractPhysicsControl
    
    Parameters:
    space -
  - createSpatialData
```
protected void createSpatialData(com.jme3.scene.Spatial spat)
```
    Description copied from class: AbstractPhysicsControl
    
    Called when the control is added to a new spatial, create any spatial-dependent data here.
    
    Specified by:
    
    createSpatialData in class AbstractPhysicsControl
    
    Parameters:
    spat - The new spatial, guaranteed not to be null
  - removeSpatialData
```
protected void removeSpatialData(com.jme3.scene.Spatial spat)
```
    Description copied from class: AbstractPhysicsControl
    
    Called when the control is removed from a spatial, remove any spatial-dependent data here.
    
    Specified by:
    
    removeSpatialData in class AbstractPhysicsControl
    
    Parameters:
    spat - The old spatial, guaranteed not to be null
  - cloneForSpatial
```
public com.jme3.scene.control.Control cloneForSpatial(com.jme3.scene.Spatial spatial)
```
    Specified by:
    
    cloneForSpatial in interface com.jme3.scene.control.Control
  - jmeClone
```
public java.lang.Object jmeClone()
```
    Specified by:
    
    jmeClone in interface com.jme3.util.clone.JmeCloneable
  - write
```
public void write(com.jme3.export.JmeExporter ex)
           throws java.io.IOException
```
    Specified by:
    
    write in interface com.jme3.export.Savable
    
    Overrides:
    
    write in class AbstractPhysicsControl
    
    Throws:
    
    java.io.IOException
  - read
```
public void read(com.jme3.export.JmeImporter im)
          throws java.io.IOException
```
    Specified by:
    
    read in interface com.jme3.export.Savable
    
    Overrides:
    
    read in class AbstractPhysicsControl
    
    Throws:
    
    java.io.IOException

Class BetterCharacterControl

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Methods inherited from interface com.jme3.util.clone.JmeCloneable

Field Detail

logger

rigidBody

radius

height

mass

duckedFactor

localUp

localForward

localLeft

localForwardRotation

viewDirection

location

rotation

rotatedViewDirection

walkDirection

jumpForce

physicsDamping

scale

velocity

jump

onGround

ducked

wantToUnDuck

Constructor Detail

BetterCharacterControl

BetterCharacterControl

Method Detail

update

render

prePhysicsTick

physicsTick

warp

jump

setJumpForce

getJumpForce

isOnGround

setDucked

isDucked

setDuckedFactor

getDuckedFactor

setWalkDirection

getWalkDirection

setViewDirection

getViewDirection

resetForward

getVelocity

setGravity

getGravity

getGravity

setPhysicsDamping

getPhysicsDamping

setHeightPercent

checkOnGround

checkCanUnDuck

getShape

getFinalHeight

getFinalRadius

updateLocalCoordinateSystem

updateLocalViewDirection

calculateNewForward

setPhysicsLocation

setPhysicsRotation

addPhysics

removePhysics

createSpatialData

removeSpatialData

cloneForSpatial

jmeClone

write

read