%creatingabloodymess%

Preamble

This small guide is for the 1.5.x releases of NxOgre; also known as Bloody Mess, it is more technical than the other NxOgre guides and does expect you to have previous knowledge with NxOgre, or previously used a Physics engine with Ogre before.

Ready? Let's go.

World, Scenes and TimeControllers

Classes: World, Scene and TimeController

World


World is the main class it's like the Ogre Root class. Being a singleton it is created and destroyed like so;

World* mWorld = World::createWorld();
World::destroyWorld();


The life-time of the World class, should be the same as your Ogre Root.

Scene

A Scene is a portion of the World. There can be up to 32 of them, and they are almost infinite in size. Actors, Materials, Shapes cannot be shared between scenes, but Meshes and HeightFields can.

SceneDescription description;
description.mGravity.y = -9.81f; // -9.81 m/s

Scene* mScene = mWorld->createScene(description);

TimeController


The TimeController is in charge of time. Once time has been "injected" into NxOgre (in fractions of seconds), it will propagate to all EventListeners; Singletons, Scenes, Renderables, Actors and then finally to Shapes.

mTimeController = TimeController::getSingleton();

Normally it is best to inject the same time value for each second - such 1/60th of a second when Ogre is in vertical sync mode. You should inject time every time a frame is rendered.

static const float sTime = 1.0f/60.0f;
mTimeController->advance(sTime);

Resources

Classes: ResourceSystem, ResourceProtocol, Archive UniformResourceIdentifiers and Resource

ResourceSystem

The Resource system allows you to read and write to things; such as files, zip files or even chunks of memory. The ResourceSystem singleton is created automatically by World when it is created, but if you need to use it before, then like all Singletons you can pre-create them.

World::precreateSingletons();


Then to use the ResourceSystem, and like all Singletons you can access the pointer via

ResourceSystem::getSingleton();

ResourceProtocol


NxOgre doesn't know or really care how an Resource is written or read to, all of that is handled by the ResourceProtocol. Which turns all of the functions and classes
involved in writing and reading to resources in a nice and neat interface provided by NxOgre.

There are two default ResourceProtocols in NxOgre by default they are file and memory. File uses the Operating System's function to write and read to files, where as memory reserve a resizeable block of memory to be used as you wish, but to NxOgre they are both the same.

Archives

An archive represents a folder, zip folder, website or any collection of resources, again to NxOgre they all behave the same. A ResourceProtocol implements an archive such as FileArchive or MemoryArchive, but keep everything abstract you will never have to deal with them. Instead you work with UniformResourceIdentifiers and ArchiveResourceIdentifiers.

UniformResourceIdentifier

A UniformResourceIdentifier or URI, is the protocol and location of an archive described as a string. The syntax is much like the URI syntax you use on the web;

Protocol Location
file: c:/Program Files/myGame/myMediaFolder


To create an archive, we tell the ResourceSystem to open an Archive by giving a URI and a common name to assign it with.

ResourceSystem::getSingleton()->openArchive("media", "file:c:/Program Files/myGame/myMediaFolder");

Resources


The Resources are the final class in the ResourceSystem. They provide direct functions to reading and writing to a file, with tons of helper functions and anything else you want to manipulate or gather information from. We open our Resource using a ArchiveResourceIdentifier and the read/write permissions.

Resource* resource = ResourceSystem::getSingleton()->open("media:myFile.nxs", Enums::ResourceAccess_ReadOnly);


Once you've finished with your resource, then you must close it.

ResourceSystem::getSingleton()->close(resource);

ArchiveResourceIdentifier


ArchiveResourceIdentifiers or ARI are use to identifiy a Resource inside an Archive. They are much like URIs but do not specifiy what protocol is being used, instead it specificies what the archive name is, rather than the location of the archive or the protocol, names of the resources are always relative to the archive and in some cases Resource names are not used at all such as the MemoryResourceProtocol.

Archive Name Resource Name
media: myFile.nxs

Meshes and Heightfields

Classes: Mesh, MeshManager, ManualMesh, HeightField, HeightFieldManager and ManualHeightField.

Mesh

The Mesh class may represent a "convex point cloud", "triangle soup", CCD Skeleton, piece of cloth or a SoftBody that may be created within NxOgre, or saved previously then loaded. PhysX mesh files names usually end in ".nxs" but that is entirely optional. One note to point out; They aren't Ogre meshes and they can't be used with Ogre. NxOgre can't use Ogre meshes either - without converting them first using a conversion tool such as Flour.

A Mesh may be loaded in via the MeshManager or created via the ManualMesh classes. The MeshManager is a singleton, and like all NxOgre Singletons it may be created before or most definitely when World is created.

MeshManager::getSingleton();


To be continued.