Best wishes,

Captain ZSquare

Working on our games, we came across the need to do some screen-space deformations for all sorts of special effects like explosions, ‘drunk filter’, warp effects and other similar stuff. But since we’re targeting Windows Phone 7, we don’t have access to any custom shaders (which is a bummer), so we had to be creative. In the end, the solution turned out to be rather simple, and the performance is good enough (if you don’t go overboard with the effects, of course).

See the post for screen shoots and code!

Lets see if Captain ZSquare reposts this one with a screen shoot, too

XnaFlixel is a XNA 4.0 port of flixel (http://flixel.org). It's highly experimental now and I'm planning to break the whole API to make it more C#-ish. It's not tested on Xbox yet, so if you plan to use it, don't expect to much.

And a handy list of all the features of the solution:

• Suitable for side-on and top-down games
• Good for platformers, RPGs, shooters, racers, adventures - anything that needs tiles!
• Works in landscape or portrait with one line change.
• Built on the Windows Phone 7 XNA Gamestate Management engine sample.
• Uses Nick Gravelyn's content pipeline extension for the "Tiled" editor.
• Simple but flexible camera class that clamps to the map boundaries.
• Draw the whole map at once, or one layer at a time for flexibility.
• Parallax scrolling simply by adding a couple of properties to a layer in Tiled.
• An overload to draw a layer as "shadows" by drawing offset+black+semi-transparent.
• Per-pixel colour-based collision detection on specified layers/tilesets.

There's a link to the sample project on his blog, please read the rest of this post along with trying out the sample.
Source

There isnt much else to but .. Awsomesauce... you should go download it immediately.

Read direct from the source here

This tutorial shows a technique to implement a secondary 2D viewport which has a shape that does not need to be rectangular, but can be customized by the programmer. Even moving sprite shapes are possible. Utilized code techniques: secondary rendertarget (of XNA Game Studio 3.1) and an alphamap by a pixelshader (PS 2.0).

This tutorial is for beginner to intermediate level programmers. At least you should know the oo basics and know the nitty-gritty about the XNA framework. Also, basic shader programming is explained somewhere else (e. g. here: http://www.sgtconker.com/2009/11/crash-course-in-hlsl/)

What is a Secondary Viewport?

Normally games let the player watch one scene at a given time. In a jump'n'run game the player's avatar is somewhere in the middle of the screen, and the game always displays a cut-out part of the world depending on the avatar´s position. This cut-out part is the primary (main) viewport.

A secondary viewport would be some kind of a window inside of the main viewport that shows either the same scene by another view or a completely different scene.

What could a secondary viewport be useful for?

I can think of at least 5 applications:

1. Surveillance cameras: the player can behold faraway places while the screen mainly displays some totally other scene. E. g. this could be useful in multiplayer games where one could be able to place such cameras inside of the enemy´s base for spy actions.
2. Dimension gates: through the door you see a scene of some fantasy land that gets real when you enter.
3. Microscope: works by applying some magnifying factor.
4. Mirrors: as the player´s avatar walks by, the secondary viewport shows it horizontally mirrorred and somewhat displaced.
5. Special FX: do you remember the intro of some old James Bond movie, where some scenes where shown inside of the shape of a dancer? In principle this can be done with a secondary viewport, when the alpha map is a moving sprite.

These are just some suggestions for where secondary viewports are useful. Nevertheless this tutorial concentrates on showing how the shape of the viewport can be free from a rectangular nature.

Principle

The secondary viewport consists of a secondary RenderTarget object and an alphamap. The alphamap consists of a texture which defines its shape and a pixelshader that modulates pixels by the alphamap texture. The drawing process of the secondary viewport follows these steps:

1. The spectated scene gets rendered onto the secondary rendertarget.
2. A texture of the secondary rendertarget is kept. It will be drawn later on.
3. Then the main scene is drawn onto the videocard´s own rendertarget (main rendertarget).
4. Finally the texture of the spectated scene is drawn onto the main rendertarget by applying the alphamap as a shader effect.

Create the Background Scene

First we need a scene that we can spectate by the secondary viewport. Understanding the scene implementation itself is not required to comprehend the rest of the tutorial. So to avoid too much confusion we keep the scene code rather simple and encapsulate it mostly into the Star class. Since it is really easy to understand we just skim over some hotspots. Here (SecondaryViewport-SceneOnly.zip) is the code that produces the plain scene. In case you are unsure, if some code belongs to the scene or to the viewport implementation, you can compare this project and the project we will build for the viewport to see the differences.

Idea

Figure 1: Only the Scene - no secondary viewport yet

A field of randomly sized, randomly moving sprite stars will do the trick. The Game1 object will have an array of Star objects that will get updated and drawn. Figure 1 shows the resulting scene that yet misses the secondary viewport.

The Star class

To keep the scene code as far as possible separated from the code that actually implements the secondary viewport, we have the Star class. A Star object keeps track of its position, rotation, moving speed, moving direction and has a unique (also random) color. Each Star object can only move inside of a rectangular area that gets set in the constructor.

Only few things are notably about this class. First all objects share the same texture graphic. The first created Star object loads the static Texture2D member during its constructor call. The same thing applies to the Random value generator.

protected static Texture2D _texStar = null;
protected static Random _randGen = null;

These static objects get created in the constructor call of the first Star object.

if (_texStar == null)
        _texStar = game.Content.Load<Texture2D>("textures//star");
if (_randGen == null)
        _randGen = new Random();

Then in Update, the movement direction of a Star object gets reversed when the position collides with one of the initially set movement boundaries.

if (_pos.X <= _bounds.X || _pos.X >= _bounds.X + _bounds.Width) {
        _move.X *= -1.0f;
        _pos.X = MathHelper.Clamp(_pos.X, _bounds.X, _bounds.X + _bounds.Width);
}// fi
if (_pos.Y <= _bounds.Y || _pos.Y >= _bounds.Y + _bounds.Height) {
        _move.Y *= -1.0f;
        _pos.Y = MathHelper.Clamp(_pos.Y, _bounds.Y, _bounds.Y + _bounds.Height);
}// fi

Last, also in Update, the rotation gets clipped to some value inside of the range 0 to 2 pi.

_rot += (float) (_rotInc * gametime.ElapsedGameTime.TotalMilliseconds);
if (_rot < 0.0f) {
        _rot = MathHelper.TwoPi + (_rot % MathHelper.TwoPi);
} else {
        _rot = _rot % MathHelper.TwoPi;
}// fi

Creating the Scene

The Game1 object has an array of Star objects.

protected Star[] _stars;

It gets created inside of the LoadContent method. Each Star´s movement gets limited to the main window´s ClientBounds rectangle.

Rectangle rcWin = new Rectangle(0, 0, Window.ClientBounds.Width,
                                             Window.ClientBounds.Height);
_stars = new Star[_StarCount];
for (int i = 0; i < _StarCount; i++)
        _stars[i] = new Star(this, rcWin);

Note, that in LoadContent a font gets loaded ("Arial" should be available on any Windows system). It´s used for drawing some coordinates on the screen so the user can orientate easier.

_font = Content.Load<SpriteFont>("fonts\\Arial10");

Updating the Scene

Straightforward. For each Star its Update method gets called.

for (int i = 0; i < _StarCount; i++)
        _stars[i].Update(gameTime);

Drawing the Scene

Each Star has its Draw method called and now and then we draw some coordinate values.

GraphicsDevice.Clear(Color.White);
_spriteBatch.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.Immediate,
        SaveStateMode.None);
        // The stars know how to draw by themselves.
        for (int i = 0; i < _StarCount; i++)
                _stars[i].Draw(_spriteBatch);
        // For easier orientation draw some coordinate values.
        float chunksW = Window.ClientBounds.Width / 5;
        float chunksH = Window.ClientBounds.Height / 5;
        for (int x=0; x < 5; x++)
                for (int y = 0; y < 5; y++) {
                        _spriteBatch.DrawString(_font, x.ToString() + "/" + y.ToString(),
                                new Vector2(chunksW * (0.5f + x), chunksH * (0.5f + y)), Color.Black);
                }// for
        _spriteBatch.End();

Create the Alphamap Texture

Now that we have a scene, let´s create the texture for the alphamap. This texture defines the actual shape of the secondary viewport. The texture gets interpreted as a grayscale image. The darker a pixel is in this image, the more transparent the pixel of an image onto which the alphamap gets applied will be. This means a pixel of the alphamap that is completely black, will modulate an incoming pixel to be completely transparent and a pixel of the alphamap that is completely white will modulate an incoming pixel to be completely opaque (i. e. retaining its original color value).
Notes:

• The alpha value of a pixel in the alphamap texture gets ignored completely. Of course you could use the alpha value of the pixels instead of grayscale, but its easier to see the shape of the map in the image editor by using grayscale.
• You can use any image editor to create the alphamap. Personally I favour Inkscape which can be used by a GNU license. If you never worked with a vector graphics editor before you may find the following tips useful when creating the alphamap texture.

1. Show the layers

Select the main menu option "Layer / Layers..." (figure 2). It displays the "Layers" window where you can see the layers of the current Inkscape image. Think of a layer being like a transparent sheet on an overhead light projector. The "plus" button creates a new layer, the "minus" button deletes the selected layer. By clicking on the "eye" symbol everything drawn on that layer gets hidden or shown. Create a new layer and rename it by clicking on its name e. g. as "background".

Figure 2: Main menu option "Layer / Layers..." in Inkscape.

2. Create a black background

Select the "background" layer. Then click on the black color at the bottom of the Inkscape window to have black assigned as the color that fills any shape you will draw. On the left side of the Inkscape window you find the "Toolbox" toolbar. Click the "square" button ("Create rectangles and squares") and draw a square onto the image. The results should look similar to figure 3.

Figure 3: Step 2, drawing a rectangular background for the alphamap.

3. Create a sphere

Create another layer (e. g. called "alphashape"). Make sure, that layer is selected. Select the white color at the bottom of the Inkscape window. Then click the "circle" tool ("Create circles, ellipses, and arcs") in the toolbox and draw a spherical object inside of the black background rectangle. The results should look similar to figure 4.

4. Apply a gradient to the sphere shape

First show the "Fill and Stroke" colors by selecting the main menu option "Object / Fill and Stroke...". Above the "Layers" window another window named "Fill and Stroke" should be displayed now. Make sure the "Fill" tab and inside of the drawing area the white sphere are selected (You may need to click the 'select' tool ("Select and transform objects") in the toolbox first to select the sphere). Now click the 'gradient' tool ("Create and edit gradients") in the toolbox. Then press the left mouse button in the center of the white sphere and drag the cursor towards its edge. The results should look similar to figure 5. Since we want to have most of our alphamap opaque, we have to modify the gradient. Press the "Edit..." button ("Edit the stops of the gradient") of the 'tool controls' bar (figure 6). In the appearing "Gradient editor" window press the "Add stop" button. Behold new control points appearing on the gradient lines (figure 7). Close the gradient editor window and click on one of these new points to have it selected in the "Fill and Stroke" window. Now set the "Opacity, %" gauge to "100.0" (figure 8). Finally press the left mouse button onto the new gradient point and drag it towards the edge of the spherical object (figure 9).

Figure 5: Step 4a, a simple gradient applied to the sphere.

Figure 6: Step 4b, the gradient edit button.

Figure 7: Step 4c, the new points on the gradient lines.

Figure 8: Step 4d, modify new gradient step.

Figure 9: Step 4e, repositioning gradient step points.

5. Export the image as PNG

Select the black background rectangle we created in the second step. Select the main menu entry "File / Document Properties...". Inside of the appearing "Document Properties" window in the "Custom size" box press the little plus button and then the "Resize page to drawing or selection" (figure 10). Close the "Document Properties" window. Select the main menu option "File / Export Bitmap...". Press the "Page" button to have the size of the exported bitmap fixed to the page size. Press the "Browse..." button and enter a filename and storage location for the bitmap file. Also do not forget to select PNG as file format and have the filename have a ".png" suffix. Press "Save" to close the file selection dialog. Finally press the "Export" button to actually have the image exported.

Figure 10: the button to have the page resized is a little bit hidden.

6. Import the texture into the Visual C# Project

Back in the MS VC# IDE do not forget to add the alphamap image to the "Content" in the project explorer.

Implement the Viewport

Note that in this sample the main scene and the spectated scene are the same. Therefore it is not necessary to render the scene twice. Instead the main scene gets rendered once onto the texture of the secondary rendertarget, and then this texture gets rendered twice. Otherwise, if there would be many complex objects in the scene (though obviously not the case in this tutorial), the need to render the scene itself twice could become a serious performance hit.

The idea in this sample is to draw a magnified cut-out of the main scene as the secondary viewport. With the mouse you can steer the cut-out rectangle.

New Members of Game1

The Game1 class gets some new members that are necessary for the secondary viewport.
The actual secondary rendertarget. Note that this is a memory space inside of the graphics card memory.

protected RenderTarget2D _rendtarg2;

This Texture2D object that will hold the alphamap texture that we created in the last step:

protected Texture2D _texAlphamap;

The member that will hold the compiled pixel shader effect:

protected Effect _fxAlphamap;

A Rectangle member will hold the rectangular cut-out of the main scene that defines the source of the secondary viewport:

protected Rectangle _rcSrc;

Changes to the Game1 class

In Initialize the cursor gets shown to make tracing the cut-out source easier for the user.

IsMouseVisible = true;

In LoadContent we need to load the alphamap texture and shader effect.

_texAlphamap = Content.Load<Texture2D>("textures\\alphamap");
_fxAlphamap = Content.Load<Effect>("shaders\\AlphaMapping");

Also in LoadContent the secondary rendertarget is created here by calling CreateRenderTarget:

CreateRenderTarget();
[/csharp

Note that the secondary rendertarget always needs to be of the current size of the <em>GraphicsDevice</em>´s backbuffer. Therefore, if you implement some screen resolution / fullscreen mode switches you will also have to call <em>CreateRenderTarget </em>again to fit the secondary rendertarget to the new size of the backbuffer.

In <strong><em>Update </em></strong>the positional change of the mouse cursor defines the source position of the secondary viewport. The <em>MathHelper.Clamp</em> calls make sure that the source rectangle does cover space outside of the main window.
[csharp]
        // Keep track of where the mouse is and update the viewport source.
        MouseState mouse = Mouse.GetState();
        float factor = 0.33f;
        int w = (int)Math.Round(Window.ClientBounds.Width * factor);
        int h = (int)Math.Round(Window.ClientBounds.Height * factor);
        int w2 = (int)Math.Round(Window.ClientBounds.Width * factor * 0.5f);
        int h2 = (int)Math.Round(Window.ClientBounds.Height * factor * 0.5f);
        _rcSrc = new Rectangle(mouse.X - w2, mouse.Y - h2, w, h);
        _rcSrc.X = (int)MathHelper.Clamp(_rcSrc.X, 0, Window.ClientBounds.Width – w);
        _rcSrc.Y = (int)MathHelper.Clamp(_rcSrc.Y, 0, Window.ClientBounds.Height - h);

The most and most important changes to Game1 appear in Draw.

As stated above, the main scene only gets rendered once – and not onto the main rendertarget, but onto the secondary rendertarget (_rendtarg2). So before drawing our scene we need to set the secondary rendertarget as the current one. In order to be able to reset the main rendertarget to be the current one, we have to keep a reference in the local variable rtTemp.

RenderTarget2D rtTemp = null;
rtTemp = (RenderTarget2D)_graphics.GraphicsDevice.GetRenderTarget(0);
_graphics.GraphicsDevice.SetRenderTarget(0, _rendtarg2);

After regularly drawing the scene, we keep a Texture2D of what we just drew. But since GetTexture is only possible on a RenderTarget2D that is not the current one, we first have to reset to the original rendertarget.

_graphics.GraphicsDevice.SetRenderTarget(0, rtTemp);
texTemp = _rendtarg2.GetTexture();

Now we´re ready to assemble the graphical output as it is to be seen by the user. So we clear the (original) rendertarget to black (just to be safe) and paint the Texture2D that we just rendered on it. Note that the texture gets tinted into some light blue so that it´s easier to distinguish it from the secondary viewport graphics.

GraphicsDevice.Clear(Color.Black);
_spriteBatch.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.Immediate,
                              SaveStateMode.None);
_spriteBatch.Draw(texTemp,
                         Vector2.Zero, null,
                         new Color(225, 245, 255, 255),
                         0.0f, Vector2.Zero,
                         Vector2.One,
                         SpriteEffects.None, 0.0f);
_spriteBatch.End();

Finally the secondary viewport will be rendered atop of the main scene. Note that the drawing code is outsourced into a method of its own: Draw2ndViewport. Why? Admitted, in this sample it does not make much sense. But assuming you write a program build atop of this sample, which needs to have more than one secondary viewport (e. g. an ingame monitor wall with say 4 monitors showing what goes on elsewhere), it is easier to have a method dedicated to draw a single secondary viewport.
So what does Draw2ndViewport need as input?

1. rcOut defines the output rectangle of the secondary viewport, i. e. Its size and where it gets drawn at. We calculate this Rectangle just before the call of Draw2ndView.
2. rcSrc defines the rectangular cut-out source of the secondary viewport. Remember that we calculated this Rectangle in Update.
3. rcScreen is a Rectangle holding the size of the screen onto which the secondary viewport is to be drawn. It gets used for calculating mapping factors from incoming image space to output space. Here it is set to the main window´s extends. We calculate this Rectangle just before the call of Draw2ndView.
4. tex is the reference to the texture to be drawn. If drawing cut-out´s of a scene, then a single texture reference can be reused for this parameter.

So the Draw2ndView call looks like this:

Rectangle outrect = new Rectangle(
                     (int)Math.Round(Window.ClientBounds.Width * 0.25f),
                     0,
                     (int)Math.Round(Window.ClientBounds.Width * 0.5f),
                     (int)Math.Round(Window.ClientBounds.Height * 0.5f));
Rectangle screenrect = new Rectangle(0, 0,
                     Window.ClientBounds.Width, Window.ClientBounds.Height);
Draw2ndViewport(outrect, _rcSrc, screenrect, texTemp);

For now treat Draw2ndViewport as a black box. After explaining the pixelshader its workings are easier to understand, and we come back to it.

How the Pixelshader works

The alphamap pixelshader ("AlphaMapping.fx") has three parameter members that need to be set outside, before the effect can be applied.

1. float4 srcRect: these 4 float values defines the source area inside of the incoming image. The values can be between 0.0f and 1.0f as usual for texel coordinates.
2. float4 destRect: these 4 float values define the destination area inside of the shaded image. These values too are to be inside of 0.0f and 1.0f.
3. texture AlphaMap: is to hold the reference to the alphamap texture.

The shader has two samplers, the first for the incoming image and the other for the alphamap.

sampler IncomingSampler;
sampler AlphaMapSampler = sampler_state {
        Texture = <AlphaMap>;
        MinFilter = Linear;
        MagFilter = Linear;
        MipFilter = Linear;
        AddressU  = Mirror;
        AddressV  = Mirror;
};

The actual work of modulating pixels of the incoming image by corresponding pixels of the alphamap texture happens inside of the PS_AlphaMap function.

float4 PS_AlphaMap(float2 texCoord: TEXCOORD0) : COLOR

The function receives texture coordinate inside of the texture image to be processed. Again these two float values are between 0.0f and 1.0f. It returns four float values defining the color that the pixel at that coordinate position is to have.
First we get whatever color is at the original position of the incoming texture image. colOut will hold the color value that PS_AlphaMap returns.

float4 colOut = tex2D(IncomingSampler, texCoord);

Then we check, if the incoming coordinate is inside of the output area to be modulated by the alphamap.

if ((texCoord[0] >= destRect[0]) && (texCoord[0] < (destRect[0] + destRect[2])) &&
      (texCoord[1] >= destRect[1]) && (texCoord[1] < (destRect[1] + destRect[3]))){

If it is not inside of the destination area, the read color is assured to stay like it is. Therefore the a value is set to opaque.

} else {
      colOut.a = 0.0f;
}// fi

But if the coordinate is inside of the destination area, its color value gets modulated by the alphamap before returning it. Then it is necessary to respect that the source of the output color could be some other pixel than the one we currently have the coordinates for in texCoord. Depending on the size of the incoming texture image and the size of the destination rectangle the new source coordinate gets calculated and stored in newSrc. Remember that all these values are relative share values between 0.0f and 1.0f. Afterwards colOut is filled with the color of the pixel at this new coordinates in the incoming texture image.

float2 newSrc;
float shareX = (texCoord[0] - destRect[0]) / destRect[2];
float shareY = (texCoord[1] - destRect[1]) / destRect[3];
newSrc[0] = srcRect[0] + shareX * srcRect[2];
newSrc[1] = srcRect[1] + shareY * srcRect[3];
colOut = tex2D(IncomingSampler, newSrc);

Now we have to read the color value of the alphamap that corresponds to the incoming coordinates relative to the destination rectangle size.

float2 mappedTC;
float4 colAlphaMap;
mappedTC[0] = ((texCoord[0] - destRect[0]) / destRect[2]);
mappedTC[1] = ((texCoord[1] - destRect[1]) / destRect[3]);
colAlphaMap = tex2D(AlphaMapSampler, mappedTC);

Finally the current incoming color value gets modulated by the alphamap color value. This is done by simply multiplying the a parts of the colors and leaving the r, g, b of the incoming value as they are. Note that since the alphamap texture should be grayscale the r, g, b values should be the same for a single pixel in the alphamap texture. Therefore in the pixelshader only the r value of a pixel´s color is processed, r and b get ignored.

colOut.a = colOut.a * colAlphaMap.r;

Finally in the technique AlphaMapShader the Pass0 defines that the AlphaMapSampler and the PS_AlphaMap functions are to be used.

technique AlphaMapShader {
        pass Pass0 {
                AlphaBlendEnable = True;
                SrcBlend = SrcAlpha;
                DestBlend = InvSrcAlpha;
                Sampler[0] = (AlphaMapSampler);
                PixelShader = compile ps_2_0 PS_AlphaMap();
        }// Pass0
} // AlphaMapShader

Draw 2nd Viewport

So back in Game1 we only need to explain what Draw2ndView does. Actually it only sets the parameters of the pixelshader and draws the given texture image by applying the alphamap shader – all wrapped in the SpriteBatch´s Begin and End methods.
Setting the AlphaMap shader parameter:

_fxAlphamap.Parameters["AlphaMap"].SetValue(_texAlphamap);

For setting the srcRect shader parameter we first need to have the source rectangle mapped to share values between 0.0f and 1.0f relative to the texture´s size.

float[] srcRect = new float[4] {
        (float) rcSrc.X / (float)tex.Width,
        (float) rcSrc.Y / (float)tex.Height,
        (float) rcSrc.Width / (float)tex.Width,
        (float) rcSrc.Height / (float)tex.Height
};
_fxAlphamap.Parameters["srcRect"].SetValue(srcRect);

Setting the destRect shader parameter also needs mapping the values to share values, but this time relative to the output screen´s size.

float[] destRect = new float[4];
destRect[0] = (rcOut.X + rcScreen.X) / (float)rcScreen.Width;
destRect[1] = (rcOut.Y + rcScreen.Y) / (float)rcScreen.Height;
destRect[2] = (rcOut.Width) / (float)rcScreen.Width;
destRect[3] = (rcOut.Height) / (float)rcScreen.Height;
_fxAlphamap.Parameters["destRect"].SetValue(destRect);

After setting these parameters drawing the given texture by applying the shader is straightforward just like with other shaders.

_fxAlphamap.CurrentTechnique = _fxAlphamap.Techniques["AlphaMapShader"];
_fxAlphamap.Begin();
_fxAlphamap.CurrentTechnique.Passes[0].Begin();
        _spriteBatch.Draw(tex,
                        new Vector2(),
                        null,
                        Color.White,
                        0.0f, Vector2.Zero,
                        Vector2.One,
                        SpriteEffects.None, 0.0f);
_fxAlphamap.CurrentTechnique.Passes[0].End();
_fxAlphamap.End();

Figure 11 shows what the result looks like.

Figure 11: the scene with a magnifying secondary viewport.

Find the sample code here: SecondaryViewport.zip.

Ideas for Extensions

Homework for you!

• The mousewheel could steer the zoom. The zoom is controlled by the size of the rectangle defining the cut-out of the main scene.
• Of course the spherical form of the alphamap is only a suggestion. It´s easy to reproduce, therefore it seemed appropriate for this tutorial. Actually having a completely customized alphamap shape is what this tutorial is about – go ahead and change it to whatever form you like!
• As mentioned in the intro, the alphamap could also be a moving 2D sprite. I extended the sample of this tutorial to reflect, how this could be established. You can get the code here: SecondaryViewport-MovingSprite.zip.

License

This text and any referred code is licensed under a "Creative Commons Attribution 3.0 Unported" license, which can be read here: http://creativecommons.org/licenses/by/3.0/

The author of all text, any code and any assets found in this tutorial likes to be referred by Harry Trautmann, http://codemachinery.net

Today I’m going to introduce you to a neat 2D physics engine for XNA called Farseer. With the help of this 2D physics engine we are going to create a small platform ‘game’ while introducing the important concepts of Farseer like bodies, geometry, joints and springs.

By the end of the tutorial, you'll be able to build something like:

Set-up

Before we can get started please download the latest stable release at http://farseerphysics.codeplex.com (at the time of writing that was 2.1.3) and extract the solution somewhere. Now also download the “Added motor to RevoluteJoint and FixedRevoluteJoint” patch at http://farseerphysics.codeplex.com/Project/Download/FileDownload.aspx?DownloadId=70619. You will find two files in the archive (RevoluteJoint.cs and FixedRevoluteJoint.cs) extract these and copy these over the files in “Farseer Physics 2.1.3 XNA\Dynamics\Joints”.

Creating a project

Now let’s fire up Visual Studio and create a new XNA 3.1 Windows Game project, call it anything you like. I’ve called it “FarseerPlatformer”. Now add the Farseer project to our solution: right click the our solution in the solution explorer and select “Add existing project”, then browse to where you’ve extracted Farseer and select the FarseerPhysicsXNA.csproj.

Now add a reference to the FarseerPhysicsXNA project in your own project by right clicking the References folder in the solution explorer and choosing “Add reference”. Then select FarseerPhysicsXNA from the tab “Projects” and press ok.

If your solution explorer now looks like the picture on the left we’re ready to try and compile. Hit F6 on your keyboard. There should be no errors.

My  first physics

The physics simulator class is the heart of the Farseer physics engine and will control all our physics objects. Let’s create one!

Open Game1.cs and add the following using statements at the top of the file.

using FarseerGames.FarseerPhysics;
using FarseerGames.FarseerPhysics.Dynamics;
using FarseerGames.FarseerPhysics.Factories;
using FarseerGames.FarseerPhysics.Collisions;

Now let’s create a PhysicsSimulator called physics. Add this definition at the top of the class.

PhysicsSimulator physics;

And instantiate it by adding the following line to the end of the constructor.

physics = new PhysicsSimulator(Vector2.UnitY * 500);

This will create a new physics simulator with a predefined gravity of (0, 500) which means that there is a constant force of strength 500 pushing everything down. 500 here is just an arbitrary number, play around with this value as much as possible to tweak the feel of your games.

All we need todo to make the physics simulator work is making it update every frame by adding the following line at the end of the Update method.

physics.Update((float)gameTime.ElapsedGameTime.TotalSeconds);

So that’s it. We’re done! But well, you can’t actually see anything yet. Let’s make a very simple class called PhysicsObject. I will not put down the entire class right here, see the source code for that. However there is one method that deserves special attention:

protected virtual void SetupPhysics(PhysicsSimulator physics,
            Vector2 position, float width, float height, float mass)
        {
            body = BodyFactory.Instance.CreateRectangleBody(physics,
                                                width, height, mass);
            body.Position = position;

            geom = GeomFactory.Instance.CreateRectangleGeom(physics,
                                                body, width, height);
            geom.FrictionCoefficient = 0.5f;
        }

In this method we create the ‘physical representation’ for our new object. For this we need two fields: body of type Body and geom of type Geom. Body represents a handle which we can push and pull and apply all sorts of forces to. Geom (short for geometry) handles the actual collisions and friction. Both objects fire numerous events which you can handle, the most useful one is geom’s OnCollision event that we will use in the final chapter.

Instantiating them is very easy. Just use the apropiate factory class to get a new instances, make sure to always choose the overload that also asks for a PhysicsSimulator object so that your object is automatically registered in the simulation. Also note that the PhysicsSimulator uses the center of an object as its position, while the SpriteBatch uses the top left corner normally, take this into account when drawing by setting the origin to the center of the texture when using the SpriteBatch.
Add a texture to your content project and quickly instantiate a new PhysicsObject like this:

squareTex = Content.Load<Texture2D>("square");
box = new PhysicsObject(physics, new Vector2(100, 0), 64, 64, 10, squareTex);

Then add the following lines to the draw method in Game1.

spriteBatch.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.Immediate,
                                              SaveStateMode.SaveState);
