Quick Start Guide for Farseer.BMX

This is a quick and dirty ‘how-to’ on getting users new to Farseer.BMX up and running a basic application that compiles with the Farseer Physics Engine. To speed up the start-up development time we’ll be using some support classes that come from the physics demo source code. If you’ve downloaded the original source code from this then you should see a QuickStart.bmx in the zip file that goes through what this guide will be explaining. Otherwise if you’ve ‘acquired’ the source by other means then read on ;). In the end you’ll have a basic blitzmax app that looks like this:

Setup

You’ll need the full farseer source code along with the demo source code to complete this guide. Reason being, is instead of writing a lot of support code to ‘render’ physics objects properly we’ll be using the physics simulator viewer type that renders a ‘debug’ version of the engine.

So lets begin…

The BMX File

We start out by creating a new blitzmax code file. Let’s call it ‘QuickStart.bmx‘. At the top of the file we put:

[blitzmax2]
SuperStrict
Import “source/DemoLib.bmx”

‘ setup our graphics device and render settings
Graphics 800,600
SetClsColor(64,156,233)
SetBlend(ALPHABLEND)
[/blitzmax2]

Make sure the import statement in your code is pointing correctly to wherever DemoLib.bmx is. Next we’ll declare and initialize a few globals:

[blitzmax2]
‘ create an instance of the physics engine
‘ and the physics engine viewer so we can see our objects.
Global physics:TPhysicsSimulator
Global viewer:TPhysicsSimulatorView

‘ setup our physics with a gravity of 100 and initialize the viewer
physics = TPhysicsSimulator.Create(Vector2.Create(0,100))
viewer = TPhysicsSimulatorView.Create(physics)
physics.EnableDiagnostics = True ‘ with this true the engine will calculate timing information for benchmarking
[/blitzmax2]

physics is the Farseer Physics Engine that manages all body and geometry. Now that our physics engine is constructed we’ll create a ‘box’ body and a floor for the box to sit on. Below is the code for the box body:

[blitzmax2]
‘ create a basic box body with a mass of 1 and a geometry to match it.
Global body:TBody = TBodyFactory.CreateRectangleBody(physics, 100, 100, 1)
TGeomFactory.createRectangleGeom(physics, body, 100, 100)
body.SetPosition(Vector2.Create(400,300)) ‘ then put it at the center of the screen
[/blitzmax2]

What you see above is the main way to construct bodies and geometry for Farseer. There is a TBodyFactory, TGeomFactory, TJointFactory, and TControllerFactory. Each of them have several functions to allow you to easily compose objects. I recommend you stick to using them, as they’ll condense the amount of code you’ll write compared to constructing objects manually. Manually initializing physics objects works as well, but requires you to know how to construct each object. Easy is better right?

Alright, lets make the floor the same way:

[blitzmax2]
‘ create a floor so our body just doesn’t fall off the screen.
Local floorBody:TBody = TBodyFactory.CreateRectangleBody(physics,800,200,1)
TGeomFactory.CreateRectangleGeom(physics, floorBody, 800, 200)

‘position our floor
floorBody.SetPosition(Vector2.Create(400,500))
‘ set it to static so the floor has an ‘infinite mass’ and doesn’t budge.
floorBody.SetStatic(True)
[/blitzmax2]

The above numbers 800 and 200 represent the width and height respectively. We set the floor to ‘static‘ so when objects collide against it, the floor will not move. Static bodies are good for setting up game level objects such as platforms, rooms, etc…

Now that we have these objects initialized let’s write a basic game loop in blitzmax below that code:

[blitzmax2]
‘ a basic update/draw loop
While Not(KeyHit(KEY_ESCAPE))

Update()
Cls
Draw()
Flip
Wend
[/blitzmax2]

Nothing special here. Trying to compile now and you’ll get an error because Update() and Draw() aren’t implemented yet. Let’s start with Draw() since it’s the easiest:

[blitzmax2]
‘ just draw our viewer 😀
Function Draw()
viewer.Draw()
End Function
[/blitzmax2]

Pretty easy eh? Now our update function isn’t any harder:

[blitzmax2]
Function Update()
‘ update our physics engine
‘ with a given time step.
physics.Update(.01)

‘ some controls to move our body
‘ to make things interesting 🙂
Local force:Vector2 = Vector2.Zero()
Local speed:Float = 1000
If KeyDown(KEY_UP) Then
force.Y = -speed
End If
If KeyDown(KEY_DOWN) Then
force.Y:+speed
End If
If KeyDown(KEY_LEFT) Then
force.X:-speed
End If
If KeyDown(KEY_RIGHT) Then
force.X:+speed
End If
body.ApplyForce(force)

‘ apply a little torque
body.ApplyTorque(900)
End Function
[/blitzmax2]

Make sure to call physics.Update(delta:float) to update the physics bodies positions and collisions. I added some basic key hit handling to move the ‘box’ around by calling ApplyForce(). I threw in an ApplyTorque() to have the body slowly rotate to make things interesting :).

For those that just want the entire code in one go here it is:

[blitzmax2]
SuperStrict
Import “source/DemoLib.bmx”

‘ setup our graphics device and render settings
Graphics 800,600
SetClsColor(64,156,233)
SetBlend(ALPHABLEND)

‘ create an instance of the physics engine
‘ and the physics engine viewer so we can see our objects.
Global physics:TPhysicsSimulator
Global viewer:TPhysicsSimulatorView

‘ setup our physics with a gravity of 100 and initialize the viewer
physics = TPhysicsSimulator.Create(Vector2.Create(0,100))
viewer = TPhysicsSimulatorView.Create(physics)
physics.EnableDiagnostics = True ‘ with this true the engine will calculate timing information for benchmarking

‘ create a basic box body with a mass of 1 and a geometry to match it.
Global body:TBody = TBodyFactory.CreateRectangleBody(physics, 100, 100, 1)
TGeomFactory.createRectangleGeom(physics, body, 100, 100)
body.SetPosition(Vector2.Create(400,300)) ‘ then put it at the center of the screen

‘ create a floor so our body just doesn’t fall off the screen.
Local floorBody:TBody = TBodyFactory.CreateRectangleBody(physics,800,200,1)
TGeomFactory.CreateRectangleGeom(physics, floorBody, 800, 200)

‘position our floor
floorBody.SetPosition(Vector2.Create(400,500))
‘ set it to static so the floor has an ‘infinite mass’ and doesn’t budge.
floorBody.SetStatic(True)

‘ a basic update/draw loop
While Not(KeyHit(KEY_ESCAPE))

Update()
Cls
Draw()
Flip
Wend

Function Update()
‘ update our physics engine
‘ with a given time step.
physics.Update(.01)

‘ some controls to move our body
‘ to make things interesting
Local force:Vector2 = Vector2.Zero()
Local speed:Float = 1000
If KeyDown(KEY_UP) Then
force.Y = -speed
End If
If KeyDown(KEY_DOWN) Then
force.Y:+speed
End If
If KeyDown(KEY_LEFT) Then
force.X:-speed
End If
If KeyDown(KEY_RIGHT) Then
force.X:+speed
End If
body.ApplyForce(force)

‘ apply a little torque
body.ApplyTorque(900)
End Function

‘ just draw our viewer
Function Draw()
viewer.Draw()
End Function
[/blitzmax2]

And that is all there is to it. Hope you enjoy the engine, and I hope to see some awesome games made with it!

3 comments

Leave a Reply

Your email address will not be published. Required fields are marked *