JamochaMUD, A Java MUD/Muck Client
(A Java MUD/Muck Client)

Buh-ZAPPP!!! (JamochaMUD Plugins!)

Writing JamochaMUD plugins

Please note that this document may be somewhat out of date! The JamochaMUD source will be the authoritative place to see how things are done, but this should help give an overview.

The framework for JamochaMUD plugins has been created in a very minimal and hopefully quite extensible format... going solely on the knowledge that the user/hacker will enhance JamochaMUD in ways that I could never even dream of foreseeing.

Sections:

Sample Code

Here, I will give a basic overview of the methods present in the PlugInterface.class, which *must* be implemented by all plugins.

The following is a skeleton of what a plugin must contain. The programmer can then build on and extend this in any way they please (within a few 'rules' I have created, just to keep good form and consistency between plugins).

-----Code snippet begins-----

/* 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 &quot;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 &quot;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;
    }
}


----- Code snippet ends -----

Notes on creating plug-ins

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!

Creating a JamochaMUD plug-in archive

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

Special notes for multi-user systems

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!! ****
Thus, when writing a PlugIn (regardless of your *target* platform), it is important to use the format of 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.



All artwork presented on these pages is ©copyright 1996-2010 Jeff Robinson.
These images should only be used in association with JamochaMUD, and you should really really really ask the artist first, because he's known to be pretty congenial and easy going about stuph like that.