box.Draw(spriteBatch);
spriteBatch.End();

If you run the simulation now you should see a falling square. Nifty isn’t it?

Laying grounds

Now we need to make some ground that will stop our square from falling down at terminal velocity. To do this we’re going to make a static body. This means that the body is unaffected by all forces but still is in our simulation, handy for making immovable objects like ground and walls. To do this neatly we will make a new class that inherits from the PhysicsObject class. Call this class StaticPhysicsObject.
Because of inheritance all we have to write in this new clas is this:

    public class StaticPhysicsObject : PhysicsObject
    {
        public StaticPhysicsObject(PhysicsSimulator physics, Vector2 position, float width, float height, Texture2D texture)
            : base(physics, position, width, height, 1, texture)
        {
            body.IsStatic = true;
        }
    }

Note how we always pass a mass of 1, mass isn’t important for a static object.

Create a new field StaticPhysicsObject ground in Game1 and instantiate it in LoadContent like this:

ground = new StaticPhysicsObject(physics, new Vector2(GraphicsDevice.Viewport.Width / 2, 500), GraphicsDevice.Viewport.Width, 64, squareTex);

Don’t forget to draw it in the Draw method.

You should now see a square falling down and stopping when it hits our new ground.

Joints

Let’s make the simulation a bit more interesting by creating a see-saw. Quickly add two more PhysicsObjects, instantiate them like this:

            seeSawBottom = new PhysicsObject(physics, new Vector2(175, 300), 50, 50, 1000, squareTex);
            seeSawTop = new PhysicsObject(physics, new Vector2(175, 200), 300, 30, 25, squareTex);

