Entity extras attach additional methods to the BigWorld.Entity Python class on the cell. All entities have access to all methods of entity extras. However, the class implementing an entity extra is not instantiated until one of those methods is used, thus saving memory.

While entity extras are useful for extending entities in ways that can only be done via C++, it is worth remembering that for many things a simple Python base class will suffice.

Entity extras should not contain any state for an entity, as they are not streamed from one cell to another during the cell's ghosting process.

A minimal entity extra consists of the following header file (replacing any references to EgExtra with the appropriate name):

#ifndef EGEXTRA_HPP
#define EGEXTRA_HPP

#include "cellapp/entity_extra.hpp"

/**
 * Simple example entity extra... can print a message to the screen
 */

#undef PY_METHOD_ATTRIBUTE_WITH_DOC
#define PY_METHOD_ATTRIBUTE_WITH_DOC PY_METHOD_ATTRIBUTE_ENTITY_EXTRA_WITH_DOC

class EgExtra : public EntityExtra
{
  Py_EntityExtraHeader( EgExtra );

public:
  EgExtra( Entity& e );
  ~EgExtra();

  PyObject * pyGetAttribute( const char * attr );
  int pySetAttribute( const char * attr, PyObject * value );

  static const Instance<EgExtra> instance;
};

#undef PY_METHOD_ATTRIBUTE_WITH_DOC
#define PY_METHOD_ATTRIBUTE_WITH_DOC PY_METHOD_ATTRIBUTE_BASE_WITH_DOC

#endif

EgExtra header file bigworld/src/examples/cellapp_extension/egextra.hpp ‐ Minimal definition

The code above contains the declarations necessary to integrate an entity extra into any entity in the BigWorld system.

After the header guards, bigworld/src/server/cellapp/entity_extra.hpp is included which defines the EntityExtra class.

It also overrides the macro PY_METHOD_ATTRIBUTE, in order to make automatically declared Python attributes in EntityExtras work^[40]. This allows BigWorld to search through and automatically instantiate extras by using only the name of the method that has been called.

In the EgExtra class, we derive from EntityExtra, and use the macro Py_EntityExtraHeader to declare some additional methods and properties that are used to keep track of these classes.

We provide the methods pyGetAttribute and pySetAttribute so that we can act like a Python object.

A static specialisation EntityExtra::instance member is also declared to access the entity extras. With it, we can get a reference to the EgExtra for any Entity& ent using the code:

EgExtra& eg = EgExtra instance( ent );

If the extra does not exist, it will be instantiated and returned. If we wanted to check first whether the extra exists, we can query it with the following code:

bool hasEgExtra = EgExtra instance.exists( ent );

We implement the outline of the EgExtra class as follows:

#include "egextra.hpp"

DECLARE_DEBUG_COMPONENT(0);

PY_TYPEOBJECT( EgExtra )

PY_BEGIN_METHODS( EgExtra )
PY_END_METHODS()

PY_BEGIN_ATTRIBUTES( EgExtra )
PY_END_ATTRIBUTES()

const EgExtra::Instance<EgExtra> 
  EgExtra::instance( &EgExtra::s_attributes_.di_ );

EgExtra::EgExtra( Entity& e ) : EntityExtra( e )
{
}

EgExtra::~EgExtra()
{
}

PyObject * EgExtra::pyGetAttribute( const char * attr )
{
  PY_GETATTR_STD();
  return this->EntityExtra::pyGetAttribute( attr );
}

int EgExtra::pySetAttribute( const char * attr, PyObject * value )
{
  PY_SETATTR_STD();
  return this->EntityExtra::pySetAttribute( attr, value );
}

EgExtra implementation file bigworld/src/examples/cellapp_extension/egextra.cpp ‐ Class outline

These two files together constitute the framework that we will use to implement any entity extra. These files can be found in BigWorld distribution, in the directory bigworld/src/examples/cellapp_extension.

We can now add methods to this entity extra. We do this by declaring the method in the class declaration, and exposing it to Python with the BigWorld Python macros.

As a simple example, to implement a method that prints the message 'hello world' to the server debug log, we add the following code to the class declaration:

// ...

class EgExtra : public EntityExtra
{
  Py_EntityExtraHeader( EgExtra );

public:
  // ...

  void helloWorld();
  PY_AUTO_METHOD_DECLARE( RETVOID, helloWorld, END );
};

// ...

