Plug-in Documentation
PlugInterface.class, which *must* be implemented by all plugins.
/* This is a test plug-in.
* It mainly contains stubs for the
* functions the plug-ins look for.
*/
package anecho.JamochaMUD.plugins;
import anecho.JamochaMUD.JMConfig;
import anecho.JamochaMUD.MuSocket;
import java.util.*;
public class TestPlugIn implements PlugInterface {
JMConfig settings;
public void setSettings(JMConfig mainSettings) {
this.settings = mainSettings;
}
/** This method returns the name of the plug-in */
public String PlugInName() {
// Nothin'
return "Test Plug-in";
}
/** A basic description of the plug-in that is shown in
* the JamochaMUD "Manage Plugins" dialogue box
*/
public String PlugInDescription() {
return "TestPlugIn is a sample plug-in used to show developers how to create their own plug-ins.";
}
/** This indicates what type of plugin this is, ie: input or output.
* This setting will affect what information JamochaMUD tries to
* process with this plug-in.
* If the plug-in is set to a setting that JamochaMUD does not
* understand than the plugin will be ignored.
*/
public String PlugInType() {
return "TestPlugIn -> PlugInType";
}
/** This is the main method of the plug-in. It is passed both
* a string for processing as well as and associated MU* that
* the message is coming from/going to.
*/
public String PlugMain(String jamochaString, MuSocket mu) {
System.out.println("TestPlugIn received: " + jamochaString);
return jamochaString;
}
/** This method is called by the "Properties" option in
* the JamochaMUD "Manage plugins" dialogue box.
* Any settings that you wish the user to have access to
* can be configured through this method
*/
public void PlugInProperties() {
}
/** This method is called as soon as the plugin is first loaded.
* It is useful for loading or configuring anything needed by
* the plug-in at start-up (such as loading settings).
* This method is only called when JamochaMUD first loads the
* plug-in, even if the plug-in is not currently enabled.
*/
public void InitialiseAtLoad(){
}
/** The method is automatically called when JamochaMUD is quit
* by using the File -> Exit menu or the close window icon.
* This method will not be called if JamochaMUD is "killed"
* or crashes.
* This section is useful for writing any settings back to disk.
*/
public void SetAtHalt(){
}
/** This method tells JamochaMUD whether this plugin should have
* its own person configuration directory where it can keep its
* settings.
* A return of false means that the plugin has no settings that
* need to be saved to disk.
* A return of true tells JamochaMUD to create a settings directory
* for this plugin (if one does not already exist).
*/
public boolean haveConfig() {
return false;
}
/** If a plug-in has properties that can be configured via a GUI,
* this method should return <tt>true</tt>, otherwise it should
* return false.
* When settings this result to <tt>true</tt>, it indicates to
* JamochaMUD that the PlugInProperties method may be called.
*/
public boolean HasProperties() {
return false;
}
/** This function is automatically called by JamochaMUD when the
* plug-in is first activated (at each JamochaMUD start-up). This
* may be called if the plug-in was active the last time JamochaMUD
* was stopped, or when it is set active from the "Manage Plug-Ins"
* dialogue.
* It can be useful for setting up items that you did not want setup
* during the normal initialisation of the plug-in.
*/
public void Activate() {
}
/** This function is automatically called by JamochaMUD when the
* plug-in is set inactive from the JamochaMUD "Manage Plug-Ins"
* dialogue. With this method, you can easily deactive items that may have
* initially been setup by the <tt>Activate</tt> method (such as removing
* listeners, etc.).
*/
public void Deactivate() {
}
public boolean isActive() {
return false;
}
}
I've come up with a few general notes about creating PlugIns in hopes that it'll help maintain a certain amount of consistency in format, and to help ensure that they work equally well (or at all) on both single-user and multi-user platforms!
.class of the plugin should reside in the plugins
directory (this is how JamochaMUD enumerates them, so if they're not there, they won't
be counted). Please note that there is a slight difference for multi-user machines,
listed below. Eg: for our FooBar PlugIn, we'll put FooBar.class (the
plugin's class name) in the plugins directory.
FooBarDir
subdirectory, putting the additional classes in there.
As of 2004-01-17 JamochaMUD now has a built-in plug-in installer! This means that we as developers now have a platform-independent way of installing our plug-ins (unless they require some really funky stuff such as 3rd part jar-files and such)!
A JamochaMUD plug-in package is really just a specialised zip-file, so requires no
special software to create one. The extension .jpa is used to visually
differentiate a plug-in package from an ordinary zip-file.
The only file required in a JamochaMUD plug-in archive (besides the classes for your code) is that of a MANIFEST file; a simple text file with the following information (comments are included in brackets for reference here, but should not be included in the actual file):
NAME: Test Plug-in (Name of the plug-in) VERSION: 1.0 (Version of the plug-in) PLUGCLASS: TestPlugIn (Name of the main Java class of the plug-in) JVM: 1.1 (Minimum Java Virtual Machine needed to use the plug-in) JMUDVER: 04-01-12 (Minimum version of JamochaMUD needed... numeric portion only) LICENSE: TestPlugInDir\COPYING (location in the .jpa archive of the license file) README: TestPlugInDir\readme.txt (any special instructions for the user)
Do not confuse the plug-in MANIFEST file with a jarfile MANIFEST file. They are not related, and not interchangable
Currently most of these tags are not followed by the installer, but they are planned to be implemented, so it is important to maintain them for forward-compatibility.
The manifest file must be in the root directory of the plug-in archive, so a plug-in archive may have an internal structure such as:
TestPlugIn.class MANIFEST TestPlugInDir\COPYING TestPlugInDir\readme.txt TestPlugInDir\StringMangler.class TestPlugInDir\PizzaEater.class
On multi-user systems, it is common for the user to be allocated a $home
directory which they can have free reign over. This would allow the user to
theoretically load JamochaMUD into their $home directory and run
everything from there, which would, of course, work just fine.
But, being a multi-user system, it would seem inefficient to have multiple copies of JamochaMUD in multiple user directories if the case ever arose. This can be remedied by the admin creating a 'common' directory accessible to users that contains JamochaMUD. This is where the additional PlugIn considerations arise.
Since we do not want one user changing the settings for another user's plugin, or if the
administrator isn't too big on keeping up with the newest PlugIns, we have
JamochaMUD scan both it's running directory (JMConfig.MASTERPLUGINDIR), and a
/anecho/JamochaMUD/plugins directory in the user's $home
(JMConfig.USERPLUGINDIR).
ALL configuration files will then be stored in the user's $home/anecho/JamochaMUD/plugins
directory, keeping the configurations separate, but allow
global use of whatever plugins the Admin sees fit to offer. Any additional plugins may
be added by the user to their own plugins directory without 'inflicting' these additions
on other users.
Theoretically, with symbolic links, users could also use PlugIns kept in other directories, and perhaps even across networks and the 'net.
**** DURN IMPORTANT!! ****JMConfig.getJMString(JMConfig.USERPLUGINDIR) and
JMConfig.getJMString(JMConfig.MASTERPLUGINDIR). This will ensure
that the .rc files et al. are always written to the correct directory.