And write some draw code. Now let’s fire up the simulation again. You will now see our original block smash hard into our see-saw, rolling out of screen while the see-saw almost falls apart.

This looks awesome, however we would like the see-saw to behave as one object, so let’s introduce a joint. A joint is a way of fixing two bodies or a body and the background together (like an axel that connects a wheel to a car). There are multiple types of joints. For an explantion of the different types of joints see this page: http://www.farseergames.com/storage/farseerphysics/Manual2.1.htm#_Toc213068491

We are going to create a revolute joint, that fixes two bodies together but still alows them to rotate independently, very handy for a see-saw or a wheel. To demonstate this we will create a new class called CompositePhysicsObject as below:

public class CompositePhysicsObject
    {
        public CompositePhysicsObject(PhysicsSimulator physics, PhysicsObject poA, PhysicsObject poB, Vector2 relativeJointPosition)
        {
            this.poA = poA;
            this.poB = poB;

            joint = JointFactory.Instance.CreateRevoluteJoint(physics, poA.body, poB.body, poA.Position + relativeJointPosition);
            poA.geom.IgnoreCollisionWith(poB.geom);
            poB.geom.IgnoreCollisionWith(poA.geom);
        }

        public virtual void Draw(SpriteBatch spriteBatch)
        {
            poA.Draw(spriteBatch);
            poB.Draw(spriteBatch);
        }

        protected RevoluteJoint joint;
        protected PhysicsObject poA;
        protected PhysicsObject poB;
    }