EgExtra header file ‐ Declaration of method helloWorld

And in the implementation file, we add a simple 'stub' implementation:

// ...

PY_TYPE_OBJECT( EgExtra )

PY_BEGIN_METHODS( EgExtra )
  PY_METHOD( helloWorld )
PY_END_METHODS()

// ...

void EgExtra::helloWorld()
{
  DEBUG_MSG( "egextra: hello world\n" );
}

EgExtra implementation file ‐ Definition of method helloWorld

After compiling this module, then for any entity in the world you can call:

self.helloWorld()

The call above outputs the text 'egextra: hello world' to the server debug log.

Entity extras have an entity() function, which returns a reference to the entity they have been attached to.

Controllers enable us to dynamically add stateful C++ objects to entities on the CellApp. They can be used for property updates that need to be continuous, or for extensions that need to interact with the server at a level lower than the one exposed via the scripted entity model.

To implement a Controller, inherit from the CellApp class named Controller. The Controller declaration has to include the special macro DECLARE_CONTROLLER_TYPE, which includes definitions required to register the Controller in the BigWorld system.

The stub declaration file contains the following code:

#ifndef EGCONTROLLER_HPP
#define EGCONTROLLER_HPP

#include "cellapp/controller.hpp"

class EgController : public Controller
{
  DECLARE_CONTROLLER_TYPE( EgController );

public:
};

#endif

Controller header file ‐ bigworld/src/examples/cellapp_extension/egcontroller.hpp

A Controller may be a member of the real domain (denoted by DOMAIN_REAL), or the ghost domain (denoted by DOMAIN_GHOST).

BigWorld directs Controllers by calling various virtual methods on the Controller class. There are two types of such methods:

A Controller can be a member of both domains (DOMAIN_REAL, and DOMAIN_GHOST) if it has the (uncommon) need to present aspects of itself as a ghost Controller, and aspects of itself as a real Controller.

Once an initial decision has been made as to which domains a controller belongs to, a stub implementation file needs to be set up. At first, it does not have to declare the domain, as illustrated below:

#include "egcontroller.hpp"
#include "cellapp/cellapp.hpp"

DECLARE_DEBUG_COMPONENT(0);

// controller type declaration needs to go here

Controller stub implementation file ‐ bigworld/src/examples/cellapp_extension/egcontroller.cpp

Next, a macro needs to be placed to implement the controller integration. There are two possible macros for that:

When implementing a controller, the Controller class exposes the following useful methods:

Entity extras are commonly used to provide a more sophisticated means of instantiating Controllers. They might provide a factory that selects one of several types of Controller to instantiate, or provide a means of limiting the number of Controllers that are instantiated.

To begin exploring this, we implement something similar to the automatic instantiation provided by the macro IMPLEMENT_CONTROLLER_TYPE_WITH_PY_FACTORY.

We add an instantiation method called addEgController to EgExtra, taking an integer user argument:

class EgExtra : public EntityExtra
{
  Py_EntityExtraHeader( EgExtra );

public:
  // ...

  PY_AUTO_METHOD_DECLARE( RETOWN, addEgController, ARG( int, END ) );
  PyObject * addEgController( int userArg );

  static const Instance<EgExtra> instance;
};

EgExtra header file bigworld/src/examples/cellapp_extension/egextra.hpp ‐ Declaration of instantiation method addEgController

The next step is to implement the method addEgController. To do so, we need to:

This will mean the following changes to EgExtra:

#include "egextra.hpp"
#include "egcontroller.hpp"

DECLARE_DEBUG_COMPONENT(0);

PY_TYPEOBJECT( EgExtra )

PY_BEGIN_METHODS( EgExtra )
  PY_METHOD( helloWorld )
  PY_METHOD( addEgController )
PY_END_METHODS()

// ...

PyObject * EgExtra::addEgController( int userArg )
{
  if (!entity_.isReal())
  {
    PyErr_SetString( PyExc_TypeError,
      "Entity.addEgController() may only be called on real entities" );
    return NULL;
  }

  ControllerPtr pController = new EgController();
  ControllerID controllerID = 
    entity_.addController( pController, userArg );
  return Script::getData( controllerID );
}

EgExtra implementation file bigworld/src/examples/cellapp_extension/egextra.cpp ‐ Definition of instantiation method addEgController

EgExtra::instance( *this->entity() ).setEgControllerPtr( this )