Overview

The server start script, world.sh, launches a number of Java virtual machine (JVM) processes. Each server process has a single instance of the atavism.server.engine.Engine class and a single messaging agent. The server messaging agent participates in the Atavism message system. A process (or agent) can have multiple server plug-ins, each of which corresponds to an instance of atavism.server.engine.EnginePlugin.

An agent is a process in the Atavism message domain. Agents using the same message domain can communicate with each other using the Atavism Messaging System. To access the messaging agent, use the atavism.server.engine.Engine.getAgent()method, which returns a atavism.msgsys.MessageAgent object. Agents have an agent type and an agent name. By default, the agent name is the same as the logger name when the Java VM is started. By convention, the agent type and agent name are lower cases. They should be the same if there is just one instance of the agent type. If there are multiple instances of an agent type, then the agent name should be constructed by appending “_” and a number to the agent type. For example, agent type “proxy” and agent name “proxy_1”.

The agent type identifies a class of agents, typically running the same set of plug-ins. For example, “proxy” could be the agent type of agents running a ProxyPlugin. Multiple agents can have the same agent type. The agent type also determines which message advertisement file the process uses. The file name is constructed: agent-type-ads.txt Agent name The agent name must be unique within the message domain (that is, for a particular game/world sever installation). The agent name determines the agent’s log file name. The log file name is constructed: <agent-name>.out. Also, the domain server is told which agent names are expected to be running. It uses this information to know when all agents are running. There is a one-to-one correspondence between processes and agents; therefore a single agent can host zero or more plug-ins.

A plug-in is an instance of an atavism.server.engine.EnginePlugin sub-class. For example, ProxyPlugin, ObjectManagerPlugin, and CombatPlugin. Plug-ins run within an agent process. Plug-ins use the domain, messaging, and logging services provided by the agent. Plug-ins have a plug-in type and a plug-in name. Plug-ins must set their plug-in type and plug-in name within their constructor. The plug-in type identifies the plug-in class, typically a shortened form of the class name. For example, “Proxy” is the plug-in type of ProxyPlugin. Instances of a given plug-in class should have the same plug-in type. The plug-in name must be unique within its message domain. By convention, the plug-in type and plug-in name use “CamelCase” and omit the string “Plugin”. They should be the same if there is just one instance of the plug-in type within the domain. If there are multiple instances of a plug-in type, then the plug-in name should be constructed by appending a number to the plug-in type. For example, plug-in type “Proxy” and plug-in name “Proxy1”. The plug-in dependencies (see world.properties) are expressed in terms of plug-in types. The domain server tracks the number of available plug-ins for each plug-in type. When the expected number of plug-ins are available, then the dependency is satisfied. For more information, see Plug-in dependencies.

The domain server includes a facility to generate unique names. These names are unique until the domain server restarts. A unique name is generated by appending a number to a given prefix. The numbers start at one (1) and increment upward. Each prefix has its own number sequence. This facility is used to generate unique agent and plug-in names. For agent names, the startup script starts the domain server first, then runs a small program requesting a unique name. See function alloc_domain_name in atavism.sh for an example. You only need to generate names if you run multiple copies of an agent or plug-in. For plug-in names, the plug-in constructor uses a MessageAgent API to request a unique name from the domain server. For example:

 public MyPlugin()
 {
     super();
     setPluginType("Mine");
     String myPluginName;
     try {
         myPluginName = 
         Engine.getAgent().getDomainClient().allocName("PLUGIN",getPluginType()+"#");
     }
     catch (java.io.IOException e) {
         throw new AORuntimeException("Could not allocate a plugin name",e);
     }
     setName(myPluginName);
     // Other plugin initialization ...
 }

This example uses plug-in type “Mine”. The plug-in name is constructed by replacing the “#” with a number.

The order of plug-in activation is controlled by the plug-in dependencies expressed in world.properties. The dependencies are in terms of plug-in types, rather than plug-in names. When the expected number of plug-ins of a given type are activated, then the dependency is satisfied. Note that a plug-in constructor should never create any subscriptions or publish messages. That should only be done within the plug-in onActivate() and thereafter. A dependency is described by a atavism.plugin_dep property: atavism.plugin_dep.MyPluginType=OtherPluginType[,MorePluginTypes] MyPluginType will be activated when OtherPluginType (and possibly MorePluginTypes) have finished activation. Plug-in types must have a “plugin_dep” property even if they have no dependencies. You can create world-specific plug-in dependencies by appending the world name after “plugin_dep”: atavism.plugin_dep.my_world.MyPluginType=OtherPluginType These are the default plug-in dependencies:

• atavism.plugin_dep.Login=ObjectManager,Instance
• atavism.plugin_dep.Instance=ObjectManager,Quest,MobManager,Inventory,WorldManager
• atavism.plugin_dep.Proxy=Instance
• atavism.plugin_dep.MobManager=ObjectManager,WorldManager,Inventory,Quest,Social
• atavism.plugin_dep.sampleworld.MobManager=ObjectManager,WorldManager,Inventory,Quest,Combat
• atavism.plugin_dep.ObjectManager=
• atavism.plugin_dep.WorldManager=
• atavism.plugin_dep.Inventory=
• atavism.plugin_dep.Quest=
• atavism.plugin_dep.Trainer=
• atavism.plugin_dep.ClassAbility=
• atavism.plugin_dep.Combat=
• atavism.plugin_dep.Vendor=
• atavism.plugin_dep.Domain=Instance,Proxy
• atavism.plugin_dep.DataLogger=
• atavism.plugin_dep.Arena=
• atavism.plugin_dep.Social=
• atavism.plugin_dep.Voxel=