Just as with the bodies and geoms we create a joint with a factory. Creating a revolute joint is very easy, the second body is attached to the first body at the absolute (world) position. To make it easier to create a composite physics object we are using a relative position (or offset) from the first body. Note that you will have to make sure yourself that the bodies overlap, the second body will not be moved by creating a joint. (Note: bodies don’t have to overlap to be fixed together by joints, but this will look pretty funny).

We also need to make sure that the geometries of both physics objects do not register colliding with each other; else we would get some very buggy results.

Let’s go back to the Game1 class, add a field called seeSaw of type CompositePhysicsObject and change the load content method to look like this:

protected override void LoadContent()
        {
            spriteBatch = new SpriteBatch(GraphicsDevice);
            squareTex = Content.Load<Texture2D>("square");
            box = new PhysicsObject(physics, new Vector2(100, 0), 64, 64, 10, squareTex);
            seeSawBottom = new PhysicsObject(physics, new Vector2(175, 300), 50, 50, 1000, squareTex);
            seeSawTop = new PhysicsObject(physics, new Vector2(175, 285), 300, 30, 25, squareTex);
            seeSaw = new CompositePhysicsObject(physics, seeSawTop, seeSawBottom, new Vector2(0, 15));
            ground = new StaticPhysicsObject(physics, new Vector2(GraphicsDevice.Viewport.Width / 2, 500), GraphicsDevice.Viewport.Width, 64, squareTex);
        }

