History: PhysX Candy Wrapper

• «
• »

            The [http://eyecm-physx.sourceforge.net/|PhysX Candy Wrapper for .NET] is a wrapper library for the [http://en.wikipedia.org/wiki/PhysX|PhysX] physics engine currently owned by Nvidia, although it was originally developed by Ageia. The wrapper is open source and is designed to be integrated with the math library of your choice. 

In our case we are using the math library is built into ((MOGRE|Mogre)) due to the design of Ogre. There is a working ((MOGRE|Mogre)) binding available for download on the wrapper website. With the Mogre binding all of the wrappers methods are directly compatible with classes like Mogre.Vector3, Mogre.Quaternion, and so on. This approach makes things a lot easier and removes the need for yet another wrapper around ((NxOgre)) for example.

The first thing you'll want to do if you haven't already is download the SDK's.

!PhysX SDK
The PhysX SDK can be downloaded from the from NVidia website. The Windows version is completely free for both commercial and non-commercial use. You'll only need to pay a fee if you intend on releasing your game for the PS3, XBox or Wii. It's not open source, but it has been used in a many commercial games so it's heavily battle tested in the real world. 
http://developer.nvidia.com/object/physx_downloads.html

For some reason NVidia has stopped providing the SDK download as a direct link from the download page. You now have to sign up and go through the PhysX developer support page. My experience with this process was long, tedious and annoying. If you are in a hurry it's not hard to google a direct download link to a previous version of the SDK while your waiting for NVidia to get there act together.
http://www.softpedia.com/progDownload/NVIDIA-PhysX-SDK-Download-104786.html

!PhysX Candy Wrapper SDK
The wrapper is open source and can be downloaded from SourceForge. Although there is limited documentation, most of the code can be translated from the PhysX documentation fairly easily. There is also some bits and pieces floating around on the forums. It's my hope by making this wiki page that this situation improves. Even if the wrapper is no longer maintained, at least it's open source and can be taken over by other developers.
http://sourceforge.net/projects/eyecm-physx/files/eyecm-physx-mogre/

!Implementation
(note: the following code was taken from my current project may be missing something, if you find any errors please correct them)

The first thing you will want to do is add a reference to the PhysX candy wrapper DLL to your Mogre project. Once this is done you'll have access to the wrapped classes under the namespace Mogre.PhysX;

What I did in my game engine was create a thin physics manager class for the purpose of holding common functionality and potentially making it easier to use a different physics engine if the day comes. Firstly add this line to the top of your physics manager class.
{CODE(wrap="1", colors="c#")}
using Mogre.PhysX;
{CODE}

Next, you can add some private variables to the class that control the physics controller root and the scene (kind of like the SceneManager in Ogre).

{CODE(wrap="1", colors="c#")}        
private Physics physics;
private Scene scene;
{CODE}

Okay, that's the easy stuff out of the road. Now for the initialisation method that should be called somewhere as your game loads. I call it just after initailising Ogre.

{CODE(wrap="1", colors="c#")}
public bool Initiliase()
{            
    // create the root object
    this.physics = Physics.Create();
    this.physics.Parameters.SkinWidth = 0.0025f;

    // setup default scene params
    SceneDesc sceneDesc = new SceneDesc();
    sceneDesc.SetToDefault();
    sceneDesc.Gravity = new Vector3(0, -9.8f, 0);
    sceneDesc.UpAxis = 1; // NX_Y in c++ (I couldn't find the equivilent enum for C#)
    
    // your class should implement IUserContactReport to use this
    //sceneDesc.UserContactReport = this;

    this.scene = physics.CreateScene(sceneDesc);

    // default material
    scene.Materials[0].Restitution = 0.5f;
    scene.Materials[0].StaticFriction = 0.5f;
    scene.Materials[0].DynamicFriction = 0.5f;

    // begin simulation
    this.scene.Simulate(0);
    return true;
}
{CODE}

After that you'll want to call an Update method in your main game / rendering loop (frameStarted for example).

{CODE(wrap="1", colors="c#")}
public void Update(float deltaTime)
{
    this.scene.FlushStream();
    this.scene.FetchResults(SimulationStatuses.AllFinished, true);
    this.scene.Simulate(deltaTime);
}
{CODE}

And don't forget to be a good little programmer and clean up your resources. This should get called when your game exits. I'm not sure if it's absolutely required in managed code but it's better to be safe than sorry when we are dealing with unmanaged wrappers.

{CODE(wrap="1", colors="c#")}
public void Dispose()
{
   this.physics.Dispose();
}
{CODE}

That's about it for the basics. You're game now has a working physics engine, although, it won't do much because you haven't setup any actors or collision shapes.

!Solid things that move
To make your game more interesting, you'll want to give physical properties to the models in your game. PhysX likes to call these Actors. You set up an actor by providing it the details of it's shape, mass and if it's static or dynamic.

Strictly speaking, the physics engine knows nothing about the graphics engine in your game. You need to tell the actors from the physics engine how to move the scene nodes from the graphics engine. For this reason, you might want to create a class the ties together an actor and a scene node. When you want your physics engine to move the scene nodes around you simply call the Update method from inside your game loop.

{CODE(wrap="1", colors="c#")}
public class ActorNode
{
	private SceneNode sceneNode;
	private Actor actor;

	public ActorNode(SceneNode sceneNode, Actor actor)
	{
	    this.sceneNode = sceneNode;
	    this.actor = actor;
	}

	internal void Update(float deltaTime)
	{
	    if (!actor.IsSleeping)
	    {
		this.sceneNode.Position = actor.GlobalPosition;
		this.sceneNode.Orientation = actor.GlobalOrientationQuaternion;
	    }
	}
}
{CODE}

But before you can do anything with this class you'll need to know how to create actors. Typically speaking, you'll want to move an Entity around with an actor, although it's not required that you have an Entity attached. For example you may also want to control the camera or lights with the physics engine. To keep things simple, lets crate a sphere around the well known ogrehead.mesh.

{CODE(wrap="1", colors="c#")}
float scale = 0.1f;
int id = 0;

// graphics
Entity entity = sceneManager.CreateEntity("ogreHead" + id.ToString(), "ogrehead.mesh");
SceneNode sceneNode = sceneManager.RootSceneNode.CreateChildSceneNode();
sceneNode.AttachObject(entity);
sceneNode.Position = new Vector3(0, 10, 0);
sceneNode.Scale = Vector3.UNIT_SIZE * scale;

// physics
// attaching a body to the actor makes it dynamic, you can set things like initial velocity
BodyDesc bodyDesc = new BodyDesc();
bodyDesc.LinearVelocity = new Vector3(0, 2, 5);

// the actor properties control the mass, position and orientation
// if you leave the body set to null it will become a static actor and wont move
ActorDesc actorDesc = new ActorDesc();
actorDesc.Density = 4;
actorDesc.Body = bodyDesc;
actorDesc.GlobalPosition = sceneNode.Position;
actorDesc.GlobalOrientation = sceneNode.Orientation.ToRotationMatrix();

// a quick trick the get the size of the physics shape right is to use the bounding box of the entity
actorDesc.Shapes.Add(new SphereShapeDesc(entity.BoundingBox.HalfSize * scale, entity.BoundingBox.Center * scale));

// finally, create the actor in the physics scene
Actor actor = scene.CreateActor(actorDesc);

// create our special actor node to tie together the scene node and actor that we can update its position later
ActorNode actorNode = new ActorNode(sceneNode, actor);
actorNodeList.Add(actorNode);
{CODE}

Now all you have to do is update your actor nodes in your game loop. There are some optimisations that can be applied to this later, but lets keep it simple for now.

{CODE(wrap="1", colors="c#")}
foreach (ActorNode actorNode in actorNodeList)
	actorNode.Update(deltaTime);
{CODE}

You should be able to run your game and see the ogre head falling off the screen, of course, this isn't very useful because you don't have a floor for it to bounce off. Lets add one. Static actors like the floor or your level geometry don't need to be added to the actorNodeList because they won't move.

{CODE(wrap="1", colors="c#")}
// creating an invisible static plane is really simple
ActorDesc actorDesc = new ActorDesc(new PlaneShapeDesc());
scene.CreateActor(actorDesc);
{CODE}

If you need help, open a thread in [http://www.ogre3d.org/addonforums/viewforum.php?f=8|Mogre add-ons forum] and ask user [http://www.ogre3d.org/addonforums/memberlist.php?mode=viewprofile&u=9599|zarifus] to answer in this thread.


!See also
* [http://en.wikipedia.org/wiki/PhysX|PhysX at Wikipedia]
* More example code - http://www.stigatle.net/index.php/mogre/71-mogrephysx