Mercury Particle Engine Tutorial
Part 1: Introduction
Hello everyone :) In this article I would like to give you some tips about how to add special effects into your PC game. All projects in this tutorial were created using MS Visual Studio 2008 (Express Edition) and XNA 3.1 library (both are free). Helpful links you can find below:
In this tutorial I would like to tell you something about very interesting engine dedicated to special 2d effects. It is “Mercury Particle Engine” and believe me - it's awesome. Some of you can ask: “Why did you write tutorial about Mercury Particle Engine, and didn’t write one about XNA ? ”. It’s a good question. Answer is very simple – I haven't found any good tutorials about MPE in internet. Who knows, maybe someone wrote a good one, but unfortunately I haven't found it. So I decided to write one by myself. I didn’t write XNA tutorial because you can find many books about it. But who knows, maybe in the future I will write tutorial about XNA ? :) What is the conclusion ? This tutorial is for person who knows basics of C# and XNA. If you don’t know XNA or C# language, please read some tutorials about them and then return here.
Before we start please remember I’m not an MPE's expert . I’m a simply programmer and I only want to give you some tips about how to use MPE in your applications. I wrote this article because I know how hard is get information about MPE. When I started using MPE I made many mistakes. I know the most popular errors, because I was have these errors in my own applications. Fortunately, I found solutions for them. I want to save your precious time for searching information which I was looking for. So we will write a few examples using MPEs effects. Of course I recognized MPE in a basic level. If you don’t find answers for your question in this tutorial, you will need to visit official MPE forum (http://mpe.codeplex.com/discussions). I know that many people have more knowledge about this engine than me, so if you are one of them and you found something wrong, please send me a message. I will be very appreciate.
Last but not least – this tutorial is absolutely free. You can copy it, put into your website, print out to school lesson (yeah, sure :P) or translate into another language. If you insert it into your website, please put link to my website (www.chimerian.net).
LET’S START
Prolog is behind us, so we can start talking about MPE. Firstly – MPE's library can be download from official project site http://mpe.codeplex.com/ (download site: http://mpe.codeplex.com/releases). As I wrote before, projects in this tutorial were created in MS Visual Studio 2008 in C# language with XNA 3.1. It’s important to download MPE version just for XNA 3.1 – In this tutorial I will use Mercury Particle Engine 3.1 for XNA 3.1. One important thing about MPE license. As we can read in "about" file, MPE was created on Microsoft Public License (Ms-PL). That means you can used it for personal and commercial projects. Yeah – that’s great news.
When you download a package, please extract and open it. You will see three folders:
- Content,
- EffectEditor,
- Reference Assemblies.
EffectEditor folder contains:
- an ProjectMercury.EffectEditor.exe file which can be used to create special effects,
- Textures folder where are localized effects textures,
- EffectLibrary folder where are localized basic special effects.
Reference Assemblies folder contain two more folders:
- X86,
- Xbox.
First folder is for PC games, second for Xbox games. In this tutorial we will use the first one. Folder x86 contains a ProjectMercury.dll file which we will use in our all project to draw special effects.
You can also find a Documentation file in main folder. It could be very helpfully, so I recommended to look into this file when you will have some problems.
Before we create our first simple project, run ProjectMercury.EffectEditor.exe. As you can see on the screen number one, editor is divide on four regions. The First contain modifiers list, second contain all libraries, in third region we can see how effect look, and the last contain modifiers properties. Let’s start creating a basic explosion.
Pic. 01 - MPE Effect Editor screen.
To do this, click on “BasicExplosion.xml” located in second region and choose “yes” when message box will appear. Program will create the chosen special effect. When you click on black screen, you can see how effect look. Awesome, isn’t it ? This simple effect will be good enough for us, so we should save it to hard drive. To save special effect on hard disc click File->Export->Mercury Particle Engine XML (*.xml) and type name: "BasicExplosion.xml". When you do it, you can close Effect Editor and run Microsoft Visual Studio 2008. If you want to know more about Effect Editor, you should read this article: http://mpe.codeplex.com/wikipage?title=Examples&referringTitle=Documentation.
OUR FIRST PROJECT
Yes, it’s time to create our first application with MPE :). But before you will read more about that I need to tell you something interesting. Similar example you can find here: http://www.youtube.com/watch?v=44RzntYsMZ4. It’s an official video tutorial. I recommended to see it - maybe you will learn something more.
Please create new XNA Game Studio 3.1 project (note that version 3.0 is not supported by MPE). I save it as “MPE example 01” – it will be easy to identify it.
Pic. 02 – Visual Studio 2008 - New Project window.
Firstly we need to copy a ProjectMercury.dll file to our main project folder. I hope that you still remember where dll file is located. You can find it in: Mercury Particle Engine\Reference Assemblies\x86. Main project folder should looks like on the screen below.
Pic. 03 – Main project folder.
Next we need to add reference to ProjectMercury.dll file. VERY IMPORTANT – we need to add reference twice – to our program and to our content !!! Please click “Add Reference” on “References”, then click on “Browse” tab and choose ProjectMercury.dll file. Repeat it for Content\Reference. You don’t need to copy dll file to content folder. Everything is presented on pictures below:
Pic. 04 – Main project view. How to add reference.
Pic. 05 –How to add reference to dll file.
Pic. 06 –Add reference (content folder).
Now we should add some using statements to our project:
using System; using System.Collections.Generic; using System.Linq; using Microsoft.Xna.Framework; using Microsoft.Xna.Framework.Audio; using Microsoft.Xna.Framework.Content; using Microsoft.Xna.Framework.GamerServices; using Microsoft.Xna.Framework.Graphics; using Microsoft.Xna.Framework.Input; using Microsoft.Xna.Framework.Media; using Microsoft.Xna.Framework.Net; using Microsoft.Xna.Framework.Storage; // new using statements: using ProjectMercury; using ProjectMercury.Emitters; using ProjectMercury.Modifiers; using ProjectMercury.Renderers;
Good. Next we need to copy our special effect file to our project. Please copy “BasicExplosion.xml” to Content folder and add it to application (remember to change filter to “XML Files (*.xml)” if you want to see XML files).
Pic. 07 – Add existing item to project.
Pic. 08 – Add XML effect file to project.
Now we need to add textures which will be used by our special effects. Our “Basic explosion” needs following textures:
- Cloud001.png
- Particle004.png
- Particle005.png
You will find these textures in EffectEditor\Textures. Now it’s a good time to ask me “How I know which textures are needed ?”. It's simple – I read errors messages, where I had got information about missing files ;) Ok – this information was informal ;) If you want to know which files is needed, you should open XML file and find something like this:
Cloud001
where “Cloud001” is a texture name. We need to add to project files between <ParticleTextureAssetName> and </ParticleTextureAssetName>.
All of textures you should add to content just like you have added XML file (please remember to change filter to “Content Pipeline Files” – if you don’t do this, you won’t see any graphics files). When you done, we can add some code to our project. Add inside the Game class:
public class Game1 : Microsoft.Xna.Framework.Game
{
GraphicsDeviceManager graphics;
SpriteBatch spriteBatch;
Renderer particleRenderer;
ParticleEffect particleEffect;
// other code...
Next add code below to Game constructor:
public Game1()
{
graphics = new GraphicsDeviceManager(this);
Content.RootDirectory = "Content";
particleRenderer = new SpriteBatchRenderer
{
GraphicsDeviceService = graphics
};
particleEffect = new ParticleEffect();
}
Insert into LoadContent:
protected override void LoadContent()
{
spriteBatch = new SpriteBatch(GraphicsDevice);
particleRenderer.LoadContent(Content);
particleEffect = Content.Load(("BasicExplosion"));
particleEffect.LoadContent(Content);
particleEffect.Initialise();
}
Add to Update function:
protected override void Update(GameTime gameTime)
{
// Allows the game to exit
if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)
this.Exit();
MouseState ms = Mouse.GetState();
if (ms.LeftButton == ButtonState.Pressed)
{
particleEffect.Trigger(new Vector2(ms.X, ms.Y));
}
float SecondsPassed = (float)gameTime.ElapsedGameTime.TotalSeconds;
particleEffect.Update(SecondsPassed);
base.Update(gameTime);
}
And finally add code below to Draw function:
protected override void Draw(GameTime gameTime)
{
GraphicsDevice.Clear(Color.CornflowerBlue);
particleRenderer.RenderEffect(particleEffect);
base.Draw(gameTime);
}
Now compile project. If you did everything correctly, program should compile and run. Click mouse on the screen to see your new special effect :)
If you do something wrong, you can get one of these errors:
The type or namespace name 'ProjectMercury' could not be found (are you missing a using directive or an assembly reference?) – this error you will see, if you don’t add reference to program.
There was an error while deserializing intermediate XML. Cannot find type "ProjectMercury.ParticleEffect" – this error you will see, if you don’t add reference to content.
Unable to load the specified content item 'Cloud001' Please check the 'ParticleTextureAssetName' – this error you will see, if you don’t add file Cloud001.png to project content (this same error you will see if you miss Particle004.png, or Particle005.png).
XML element "Particles" not found – I saw this error when I created XNA 3.0 project. As I told you MPE isn’t compatible with XNA 3.0. Create new project, but now choose XNA 3.1.
Congratulations ! You created your first special effect. On the next lesson I will tell you something about multiple effects. Ohh, I nearly forgot – you can download this lesson as PDF file from here, and example project from here.