Also update the drawing method:

protected override void Draw(GameTime gameTime)
        {
            GraphicsDevice.Clear(Color.CornflowerBlue);
            spriteBatch.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.Immediate, SaveStateMode.SaveState);
            box.Draw(spriteBatch);
            seeSaw.Draw(spriteBatch);
            ground.Draw(spriteBatch);
            spriteBatch.End();
            base.Draw(gameTime);
        }

Run, you will now have a box dropping on a fully functional see-saw.

Springs

You know what would be even cooler? If our see-saw would have a spring that would make our see-saw come back up again after our falling box hits it. With Farseer you can make numerous types of springs, for a full overview see the Springs section in the manual here: http://www.farseergames.com/storage/farseerphysics/Manual2.1.htm#_Toc213068498

To improve our see-saw we are going to use an AngleSpring. This type of spring tries to keep two objects (or one object and the background) at a specified angle by applying a specified amount of torque (or less).

Let’s create a new class that inherits from our CompositePhysicsObject class. I couldn’t think of a decent name for it, so I just called it SpringPhysicsObject. This new class will compose two physics objects together (just as before) but will now also add an angle spring to try and keep two objects at a specified angle. (If you want to force two objects to always stay at a specified angle of each other you should use an angle joint, and if you want one object to always stay at a specified angle, use a fixed angle joint).

