Emini Physics Engine 1.3.5a API Documentation

at.emini.physics2D
Class World

java.lang.Object
  extended by at.emini.physics2D.World

public class World
extends java.lang.Object

The world class represents the simulation environment.
It has the following responsibilities:

The simulation step consists of

It handles fast movement detection and resolution, event checking and handling and execution of body scripts.
All physical units are given in pixel and seconds (e.g: speed in pixel/sec.). Masses are on dimensionless scale.

Author:
Alexander Adensamer

Field Summary
static int M_SHAPE_MAX_VERTICES
           
protected  EventSet mEventSet
          Eventset managing the events.
protected  java.util.Vector mForces
           
protected  java.util.Vector mParticles
           
protected  ShapeSet mShapeSet
          Shapeset managing the shapes.
protected  UserData mUserData
          User data
 
Constructor Summary
  World()
          Empty Constructor.
protected World(ShapeSet set)
          Constructor with shapes.
  World(World world)
          Copy constructor.
 
Method Summary
 void addBody(Body body)
          Adds a body to the world.
 void addConstraint(Constraint constraint)
          Adds a constraint to the world.
 void addEvent(Event event)
          Adds an event definition to the world.
 void addExternalForce(ExternalForce externalForce)
          Adds an external force to the world.
 void addParticleEmitter(ParticleEmitter particleEmitter)
          Adds a particle emitter to the world.
 void addScript(Script script)
          Adds a script definition to the world.
protected  void addScriptBody(int index, Body b)
          Adds a body for script execution.
 Body[] addWorld(World world)
          Adds a a complete world.
 int bodyIndexOf(int id)
          Gets the index of the body.
protected  void checkCollisions()
          Checks all bodies for collisions.
protected  void collideParticles()
           
protected  Body findBody(Body b)
          Find reference to the body
 Body findBodyAt(float xFX, float yFX)
          Finds the body at position x,y.
 Body findBodyById(int id)
          Find reference to the body
protected  Constraint findConstraint(Constraint c)
          Gets reference to the constraint.
protected  float getAreaEndFX()
          Gets the end position of the area simulation.
protected  float getAreaStartFX()
          Gets the start position of the area simulation.
 Body[] getBodies()
          Gets all bodies.
 int getBodyCount()
          Gets the number of bodies.
 int getBodyEndIndex()
          Gets the end index of the currently active bodies.
 int getBodyStartIndex()
          Gets the start index of the currently active bodies.
 float getBodyTotalEnergyFX(Body b)
          Get the body energy.
 int getConstraintCount()
          Gets the number of constraints.
 int getConstraintIterations()
          Returns constraint iteration number.
 Constraint[] getConstraints()
          Gets all constraints.
 int getContactCount()
          Gets the number of current contacts.
 Contact[] getContacts()
          Gets all current contacts.
 Contact[] getContactsForBody(Body b)
          Gets all current contacts for a body.
 float getDampingLateralFX()
          Gets the lateral damping factor.
 float getDampingRotationalFX()
          Gets the rotational damping factor.
 java.util.Vector getEvents()
          Gets a vector containing all events.
 FXVector getGravity()
          Gets the gravity vector.
 float getInverseTimestepFX()
          Gets the inverse of the timestep.
 Landscape getLandscape()
          Gets the landscape object.
 java.util.Vector getParticleEmitters()
          Gets a vector containing all particle emitters.
 int getPositionConstraintIterations()
          Returns position constraint iteration number.
 Script getScript(int index)
          Gets a script.
protected  Body[] getScriptBodies()
          Gets a list of all bodies that scripts are applied to.
protected  int getScriptBodyCount()
          Gets the number of bodies that scripts are applied to.
 int getScriptCount()
          Gets the number of scripts.
protected  int[] getScriptIndices()
          Gets a list of all applied script indices.
 Script[] getScripts()
          Gets all scripts.
 ShapeSet getShapeSet()
          Gets the shape set.
 float getTimestepFX()
          Gets the timestep.
 UserData getUserData()
          Get user data.
 int indexOf(Constraint c)
          Gets the index of the constraint.
static Constraint loadConstraint(PhysicsFileReader reader, java.util.Vector bodies, UserData userData)
          Loads a constraint from a stream.
static World loadWorld(PhysicsFileReader reader)
          Loads a world from a stream.
