Creating an Atavism Plugin

Developers working with the AGIS code may decide to create a new Atavism Plugin if they want to implement a new system that is not provided by default (for example a custom weather system or maybe a stock exchange system). The steps below cover how a new plugin can be added to Atavism.

Note: The * symbol before the words Plugin or Client represent a name (any name) of a plugin.

The core file for a plugin is the *Plugin.java file which should exist in the atavism.agis.plugins package. The first step is to create a new *Plugin.java file (replacing the * with the name of your plugin). This can be done in Eclipse by right clicking on the atavism.agis.plugins, choosing New → File and naming the file *Plugin.java (replacing the * with the name of your plugin).

The Plugin class needs to extend the EnginePlugin class (or a child of EnginePlugin) and should call SetPluginType(string) in the constructor, along with passing the Plugin name to the parent constructor. The example below from the ArenaPlugin class shows the basic structure needed for setting up a Plugin class.

  public class ArenaPlugin extends EnginePlugin {
      
      public ArenaPlugin() {
          super(ARENA_PLUGIN_NAME);
          setPluginType("Arena");
      }
      
      public String getName() {
          return ARENA_PLUGIN_NAME;
      }
      
      public static String ARENA_PLUGIN_NAME = "Arena";
      
      protected static final Logger log = new Logger("Arena");
      
      public void onActivate() {
          ...
      }
  }

While not required, each Plugin uses has an accompanying *Client.java file where the messages/message types and other functions for the Plugin can be added. The Client file is generally located in atavism.agis.plugins package beside the core *Plugin.java file.

The Client class doesn’t inherit from or extend any other classes and doesn’t have any required functions or variables, however, any messages for your Plugin will be added to this class.

For a plugin to load on server startup it must be declared and registered in a couple locations.

A python script for the plugin should be created in the config/world folder on the server and contain the registerPlugin() function, such as:

  from atavism.agis import *
  from atavism.agis.core import *
  from atavism.agis.objects import *
  from atavism.agis.util import *
  from atavism.server.math import *
  from atavism.server.events import *
  from atavism.server.objects import *
  from atavism.server.engine import *
  from atavism.server.util import *
  from atavism.server.plugins import *
  
  Engine.registerPlugin("atavism.agis.plugins.ArenaPlugin");
  

This plugin file can then contain other code to allow setting properties etc. in your plugin if wanted. Take a look at the other *plugin.py files in the config/world folder to get some examples.

The new plugin python script now needs to be added to the world.sh file (located in the bin folder), along with adding the Plugin name to the list of plugins in that file.

Scroll down to roughly line 250 and find the line that starts with:

   PLUGIN_TYPES=
   

Go to the end of the string and add (without the quotation marks):

  " -p YourPluginName,1"

Now you need to decide if you can add the plugin to one of the existing server processes, or if you need to make a new server process.

A new plugin can be loaded by an existing server process by adding the plugin’s python script to the list of scripts it loads on startup. This can be a bit tricky, but a bit below the PLUGIN_TYPES line each process is defined in the following format (combat process example):

  if [ $verbose -gt 0 ]; then
      echo -en "Starting combat server: \t"
  fi
  java \
      $JAVA_FLAGS \
      -Datavism.loggername=combat \
      atavism.server.engine.Engine \
$CMDLINE_PROPS \
      -i "${AO_BIN}"/wmgr_local1.py \
      -i "${AO_COMMON_CONFIG}"/aomessages.py \
      -i "${AO_WORLD_CONFIG}"/worldmessages.py \
      -t "${AO_COMMON_CONFIG}"/typenumbers.txt \
      "${AO_COMMON_CONFIG}"/global_props.py \
      "${AO_WORLD_CONFIG}"/global_props.py \
      "${AO_COMMON_CONFIG}"/skill_db.py \
      "${AO_WORLD_CONFIG}"/skill_db.py \
      "${AO_COMMON_CONFIG}"/ability_db.py \
      "${AO_WORLD_CONFIG}"/ability_db.py \
      "${AO_WORLD_CONFIG}"/classabilityplugin.py \
      "${AO_WORLD_CONFIG}"/combat.py \
      "${AO_WORLD_CONFIG}"/extensions_combat.py \
      "${AO_COMMON_CONFIG}"/profession_db.py \
      "${AO_WORLD_CONFIG}"/profession_db.py \
      "${AO_COMMON_CONFIG}"/groupplugin.py \
      "${AO_WORLD_CONFIG}"/group.py \
      &
  
  write_pid combat $!
  

The new python script filename needs to be added to the list of python scripts for the process the plugin should belong to.