public class SpringPhysicsObject : CompositePhysicsObject
    {
        public SpringPhysicsObject(PhysicsSimulator physics, PhysicsObject poA, PhysicsObject poB, Vector2 relativeJointPosition, float springForce, float springDampening)
            : base(physics, poA, poB, relativeJointPosition)
        {
            angleSpring = SpringFactory.Instance.CreateAngleSpring(physics, poA.body, poB.body, springForce, springDampening);
            angleSpring.MaxTorque = springForce;
        }

        protected AngleSpring angleSpring;
    }

As you can see we again don’t need to write a lot of code since inheriting from CompositePhysicsObject will already join our two bodies together. All we need to do is to create a new angle spring, as always via a factory. I think spring force and spring dampening speak for themselves. MaxTorque is the maximum amount of torque that will be applied to stay at the given angle. Note that you usually need very high values for spring force to make this work properly (just as in real life).
Now that we have this new SpringPhysicsObject, replace our CompositePhysicsObject and instantiate it like this in the LoadContent method.

seeSaw2 = new SpringPhysicsObject(physics, seeSawTop, seeSawBottom, new Vector2(0, 15), 10000000, 10000);

Also update the draw method.
Now run the simulation and see how our see-saw behaves now!

Force

Now what if we want to control the falling box? Maybe make it move a little, have it jump up and down, etc.
To do this we need to apply force to our object. To demonstrate this we’re going to make a new class called Character that inherits from PhysicsObject.