static World loadWorld(PhysicsFileReader reader, UserData userData)
          Loads a world from a stream.
 void removeBody(Body body)
          Removes a body from the world.
 void removeConstraint(Constraint c)
          Removes a constraint from the world.
 void removeEvent(Event e)
          Removes an event from the world.
 void removeExternalForce(ExternalForce externalForce)
          Removes an external force from the world.
 void removeParticleEmitter(ParticleEmitter particleEmitter)
          Removes a particle emitter from the world.
 void removeScript(Script script)
          Removes a script from the world.
 void setConstraintIterationDynamic(boolean isDynamic)
          Sets the constraint iteration mode to dynamic/fixed.
 void setConstraintIterations(int constraintIterations)
          Sets the number of constraint iterations.
 void setDampingLateralFX(float dampingFX)
          Sets lateral damping factor (FX).
 void setDampingRotationalFX(float dampingFX)
          Sets rotational damping factor (FX).
 void setGravity(FXVector gravity)
          Sets the gravity vector.
 void setGravity(int gravity)
          Sets the gravity.
 void setLandscape(Landscape landscape)
          Sets the landscape for the world.
 void setPhysicsEventListener(PhysicsEventListener listener)
          Sets the event listener.
 void setPositionConstraintIterations(int positionConstraintIterations)
          Sets the number of position constraint iterations.
 void setSimulationArea(int start, int end)
          Sets the simulation area.
 void setTimestepFX(float timeStepFX)
          Sets the timestep.
 void setUserData(UserData userData)
          Set User data
 void tick()
          Performs a single step in the simulation.
 void translate(FXVector translation)
          Method to displace all bodies in the world by a given vector.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

M_SHAPE_MAX_VERTICES

public static final int M_SHAPE_MAX_VERTICES
See Also:
Constant Field Values

mShapeSet

protected ShapeSet mShapeSet
Shapeset managing the shapes.


mEventSet

protected EventSet mEventSet
Eventset managing the events.


mParticles

protected java.util.Vector mParticles

mForces

protected java.util.Vector mForces

mUserData

protected UserData mUserData
User data

Constructor Detail

World

public World()
Empty Constructor. Creates an empty world.


World

protected World(ShapeSet set)
Constructor with shapes. Creates an empty world using a special shape set.


World

public World(World world)
Copy constructor. Creates a deep copy of the world except for shapes, which are references.

Parameters:
world - source world object
Method Detail

getUserData

public UserData getUserData()
Get user data.

Returns:
the user data.

setUserData

public void setUserData(UserData userData)
Set User data

Parameters:
userData - the user data

loadWorld

public static World loadWorld(PhysicsFileReader reader)
Loads a world from a stream. Convenience method without user data.

Parameters:
reader - the reader.
Returns:
the loaded world.

loadWorld

public static World loadWorld(PhysicsFileReader reader,
                              UserData userData)
Loads a world from a stream. Makes use of user data.

Parameters:
reader - the reader.
userData - empty user data object
Returns:
the loaded world.

getTimestepFX

public float getTimestepFX()
Gets the timestep.

Returns:
the timestep (FX) of the simulation.

getInverseTimestepFX

public float getInverseTimestepFX()
Gets the inverse of the timestep.

Returns:
inverse of the timestep (FX) of the simulation.

setTimestepFX

public void setTimestepFX(float timeStepFX)
Sets the timestep. Simluation timestep (FX): large timestep leads to faster, but imprecise simulation The default value is 1 / 20.

Parameters:
timeStepFX - the new timestep (FX)

setConstraintIterations

public void setConstraintIterations(int constraintIterations)
Sets the number of constraint iterations. The default value is 10. Raising this value increases the simulation precision, but costs performance.

Parameters:
constraintIterations - number of iterations for constraint (default: 10)

setPositionConstraintIterations

public void setPositionConstraintIterations(int positionConstraintIterations)
Sets the number of position constraint iterations. The default value is 5. Raising this value increases the simulation precision - in particular resolution of body penetration, but costs performance.

Parameters:
positionConstraintIterations - number of iterations for position constraints (default: 5)

getConstraintIterations

public int getConstraintIterations()
Returns constraint iteration number.


getPositionConstraintIterations

public int getPositionConstraintIterations()
Returns position constraint iteration number.


setConstraintIterationDynamic

public void setConstraintIterationDynamic(boolean isDynamic)
Sets the constraint iteration mode to dynamic/fixed. The default is false. Fixed iteration mode iterates a fixed number of times (See mConstraintIterations). The dynamic mode stops when all constraints are staisfied. The iteration count still works as an upper limit.

Parameters:
isDynamic - whether the constraint iteration length is dynamic

setPhysicsEventListener

public void setPhysicsEventListener(PhysicsEventListener listener)
Sets the event listener.

