Farseer Physics Engine Manual

Warning

This manual is not up to date. Use http://www.physicspoweredgames.com/FarseerPhysics/Manual2.1.htm instead.

Introduction

The Farseer Physics Engine is an easy to use 2D physics engine designed for Microsoft’s XNA and Silverlight platforms. The Farseer Physics Engine focuses on simplicity, useful features, and enabling the creation of fun, dynamic games.

Overview

Getting right to the nut, the Farseer Physics Engine is designed to control the position and rotation of game entities over time.

In the real world, things move and spin due to applied forces and torques. In Farseer, the same is true. Objects called bodies represent the real world things. As forces and torques are applied, the bodies react according to the laws of 2D physics. The position and rotation of these bodies are then used to update game entities.

In the very simplest outline it works like this:

• Create Body object
• Add Body object to simulator.
• Begin Game Loop
  • Apply forces and torques to Body.
  • Update the simulator
  • Set sprite position and rotation equal to Body position and rotation.
  • Draw game sprite
• End Game Loop

Bodies, by design, have no geometry in the 2D world and therefore have no concept of collisions.

For collision, Farseer has the Geometry object. Geometry objects are represented as 2D polygons and can be either concave or convex. They are defined by a set of vertices. One or more geometries are attached to a body in order to give the body geometrical awareness. This allows the body to participate in collisions with other bodies(actually other geometries attached to other bodies, but you get the picture.)

<todo: talk about joints, spring, and controllers>

Quick Start Sample

The following is all the code for creating 2 simple bodies with geometry and attaching them with a single revolute joint. This simple sample shows the basics of using Farseer. The rest is really just details. The actual sample can be found in the XNA samples download.

Dynamics

PhysicsSimulator

Overview

The physics simulator manages all physics objects while the simulation is running. It controls the update loop for the simulation.

Public Properties

-GeometryList

The list of geometries that are part of the simulation.
NOTE: This list should be treated as read-only. Items should not be added or removed directly from this list. Use PhysicsSimulator.Add(...) for that.

-BodyList

The list of bodies that are part of the simulation.
NOTE: This list should be treated as read-only. Items should not be added or removed directly from this list. Use PhysicsSimulator.Add(...) for that.

-JointList

The list of joints that are part of the simulation.
NOTE: This list should be treated as read-only. Items should not be added or removed directly from this list. Use PhysicsSimulator.Add(...) for that.

-ControllerList

The list of controllers that are part of the simulation.
NOTE: This list should be treated as read-only. Items should not be added or removed directly from this list. Use PhysicsSimulator.Add(...) for that.

-Vector2 Gravity

The gravity currently applied to objects in the simulation

-int Iterations

The number of internal iterations that will be used to reconscile collision and joint errors. The more iterations used the more stable the collision resolution and joints, however, there is a performance penalty that comes with larger number of iterations.

The default value is 5. If you need more stability for stacking or other situations try 10.

For more info on this property see Erin Catto's paper

-float AllowedPenetration

When two bodies collide some degree of penatration is allowed. This helps decrease oscillations and increases stability, especially of stacked bodies. This value sets the penetration that is allowed.

The default value is .01 and shouldn't need to be changed in normal operation of the engine.

For more info on this property see Erin Catto's paper

-float BiasFactor

This is a more advanced property. It controls how quick the collision error or joint error between bodies is corrected. Lower values make things a bit softer but more stable while higher values make things more rigid but prone to jitter.

This propety should always be between 0 and 1.

The default value is .8. If you need to decrease jitter, try something less than .8. .2 tends to work well.

For more info on this property see Erin Catto's paper

-int MaxContactsToDetect

When two geometries collide, the vertices of their geometries overlap eachother. Some vertices of geometry1 are inside geometry2 and vice-versa. Calculating all the vertecies that overlap takes cpu time. This property sets a maximum on the number of overlapping vertices to find. Essentially it provides a way to short-circuit the collision detection between two bodies in order it increase performance.

The default value is 5. It should not need to be changed for most situations.

-int MaxContactsToResolve

Once all collision points between two bodies are found they need to be resolved with impulses. Farseer sorts the list of collisions detected (limited by MaxContactsToDetect) by penetration depth so that it can resolve the deepest collisions first.
This property sets a maximum on the number of collision to resolve.
The default value is 2 and should be enough for most situations. Some stacking situations may require a higher value

Public Methods

-Add(Geometry)

Adds a Geometry to the simulation

-Add(Body)

Adds a Body to the simulation

-Add(Controller)

Adds a Controller to the simulation

-Add(Joint)

Adds a Joint to the simulation

-Clear()