public class Character : PhysicsObject
    {
        public Character(PhysicsSimulator physics, Vector2 position, float width, float height, float mass, Texture2D texture)
            : base(physics, position, width, height, mass, texture)
        {
        }

        public virtual void Update(GameTime gameTime)
        {
            HandleInput(gameTime);
        }

        protected virtual void HandleInput(GameTime gameTime)
        {
            keyState = Keyboard.GetState();

            //Apply force in the arrow key direction
            Vector2 force = Vector2.Zero;
            if (keyState.IsKeyDown(Keys.Left))
            {
                force.X -= forcePower * (float)gameTime.ElapsedGameTime.TotalSeconds;
            }
            if (keyState.IsKeyDown(Keys.Right))
            {
                force.X += forcePower * (float)gameTime.ElapsedGameTime.TotalSeconds;
            }
            if (keyState.IsKeyDown(Keys.Up))
            {
                force.Y -= forcePower * (float)gameTime.ElapsedGameTime.TotalSeconds;
            }
            if (keyState.IsKeyDown(Keys.Down))
            {
                force.Y += forcePower * (float)gameTime.ElapsedGameTime.TotalSeconds;
            }

            body.ApplyForce(ref force);

            oldState = keyState;
        }

        public float forcePower;
        protected KeyboardState keyState;
        protected KeyboardState oldState;

    }

As you can see force is easily applied just by constructing a force vector and calling body.ApplyForce(). We pass the vector by reference so that the garbage collector doesn’t have to jump in and act too often (since Vector2 is a value type, its normally copied each time it’s passed to a different method, don’t worry too much about that right now).
You can apply impulse in the same way. (Impulse is direct, useful for jumping and explosions, while force is steadily added, more useful to make a jetpack work for example).
Let’s play: in Game1 replace our box of type PhysicsObject with a box of type Character. Set box.forcePower to 1000000. Also add box.Update(gameTime); to the Update method in Game1 and make sure the box is being drawn.
If you did everything correct you should now be able to control the falling box with the arrows on your keyboard.

A game character

Now we’ve got all of the basics covered it’s time to talk about creating a more realistic game character. Without physics you would move an object by changing its position when a key is pressed. Jumping would be done by creating two ‘fake forces’ that sent the object up and down. When using a physics engine you shouldn’t just move your character, this will make it very hard for Farseer to handle collisions because for Farseer it looks like the character just teleported a tiny amount (there are no forces, impulses or torque present). For a realistic character we need to apply forces to a body, however this causes a problem: how much force do we apply? Do we keep applying forces (e.g. the character keeps accelerating)? This sounds very unrealistic, as a normal person quickly accelerates in just a few steps and then stays at his running speed. We could do with impulses, that instantly generate movement, however stopping the character is going to be even more problematic then. And if we encounter a slope or if the friction is not set to 0 the character will slow down until the user releases and presses the move key again.
Suffice it to say that I’ve been trying all sorts of stuff for two days to get a character moving the way I want it (instant start and stop, controllable air movements, steady running speed, also characters normally don’t fall over).
Luckily I came across Bryan Dismas’ blog who wrote an article on this http://amazingretardo.simiansoftwerks.com/2010/02/17/platformer-character-control-farseer-physics-engine/. He adopted this idea from Robert Dodd (http://boxycraft.wordpress.com) and I’m going to change it even further.

Image by Robert Dodd

The idea is to create a character from two parts: the upper body is just a simple rectangle. The lower body is a circle/wheel that we rotate so that we can move around and climb slopes without problems. We’re going to create a slightly simpler version of this.

• Upper body: a rectangle body always kept up-right using a fixed angle joint.
• Lower body: a circle connected to the upper body using a revolute joint.

With the current version of Farseer this is enough to have a nice character jumping around. So let’s write some code.
Create a class called CompositeCharacter which inherits from Character.
The class is fairly long because I also had to add a bit of state management to make walking, jumping and moving in-air work. However for this tutorial the most important is the overloaded method SetupPhysics that is listed here below.

