A persitent world with entities

In mangalore the physical elements you need to create a world is :

• the database file storing your level information (db:world.db3)
• the definition of your allowed entities (data/tables/blueprints.xml)
• some graphics resources (gfxlib:examples/eagle.n2)
• some collision meshes for static environment (meshes:examples/myEnvironment_c_0.nvx2)
• or physics declarations for non static entities (physics:examples/myBox.xml)
• some optional animations (these are the entity animations like elevator paths etc. not the animations within a gfx resource)
• some optional navigation meshes
• some optionalwaypoints

I will not talk about the last three ones here. I asume some models for the environment have been exported or created by hand. Note that level is not used by the managalore framework, but it might be helpful if you export levels to an xml file (mangalore early 2005 release) and then use the python tool to create your db file. Same goes for the entity definitions found in data/tables/db these are not used by the managalore framework as provided by radonlabs.

So how would I create a level with some environment graphics, some movable and destroyable objects and a player in managalore ?

I start from the bottom and will work up to explain what I know. A property is the lowest part you will need. Have a look in the Properties directory to get a grasp of what they look like and what the provide on functionality. Basically a property is a placeholder for information bits for an object in your game. Let's create a property. You can copy an existing one over to a LivingProperty, or create one from scratch. The decisive parts are the DeclareXYZ and RegisterXYZ macros. The first part is to declare the attributes of your property, for the LivingProperty I would add an int for hitpoints and an int for armorpoint:

 

namespace Attr 

{ 

        DeclareInt(Hitpoints); 

        DeclareStorableInt(ActualHitpoints); 

        DeclareStorableInt(Armorpoints); 

}; 

 

DeclareRtti; 

DeclareFactory(LivingProperty); 

 

namespace Attr 

{ 

        DefineInt(Hitpoints); 

        DefineStorableInt(ActualHitpoints); 

        DefineStorableInt(Armorpoints); 

}; 

 

ImplementRtti(Properties::LivingProperty, Game::Property); 

ImplementFactory(Properties::LivingProperty); 

Some important details you should know about your newly created properties:

• Just creating the .cc and .h files and including them in your project for compilation will not make the properties available. The runtime macros will not get expanden until you also include your header file in one of your instantiated classes (setupmanager.cc, or something).


• Another detail to look for is the decision on storable attributes. Only atributes marked as storable will also be written back to the database. So the transform (orientation of your entity) is sure a candidate for storing, but how about the name ? Not storable ? The answere is as always 'It depends'. If you want to create most of your entities by code for example like in a RTS game and not by loading pregenerated ones then the name atribute woud be a candidate for storable. Which also has consequences for level load/store times. So if your attributes will not show up in the database it could be very likely that the were not intended to be updated (storable).

Now let's create an entity and attach some properties. You can do this via different ways.

The 'mangalore' one is create an entity by loading it from the database, either by loading the entity instance. That would be the case if you resume your game. Or you load entities from the database based on template definitions. The last one I will describe a little bit in detail is creation of entities from scratch based on the allowed entity definition (data/tables/blueprints.xml)

Loading entities from the database is quite trivial and is used in the setupmanager. Set the current level, create a bare entity based on the db definition and set its properties to the values from the database. Have a look at FactoryManager::CreateEntityByGuid, CreateEntityByCategory for details.
Creating entities from scratch goes a similar way as described above. The main part is to define your new entity first in the blueprints.xml file. Here you specify a tag to identify your entity and which properties will be attached to the entity. I name my entity Alive and have the LivingProperty added.

 

  gameEntity = FactoryManager::Instance()->CreateEntityByTemplate(

      "Alive", "Unit");

  matrix44 eMatrix;

  eMatrix.ident();

  //guid, name

  nGuid guid;

  guid.Generate();

  gameEntity->SetString(Attr::GUID, guid.Get());

  gameEntity->SetString(Attr::Graphics, "units/orks");

  gameEntity->SetInt(Attr::Hitpoints, 100);

  gameEntity->SetInt(Attr::ActualHitpoints, 100);

  gameEntity->SetMatrix44(Attr::Transform, eMatrix);

  EntityManager::Instance()->AttachEntity(gameEntity);

The last possibility is to create all from scratch, and not even use the template file. This is done via FactoryManager::CreateEntityByClassName to create a vanilla entity, followed by FactoryManager::CreateProperty to create vanilla properties. These are attached to the entity in the next step before you start setting your attribute values to the properties. The final step is again to attach the entity to the entity manager. Have a look at the code found in viewerapp.cc as shown below:

ViewerApp::SetupLightsInScene()

{    

    //create new Entity for light in scene, 

    //create lightProperty and attach it to the entity

    Ptr entity = Managers::FactoryManager::Instance()

    ->CreateEntityByClassName("Entity");

    Ptr lightProperty = Managers::FactoryManager::Instance()

    ->CreateProperty("LightProperty");

    entity->AttachProperty(lightProperty);



    //set position of lightsource

    matrix44 lightTransform;

    lightTransform.translate(vector3(100.0f, 100.0f, 100.0f));

    entity->SetMatrix44(Attr::Transform, lightTransform);



    //set Attributes of the lightsource

    entity->SetString(Attr::LightType, "Point");

    entity->SetVector4(Attr::LightColor,vector4(1.0f,1.0f,1.0f,1.0f));

    entity->SetFloat(Attr::LightRange, 1000.0f);

    entity->SetVector4(Attr::LightAmbient,vector4(0.3f,0.3f,0.3f,0.0f));

    entity->SetBool(Attr::LightCastShadows, false);



    //attach lightproperty to entity

    Managers::EntityManager::Instance()->AttachEntity(entity);

    return;

}

That's all. And remember, only storable attributes will be saved back into your world database.