Clears all physics objects from the simulation. More specifically, it clears Bodies, Geometries, Joints, Controllers, and the internal Arbiters.

-Geometry Collide(Vector2 point)

Checks to see if a given point collides with any geometries in the simulation. If it does, the geometry is returned. If it doesen't, null is returned.
This method is very helpful for mouse picking. Just send the mouse click position to this method and if the click collides with a geometry, the geometry will be returned and the geometry has a reference to the underlying Body.

Here is a small example: (point represents the mouse cursor position

Geometry pickedGeometry = physicsSimulator.Collide(point);
if (pickedGeometry != null) {
     LinearSpring mousePickSpring = ControllerFactory.Instance.CreateFixedLinearSpring(physicsSimulator, 
                                                      pickedGeometry.Body, pickedGeometry.Body.GetLocalPosition(point), 
                                                      point, 20, 10);
}

-Geometry Collide(X,Y)

Overload for above method

-PhysicsSimulator()

Constructor that defaults to zero gravity

-PhysicsSimulator(Vector2 gravity)

Constructor with gravity

-Remove(Geometry)

Removes a Geometry from the simulation

-Remove(Body)

Removes a Body from the simulation

-Remove(Controller)

Removes a Controller from the simulation

-Remove(Joint)

Removes a Joint from the simulation

-Update(float dt)

dt is the time in seconds.

This method steps the simulation forward in time. It should be called continuously in an update loop while the game is running.

This method assumes a fixed time step (dt). This means the value of dt should be the same each update call and it should be called with a frequency equal to dt.

For example, if you want to update the simulation at 100 frames per second, you would call update every 10 milleseconds and pass .01 (10ms converted to seconds) as your value for dt.

Example (assumes XNA):
In the Game class:

this.TargetElapsedTime = new TimeSpan(0, 0, 0, 0, 10);  //represents 10ms
this.IsFixedTimeStep = true;

In the Update

protected override void Update(GameTime gameTime) {
physicsSimulator.Update(gameTime.ElapsedGameTime.Milliseconds * .001f); //convert from ms to seconds
}

Body

Overview

Bodies are the core physics objects in Farseer. Forces, torques, and impulses are applied to bodies and the bodies react by moving realistically. Bodies do not contain any form of collision geometry by themselves.

Public Properties

-AngularVelocity

The rate at which a body is rotating

-Enabled

Sets whether or not the body will take part in the simulation. If not enabled, the body will remain in the internal list of bodies but it will not be updated.

-Force

The total amount of force that will be applied to the body in the upcoming loop. The Force is cleared at the end of every update call, so this value should only be called just prior to calling update.

This property is read-only.

-Torque

The total amount of torque that will be applied to the body in the upcoming loop. The Torque is cleared at the end of every update call, so this value should only be called just prior to calling update.

Torque can be thought of as the rotational analog of a force.

This property is read-only.

-TotalRotation

Returns the total rotation of a body. If a body spins around 10 times then TotalRotation wold return 2 * Pi * 10. This property is mostly intended for internal use by the angle joints and springs but it could be useful in some situataions for game related things.

This property is read-only

-XVectorInWorldCoordinates

Returns a unit vector that represents the local X direction of a body converted to world coordinates.

This property is read-only

-YVectorInWorldCoordinates

Returns a unit vector that represents the local Y direction of a body converted to world coordinates.

This property is read-only

Public Methods

BodyFactory

Overview

Public Methods

Arbiter

Overview

Public Methods

Joints

AngleJoint

Overview

Public Methods

FixedAngleJoint

Overview

Public Methods

AngleLimitJoint

Overview

Public Methods

FixedAngleLimitJoint

Overview

Public Methods

RevoluteJoint

Overview

Public Methods

FixedRevoluteJoint

Overview

Public Methods

PinJoint

Overview

Public Methods

SliderJoint

Overview

Public Methods

Joint

Overview

Public Methods

JointFactory

Overview

Public Methods

Controllers

AngleSpring

Overview

Public Methods

FixedAngleSpring

Overview

Public Methods

LinearSpring

Overview

Public Methods

FixedLinearSpring

Overview

Public Methods

Controller

Overview

Public Methods

ControllerFactory

Overview

Public Methods

Collision

Geometry

Overview

Public Methods

GeometryFactory

Overview

Public Methods

Vertices

Overview

Public Methods

AABB

Overview

Public Methods

Grid

Overview

Public Methods

Contact

Overview

Public Methods

Feature

Overview

Public Methods

Example Code Snippets

Here is an old document on how Farseer Collision Detection works: FarseerPhysicsDocumentation.pdf