Parameters:
listener - the listener.

setSimulationArea

public void setSimulationArea(int start,
                              int end)
Sets the simulation area. This defines an area along the x-axis, where the simulation is performed. Bodies outside that area are ignored. It can significantly increase simulation performance for large worlds. Only the relevant part, that is rendered to the screen is simulated. Always the whole y-dimension is computed due to the underlying optimizations.

Parameters:
start - the start coordinate of the simulation area (along the x-axis)
end - the end coordinate of the simulation area (along the x-axis)

getShapeSet

public ShapeSet getShapeSet()
Gets the shape set.

Returns:
the shape set for this world.

addWorld

public Body[] addWorld(World world)
Adds a a complete world. Bodies, Shapes, constraints and scripts form the world are added.

Parameters:
world - the elements to add to this world

addBody

public void addBody(Body body)
Adds a body to the world. The body must not be registered on any other world.

Parameters:
body - new Body.

setLandscape

public void setLandscape(Landscape landscape)
Sets the landscape for the world. Only one landscape exists, containing all landscape elements.

Parameters:
landscape - the landscape object.

getLandscape

public Landscape getLandscape()
Gets the landscape object.

Returns:
the landscape object.

addParticleEmitter

public void addParticleEmitter(ParticleEmitter particleEmitter)
Adds a particle emitter to the world.

Parameters:
particleEmitter - new particle emitter.

addExternalForce

public void addExternalForce(ExternalForce externalForce)
Adds an external force to the world.

Parameters:
externalForce - new external force.

removeBody

public void removeBody(Body body)
Removes a body from the world. This also removes all constraints, contacts and scripts relating to this body.

Parameters:
body - the body to remove.

removeConstraint

public void removeConstraint(Constraint c)
Removes a constraint from the world.

Parameters:
c - the constraint to remove.

removeScript

public void removeScript(Script script)
Removes a script from the world. This also removes all current instances of the script.

Parameters:
script - the script to remove.

removeEvent

public void removeEvent(Event e)
Removes an event from the world.

Parameters:
e - the event to remove.

removeParticleEmitter

public void removeParticleEmitter(ParticleEmitter particleEmitter)
Removes a particle emitter from the world.

Parameters:
particleEmitter - particle emitter to remove.

removeExternalForce

public void removeExternalForce(ExternalForce externalForce)
Removes an external force from the world.

Parameters:
externalForce - external force to remove.

findBodyById

public Body findBodyById(int id)
Find reference to the body

Returns:
reference to the body

findBody

protected Body findBody(Body b)
Find reference to the body

Returns:
reference to the body or null if the body does not exist in theis world

findBodyAt

public Body findBodyAt(float xFX,
                       float yFX)
Finds the body at position x,y. Note: If more than one body are occupying that place the result is not defined.

Parameters:
xFX - the x-position (FX)
yFX - the y-position (FX)
Returns:
a body at that position or null if none is there

bodyIndexOf

public int bodyIndexOf(int id)
Gets the index of the body. Note: This index can vary throughout the simulation!

Parameters:
id - identifier of the body
Returns:
the current index of the body.

findConstraint

protected Constraint findConstraint(Constraint c)
Gets reference to the constraint. Finds an equal constraint in this world.

Returns:
reference to the constraint or null if none was found.

indexOf

public int indexOf(Constraint c)
Gets the index of the constraint.

Parameters:
c - the constraint.
Returns:
the index of the constraint.

addConstraint

public void addConstraint(Constraint constraint)
Adds a constraint to the world.

Parameters:
constraint - the constrain.

addScript

public void addScript(Script script)
Adds a script definition to the world.

Parameters:
script - the script definition.

addScriptBody

protected void addScriptBody(int index,
                             Body b)
Adds a body for script execution.

Parameters:
index - the index of the script.
b - the body to which the script applies to.

addEvent

public void addEvent(Event event)
Adds an event definition to the world.

Parameters:
event - the event definition.

setGravity

public void setGravity(int gravity)
Sets the gravity. The unit is in pixel/sec^2.

Parameters:
gravity - the new gravity. The vector will be in downward direction.

setGravity

public void setGravity(FXVector gravity)
Sets the gravity vector. The gravity can point in any direction. The unit is in pixel/sec^2.

Parameters:
gravity - the new gravity.

setDampingLateralFX

public void setDampingLateralFX(float dampingFX)
Sets lateral damping factor (FX). The damping factor controls background damping of all motion.
Each lateral velocity is decelerated by that factor each timestep. Reasonable values range from 0.0..0.005.

