Animal Tutorial (Part 2)

Tutorial (Advanced)

Local Plugins

What are they?

Local plugins are plugins that are imlemented inside the host without loading a
library or other file. This can be used to provide 'default' behaviour for a
feature provided by an optional plugin (eg. a game AI).

Adding local plugins to Animals

The LocalPlugin class is a Plugin subclass, meaning that it can be used in
the same places as a LinuxSOPlugin or WindowsDLLPlugin.

To add local plugin support to the Animals example, host.h needs to be added
with the following content:

#include "animal.h"
#include <iostream>

class Penguin : public Animal
{
  public:
    virtual void speak()
    {
      std::cout << "Honk!\n";
    }

    virtual bool canFly()
    {
      return false;
    }

};

We also need a driver:

class PenguinDriver : public AnimalDriver
{
  public:
    virtual std::string getName()
    {
      return "PenguinAnimalPlugin";
    }

    virtual Penguin* createAnimal()
    {
      return new Penguin;
    }
};

In the host, we need to add some more code to main():

#include "host.h"

...

plugin = new LocalPlugin<AnimalDriver>(Animal::serverName(),
                                       Animal::ifaceVersion(),
                                       new PenguinDriver());
kernel.loadPlugin(plugin);

This code creates an instance of LocalPlugin and passes a new PenguinDriver
to it. The template parameter for LocalPlugin is the Driver base class for
the interface.

This new plugin is now in the same list as all the normal plugins, and can
be accessed in the same way (getAllDrivers or similar).

Server class

The Server class (server.h) is the class that is ultimately in charge of a
plugin interface.

Warning: This class is marked as deprecated. No user-side code should
depend on the internals of this class, and it may be hidden/removed in future
releases. However, until this happens, the API will be relatively stable.

Using Server

You can get the server for a particular interface by passing the name of the
interface to Kernel::getServer(). This method returns a ServerBase pointer which
needs to be casted to a Server using CastToServerType<DRIVER>().

Server<AnimalDriver>* svr = CastToServerType<AnimalDriver>(kernel.getServer(Animal::serverName());

To add a Server object that was instantiated by user code to the kernel, the
Kernel::addServer() method is used.

kernel.addServer(svr);

The Server API

The Server class API parallels the Kernel API - in fact, most of the Kernel
methods call Server functions behind-the-scenes.

The main difference is that the Server class methods do not have the template
parameters for the driver type. This is because the Server class that the host
uses is already specialized (the class has a driver template parameter).

In apugg 0.8, there are some methods that can only be called on Server objects.
These are getDriverCount() and getEngineVersion(). There is also a method
called getDriverName(), but this is not needed for most practical purposes.

When should I use Server?

The Kernel API for adding and manipulating plugins should be sufficient for most
uses. It is simpler and does not require the user to keep track of several
objects - only one (Kernel) is required.

The main reason to use Server objects directly is to speed up method calls. This
does not result in a huge speed boost for small projects, but when a large
number of Kernel API calls are taking place it may reduce the overhead needed
for the method calls significantly.

Another reason may be if the user has subclassed Server for some reason, but
this is not likely.