protected override void SetupPhysics(PhysicsSimulator physics, Vector2 position, float width, float height, float mass)
        {
            //Create a body that is almost the size of the entire object
            //but with the bottom part cut off.
            float upperBodyHeight = height - (width / 2);
            body = BodyFactory.Instance.CreateRectangleBody(physics, width, upperBodyHeight, mass / 2);
            //also shift it up a tiny bit to keep the new object's center correct
            body.Position = position - Vector2.UnitY * (width / 4);
            centerOffset = position.Y - body.Position.Y; //remember the offset from the center for drawing

            //Now let's make sure our upperbody is always facing up.
            fixedAngleJoint = JointFactory.Instance.CreateFixedAngleJoint(physics, body);

            //Create a wheel as wide as the whole object
            wheelBody = BodyFactory.Instance.CreateCircleBody(physics, width / 2, mass / 2);
            //And position its center at the bottom of the upper body
            wheelBody.Position = body.Position + Vector2.UnitY * (upperBodyHeight / 2);

            //These two bodies together are width wide and height high 
            //So let's connect them together.
            motor = JointFactory.Instance.CreateRevoluteJoint(physics, body, wheelBody, wheelBody.Position);
            motor.Motor_Enabled = true;
            motor.Motor_MaxTorque = 1000f; //set this higher for some more juice
            motor.Motor_Speed = 0;

            //Create geomitries.
            wheelGeom = GeomFactory.Instance.CreateCircleGeom(physics, wheelBody, width / 2, 16);
            geom = GeomFactory.Instance.CreateRectangleGeom(physics, body, width, upperBodyHeight);

            wheelGeom.IgnoreCollisionWith(geom);
            geom.IgnoreCollisionWith(wheelGeom);

            //Set the friction of the wheelGeom to float.MaxValue for fast stopping/starting
            //or set it higher to make the character slip.
            wheelGeom.FrictionCoefficient = float.MaxValue;
        }

Quite a lot is happening here, but nothing should be really new. We first create a body that is going to be the upper part of our character, we then shift its position a bit and calculate its shift from the center. (This is handy for if we want to draw our final character). A simple fixed angle joint keeps our upper body at all times.

We then create the lower body (wheelBody) which is sized like a wheel just as wide as our upper body. Its center is positioned at the bottom of the upper body (see the picture above again).

The lower body is fixed to the upper body with a revolute joint, and because we downloaded the ‘motor’ patch we can force the lower body to rotate while it stays attached to the upper body. If you think about we’ve just created a Segway actually.
Geometries are created as usual and the upper and lower bodies are told not to collide with each other.

Finally we set the friction of the lower body to the highest possible value. This way the movement of our character will be very responsive. You can lower the amount of friction for a different feel (be sure to play around a bit, 0.5f gives quite a funny feel).

Congratulations, you’re now familiar with the basics of the Farseer physics engine. Be sure to fire up the simulation and play around a bit. Maybe try to make a more complicated level with the objects you now have.

Afterthoughts

You now have a bit of a grasp on the techniques that the Farseer physics engine offers you. This engine could easily be extended to make even more fun physics objects, like moving platforms. However because this is a tutorial, some things in the code have been neglected, so if you would like to extend the tutorial code, please first make sure that you make some kind of base object, of which CompositePhysicsObject and PhysicsObject extend. Then make some sort of drawing manager, this will make your life a lot easier!
This tutorial has shown you a few useful tricks like Polymorphism (a Character is still a PhysicsObject) which saves writing a lot of duplicate code. Make sure that you use these techniques to the max they will make your life a lot easier!
I hope you’ve enjoyed this tutorial, for more of my tutorials see www.roy-t.nl.

Download sample source: FarseerPlatformer.zip (under the MS-PL License)

When you look around the XBox Indie Games Channel, there aren't a lot of 3D games around. Most XNA games only feature 2D graphics. I hope to contribute with this tutorial to making 3D graphics a bit less intimidating. And maybe the little prototype we will create throughout the next pages will be the starting point of a great 3D indie game by one of you

We will make a prototype that features the kind of rolling world effect that you can see in games such as Animal Crossing or DeathSpank. We will also create the textures and 3D models that go along with the rolling effect and recreate the combination of 2D art with a 3D world you can see in the game DeathSpank.

Difficulty

This tutorial is intended for Beginner/Intermediate developers.
If you played around with XNA and /or worked on 2D games before this tutorial should be no problem for you.

Content

The first section of this tutorial covers the creation of the assets for our game.
We will draw textures for the world, for the trees and a very simple one for the hero.
We will also create a simple DirectX effect file which we will use to render the models we create in SoftImage Mod Tool.
Once we have all the assets we will set up our game project in Visual Studio, load and render game objects and then move the hero of our game around.
In the last section we will add the rolling world effect. We will develop a concept of the effect with sketches and pseudo-code and then implement the effect.
Finally, there is some bonus content you might try once you are done with the tutorial.
This tutorials comes with pre-made assets in case you are only interested in the programming side of the tutorial. You can also skip the foreplay completely and jump to the rolling world effect part using the project in the folder WorldGame.
You can also explore for yourself with the complete rolling world game in the folder RollingWorldGame.

Software

Visual C# 2008 Express

The Visual Studio 2008 Express is a free set of tools for developing applications for Windows.
Download Visual C\# 2008 Express

XNA Game Studio 3.1

This software package contains the XNA framework which includes an extensive set of class libraries specific to game development. Once you installed the Game Studio you can use it in Visual Studio:
Microsoft XNA Game Studio 3.1

Paint.NET

Paint.NET is free image and photo editing software for Windows. We will use it to create textures for our game:
Download Paint.NET

SoftImage Mod Tool

We will be using Autodesk SoftImage Mod Tool to create the 3D models. The version we will use is for non-commercial use only which is fine for this tutorial:
Download Autodesk Softimage Mod Tool

Feedback

My name is Christian Schlager and I wrote this tutorial. If you like it, have constructive feedback or found a mistake in the tutorial please leave a comment here, or on my page: http://googoobachoo.blogspot.com

Downloads

This tutorial is accompanied by the following downloads:

WorldGame.zip
RollingWorldGame.zip
Assets.zip

Next Page: Creating the assets