Parameters:
dampingFX - damping factor
See Also:
FXUtil

setDampingRotationalFX

public void setDampingRotationalFX(float dampingFX)
Sets rotational damping factor (FX). The damping factor controls background damping of all motion.
Each rotational velocity is decelerated by that factor each timestep. Reasonable values range from 0.0..0.005.

Parameters:
dampingFX - damping factor
See Also:
FXUtil

tick

public void tick()
Performs a single step in the simulation. The following steps are performed.
  • Integrate Positions.
  • Check for collisions.
  • Add Forces (Gravity).
  • Solve constraint equations iteratively.


checkCollisions

protected void checkCollisions()
Checks all bodies for collisions.


collideParticles

protected void collideParticles()

getGravity

public FXVector getGravity()
Gets the gravity vector.

Returns:
the gravity vector.

getDampingLateralFX

public float getDampingLateralFX()
Gets the lateral damping factor.

Returns:
the damping factor (FX)

getDampingRotationalFX

public float getDampingRotationalFX()
Gets the rotational damping factor.

Returns:
the damping factor (FX)

loadConstraint

public static Constraint loadConstraint(PhysicsFileReader reader,
                                        java.util.Vector bodies,
                                        UserData userData)
Loads a constraint from a stream. The method decides which constraint to load and calls into the respective class.

Parameters:
reader - the file reader.
bodies - the body vector for correct referencing of bodies in the Constraint.
Returns:
the loaded Constraint.

getEvents

public java.util.Vector getEvents()
Gets a vector containing all events.

Returns:
a vector containing all events.

getParticleEmitters

public java.util.Vector getParticleEmitters()
Gets a vector containing all particle emitters.

Returns:
a vector containing all particle emitters.

getAreaStartFX

protected float getAreaStartFX()
Gets the start position of the area simulation.

Returns:
start x coordinate (FX) of the area simulation.

getAreaEndFX

protected float getAreaEndFX()
Gets the end position of the area simulation.

Returns:
end x coordinate (FX) of the area simulation.

getBodyCount

public int getBodyCount()
Gets the number of bodies.

Returns:
the number of bodies in the world.

getBodies

public Body[] getBodies()
Gets all bodies.

Returns:
a list containing bodies.

getBodyStartIndex

public int getBodyStartIndex()
Gets the start index of the currently active bodies.

Returns:
the start index of the currently active bodies.

getBodyEndIndex

public int getBodyEndIndex()
Gets the end index of the currently active bodies.

Returns:
the end index of the currently active bodies.

getConstraintCount

public int getConstraintCount()
Gets the number of constraints.

Returns:
the numberof constraints.

getConstraints

public Constraint[] getConstraints()
Gets all constraints.

Returns:
A list containing all constraints.

getContactCount

public int getContactCount()
Gets the number of current contacts.

Returns:
the number of all current contacts.

getContacts

public Contact[] getContacts()
Gets all current contacts.

Returns:
a list containing all current contacts.

getScriptCount

public int getScriptCount()
Gets the number of scripts.

Returns:
the number of scripts.

getScripts

public Script[] getScripts()
Gets all scripts.

Returns:
a list containing all scripts.

getScript

public Script getScript(int index)
Gets a script.

Parameters:
index - index of the script
Returns:
the script at the index.

getScriptBodyCount

protected int getScriptBodyCount()
Gets the number of bodies that scripts are applied to.

Returns:
the number of bodies that scripts are applied to.

getScriptBodies

protected Body[] getScriptBodies()
Gets a list of all bodies that scripts are applied to.

Returns:
a list of all bodies that scripts are applied to.

getScriptIndices

protected int[] getScriptIndices()
Gets a list of all applied script indices. This list runs along with the script body list and determines which script is applied to teh body.

Returns:
a list of all applied script indices.

getContactsForBody

public Contact[] getContactsForBody(Body b)
Gets all current contacts for a body. Note: this method is currently expensive due to object creation.

Parameters:
b - the body.
Returns:
a list containing all contacts.

translate

public void translate(FXVector translation)
Method to displace all bodies in the world by a given vector.

Parameters:
translation - vector for body translation

getBodyTotalEnergyFX

public float getBodyTotalEnergyFX(Body b)
Get the body energy. Returns the total energy (potential and kinetic) for a body. Position (0/0) is used as base line for potential energy.

Parameters:
b - the body
Returns:
the energy

Emini Physics Engine 1.3.5a API Documentation

Emini Physics Engine 1.3.5a API Documentation - Copyright 2014 Alexander Adensamer