Betajaen's quick guide to porting 0.6 code to NxOgre 0.9

Hi Sports Fans!

These tips and code snippets are to help you get your current 0.4RC3/0.6 code over to massive changes in NxOgre 0.9. Please join in with your own things if you like, but any questions would you take to a seperate thread. I like things clean.

So here we go:

The Basics
- Classes names use CamelCase; World, Scene, SceneParams, CharacterMovementVectorController

- Everything is in SI units; metres, kilograms and newtons.

Actors

- Actor is equivalent to NxActor.
mBody->createActor("myActorName"new SphereShape(0.5f), Vector3(5,10,5), "mass: 10");

- Bodies are Actors with a scene node.

mBody->createBody("myActorName;meshName.mesh"new SphereShape(0.5f), Vector3(5,10,5), "mass: 10");

- Actors don't have scene nodes.

- Most parts of NxOgre deal with Actors, so you need to quickly swap between them:- Actor* a = static_cast<Actor*>(myBody), Actor* myBody = mScene->createBody(..);

- Static bodies are created using params;

mBody->createBody("nx.sphere.50cm.mesh", new SphereShape(0.5f), Vector3(5,10,5), "Static: Yes");

- Bodies use the mesh name as the name (and make one up if it's already taken), Actors use the name given. This feature will be extended in the future to allow custom names to bodies, without breaking the interface.

Debugging and the Error System

- There is no DebugOverlay and DebugNode, it's been taken out, gone, exploded, finished, buried and composted. Use the PhysX Remote Debugger instead!

- Run the PhysX Remote Debugger on your computer or another on a home or business network, you connect to it via the IP address:

mWorld->getPhysXDriver()->getSDK()->getFoundationSDK().getRemoteDebugger()->connect("127.0.0.1");

This feature will be more streamlined in the future, and will support custom data such as node or state information.

- There is an Error System, which you can plug into with your own Error Reporter class, or you can make due with the logging system.

- The text log system uses three formats; text, html and phpbb formatted. Configured via the World:-

mWorld = new World("FrameListener: Yes, log: none");
mWorld = new World("FrameListener: Yes, log: text");
mWorld = new World("FrameListener: Yes, log: html");
mWorld = new World("FrameListener: Yes, log: phpbb");


- If you use your own error system, and want NxOgre to work with it, then it can:


class myNxOgreErrorSystem : public ErrorReporter {

public:

myNxOgreErrorSystem() {
MyErrorSystem::getSingleton()->createErrorSubSection("Physics");
}

~myNxOgreErrorSystem () {
MyErrorSystem::getSingleton()->destroyErrorSubSection("Physics");
}

void report(const ErrorReport& r) {
MyErrorSystem::getSingleton()->reportError("Physics", r.Caller, r.Message, r.Frame);
}
};
...
mWorld = new World("FrameListener: Yes, log: none");
myNxOgreErrorSystem* physxerrorsys = new myNxOgreErrorSystem();
NxOgre::Error::getInstance()->addReporter(physxerrorsys, false);
...
delete mWorld;
delete physxerrorsys;


Params

Params are given in via a string, usually at the end of an argument once creating a NxOgre class, or they can be passed along as an instance of the params class:

SceneParams sp;
sp.setToDefault();
sp.mFloor = true;
sp.mGravity = true;
mScene = mWorld->createScene("Main", mSceneMgr, sp);


mScene = mWorld->createScene("Main", mSceneMgr, "gravity: yes, floor: yes");

Params in the text form are case-insensitive and spacing doesn't matter.


Params text-form list for most classes

(Last updated:14-05-07)

PhysXDriver (Given in through World):
framelistener: yes/no
shutdown-on-errors: yes/no
log: none/text/html/phpbb

Scene:
floor: yes/no
gravity: yes/no/0 -9.8 0
material-restitution: 0.5
material-sfriction:0.5
material-dfriction:0.5


Actor/Body:kinematic: yes/no
mass: 10.1
density: 10.1
(In the case of both specified, the Mass is used. Mass/Density is ignored when actor/body is static.)
static: yes/no
node-scale: 1 2 3
node-shadows: yes/no

Shapes:
material: myMaterial/1
offset: 1 2 3
orientation: 1 0 0 0
ccd: yes/no
ccd-delta: 0.25
skin-width: -1.0
group: myGroup/0
mesh-scale: 1 2 3

Character:
dimensions: 1 2 3 (for box) or 1 2 (for capsule)
up: 0 1 0
slopelimit: 0.7
skinwidth: 0.1
stepoffset: 0.5
type: box/capsule

Examples

NxTutorial10x-ish

mScene = mWorld->createScene("Main", mSceneMgr, "gravity: yes, floor: yes");

mScene->createBody("cube.1m.mesh", new CubeShape(1,1,1), Vector3(0,3,0), "Mass: 100");
mScene->createBody("sphere.50cm.mesh", new SphereShape(0.5), Vector3(0,6,0), "Mass: 20");
mScene->createBody("capsule.50cmx1m.mesh", new CapsuleShape(0.5,1), Vector3(0,8,0), "Mass: 15");
mScene->createBody("convex1.mesh", new ConvexShape("convex1.mesh"), Vector3(0,10,0), "Mass: 7.5");
mScene->createBody("prism.8x50cmx2m.mesh", new PrismShape(0.5,2,8), Vector3(0,12,0), "Mass: 5");

mScene->createBody("cube.1m.mesh", new CubeShape(1,1,1), Vector3(0,3,5), "static: yes");

mScene->createBody("nx.convex.mesh", new ConvexShape("nx.convex.mesh"), NxOgre::Pose(Vector3(5,5,5),Quaternion(sqrt(0.5),-sqrt(0.5),0,0)), "Mass: 1000");

for (int i=0;i < 32;i++) {
NxReal h = NxMath::rand(1,4);
mScene->createBody("cube.1m.mesh", new CubeShape(1.0f,h,1.0f), Vector3(0,10.25f + h,i), "Mass: 100, node-scale: 1 " + Ogre::StringConverter::toString(h) + " 1");
}


Terrain

(Make sure you load up the same terrain image before with Ogre)

mWorld = new World();
mScene = mWorld->createScene("Main", mSceneMgr, "gravity: yes, floor: yes");
mActor = mScene->createActor("terrain", new TerrainShape("118.tga", 4096, 150, 513,513), Vector3::ZERO, "static: yes");

for (int i=0;i<10;i++)
mScene->createBody("cube.1m.mesh", new CubeShape(1.0f,1.0f,1.0f), Vector3(2030,64+i,2048), "mass: 10");


Character Controller, first person shooter style.
mWorld = new World();
mScene = mWorld->createScene("Main", mSceneMgr, "gravity: yes, floor: yes");
mScene->createActor("FakeFloor", new CubeShape(100,2.1f,100), Vector3(0,-0.05f,0), "static: yes");

mCharacter = mScene->createCharacter("Char", Vector3(0,4,0), "type: box, dimensions: 1 2 1");
mCharacter->attachMesh("Cube.1m.mesh");
mCharacter->getNode()->scale(1,2,1);
mCharacter->getNode()->attachObject(mCamera);
mCamera->setPosition(0,1.8,0);

...

const MouseState ms = mInputHandler->getMouseState();

Quaternion q;
q.FromAngleAxis(
Radian(-ms.Y.rel * 0.13),
mCharacter->getGlobalOrientation() * Vector3::UNIT_Y
);
q = mCharacter->getGlobalOrientation() * q;


mCharacter->setDirection(q);

mCamera->pitch(Radian(Degree(-ms.Y.rel * 0.13).valueRadians()));

if (mInputHandler->isKeyDown(Z)) {
mCharacter->addMovement(Character::DR_StepLeft);
}
else if (mInputHandler->isKeyDown(NEG_Z)) {
mCharacter->addMovement(Character::DR_StepRight);
}
else if (mInputHandler->isKeyDown(X)) {
mCharacter->addMovement(Character::DR_Forward);
}
else if (mInputHandler->isKeyDown(NEG_X)) {
mCharacter->addMovement(Character::DR_Backward);
}




When creating a scene ensure to pass in arguments for the third parameter, otherwise the scene will fail to be create resulting a large amount of frustration (well not that much).

I discovered this error about a week ago, and fixed it. Expect it in the next SVN update.

Practice makes perfect. Time for me to practice with old tutorial builds + old physX and move up to 0.9!

Params
.
.
.
Character:
dimensions: 1 2 3 (for box) or 1 2 (for capsule)
up: 0 1 0
slopelimit: 0.7
skinwidth: 0.1
stepoffset: 0.5
type: box/capsule

The capsule need three numbers for the dimensions. With two, the application crash.