[patch MT1.3.b90] Limited Plugin Support

Notes on testing the latest builds of MapTool

Moderators: dorpond, trevor, Azhrei

Post Reply
User avatar
Lord.Ashes
Dragon
Posts: 350
Joined: Wed Jul 03, 2013 5:58 am

[patch MT1.3.b90] Limited Plugin Support

Post by Lord.Ashes »

This patch is for adding Limited Plugin Support to MapTool. The patch is based on MT-1.3.b90beta code.
Patch Objective:

To provide a way for users to add limited functionality to MapTool without having to spawn a new MapTool fork (i.e. modify core MapTool source code) and without compromising version compatibility with other clients.

With this Limited Plugin System patch, users can create external programs (Plugins) which MapTool can call (use) and get limited data from.

The limited nature of the interface and the design philosophy behind these Plugins is as follows:

1.

Plugins can only pass back information to MapTool and, at most, trigger already existing MapTool macros. The limited nature of this interface does not allow Plugins to modify core MT functionality and thus it is guaranteed that clients, using different Plugins, will remain 100% compatible (because the core MT functionality can not be affected by Plugins).

2.

A Campaign file may contain cues for Plugins (such as cues for a sound plugin) but if a client does not have the necessary plugin, the Campaign file shall still work without error. It will obviously not provided the Plugin enhancement functionality (e.g. not having a sound plugin means the sound will not be generated) but the rest of the Campaign file will still execute without issues. The Plugin related commands, added by this patch, already take care of this (i.e. skip any plugin requests if the plugin is not present or not enabled) but the Campaign creator needs to take care not to violate this rule. For example, a sound plugin should not provide critical information to the Campaign if the same information is not also provided in some other means (i.e. Chat Window text) because if a client does not have the sound plugin then he/she would not get the critical information.

3.

Some Plugin bend the above rule a bit because they need all players to have the plugin installed in order to make use of the Plugin. For example, the current implementation of the Damage Level plugin performs the conversion on the client side and thus all players need to have the plugin installed in order to get the benefits of the Plugin. This is an acceptable exception to the above design philosophy as long as the Campaign file continues to work without the plugin. For example, a player who does not install the Damage Level plugin can still use a Campaign file in which the GM is using the Damage Level plugin but he/she just won't get the benefits of the Damage Level plugin.

4.

After a Plugin is installed, it can be turned on or off by the user using MT provided macro function. This allows the user to install a large selection of Plugins but only activate certain plugins depending on which Campaign is being run. A Warning when MapTool starts is provided to enumerate Available Plugins as well as indicated enabled Plugins.

More details can be found in the thread http://forums.rptools.net/viewtopic.php?f=8&t=24539


Downloading Existing Plugins:

I have written a number of Plugins for this Limited Plugin System already. They can be downloaded at:

https://www.mediafire.com/#68d4q8uwhiujd

The source code for each of these plugins is available so that it can be checked by the users, if desired, to ensure that there is not malicious code.

The current R5 patch is fully compatible with both R4 and R5 Plugins.


How Does The Patch Work: (For Those Who Are Interested)

Basically the patch adds a number of Plugin function for calling an external Class Methods in external Class or JAR files. There are four variations, each represented by a MT plugin macro function, on how this call can be made:

The pluginExecute() macro command causes MT to execute the external method and wait until the external method returns a response. This response is returned as a result of the pluginExecute() macro so it can be used as part of a user macro or the result is displayed in the Message Panel if the command was executed from the Chat Window. With this function, if an error occurs trying to use the plugin (typically because the plugin is not installed or is not enabled) then no error messages are displayed. This function is used when the Plugin is expected to return some value but when it is not desirable to show errors if the client has not installed the plugin.

The pluginExecuteWithWarning() macro command is exactly the same as the above function except that if the Plugin can not be used then the macro returns an error message. Typically this is used more for testing but can also be used to detect a missing plugin to provide some alternate information. For example, one could create a Campaign file with a sound plugin cue initiated using this function so that if the client does not have the plugin installed it can be detected and the information can be provided in text instead.

The two other variations are pluginThread() and pluginThreadWithWarning(). These perform the same functionality as above except they do not wait for a response from the Plugin. Instead the response from the plugin is pushed into the Chat Window once the Plugin has finished execution. This is typically used for Plugin that will take longer to execute and thus need to run in the background. For example, a sound plugin which plays background music would typically be started using the pluginThread() because otherwise the background music would block MT for running. It should be noted that the Plugin itself can also implement Threading (as it the case with my Sound plugin) in which case either pluginExecute() or pluginThread() can be used.

An additional method on how Plugins can be started is by messages in the Message Panel. Plugins have the option of implementing a MessagePanelHandler function which is executed each time a new message is written to the Message Panel. The Plugin can look at the contents of the message to see if any processing is necessary and then either return the contents unmodified or return some modified version of the contents. This process is typically called planting Plugin cues. For example, Plugin function may send something like {Play Audio File "Hello.wav"} to the Message Panel but before this content is actually displayed in the Message Panel, a Plugin can detect this Plugin cue, perform some action (such as playing the audio file) and then removing the Plugin cue from the Message Panel so that the user never sees it.

Normally the output of Plugins is just text which is eventually (after being processed by all Plugins) gets passed back to the user macro or is displayed in the Message Panel. However, a re-distributor function allows the output of a Plugin to be re-processed by the client as if the user typed it at the Chat Windows. This allows the output to make use of Chat Commands and even execute MT core macro function (if they would normally be available to the client via the Chat Window).

To create a Plugin, a user creates a JAVA file with one or more public methods and compiles it to a CLASS or JAR file. This becomes the Plugin. Once placed in the Plugins directory and enabled, MapTool will be able to access the method or methods provided.

For added protection a number of MT macro function have been added for enabling and disabling Plugins. When a Plugin is installed in the Plugins directory it is Available but not Active. This allows a user to have multiple plugins installed but only a select few active at any desired time. MT macro functions have been added for enabling and disabling Plugin as well as changing the order in which Plugins are processed.


MapTool Macro vs MapTool Plugin Discussion:

There has been some discussion on the fact that some of the Plugins that I have already written can be re-created using MapTool macros without the need for the Plugin. Here are my comments on the matter: Yes. In some cases the Plugin can be re-created using MT macros but typically there are some benefits for using the Plugin as opposed to macros. For example, I created a group send macro which sends messages to multiple people. The MT broadcast function can be used to do the same. However, the plugin allows you to specify a group send as part of the Chat Message (like a pseudo chat command) whereas broadcast is a MT function. This means that using the Plugin is more direct because you specify a group as you are typing the Chat Message whereas if you use Broadcast, you would need to initiate some GroupSend macro which would prompt the user for a group and message and then send it out. This is one of the benefits of Plugins...they can be initiated like pseudo chat commands. On the other hands there are functions that Plugins can add which can not be done by MT macros such as my Sound plugin and CacheCleaner plugin.


Edits: 1. Formatting
"We often compare ourselves to the U.S. and often they come out the best,
but they only have the right to bare arms, while we have the right to bare breasts"
The Right To Bare Breasts by Bowser & Blue

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: [patch MT1.3.b90] Limited Plugin Support

Post by JamzTheMan »

Interesting, looks pretty clean at first pass. I can probably support this in my nerps build later. it will be a while as I'm in the middle of a project andwill have to look at it more closely later.
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork

User avatar
Lord.Ashes
Dragon
Posts: 350
Joined: Wed Jul 03, 2013 5:58 am

Re: [patch MT1.3.b90] Limited Plugin Support

Post by Lord.Ashes »

JamzTheMan wrote:Interesting, looks pretty clean at first pass. I can probably support this in my nerps build later. it will be a while as I'm in the middle of a project andwill have to look at it more closely later.
Sounds good. I tried to place lots of comments in the code to make it easy to follow but if you have any questions feel free to post them or PM me.
"We often compare ourselves to the U.S. and often they come out the best,
but they only have the right to bare arms, while we have the right to bare breasts"
The Right To Bare Breasts by Bowser & Blue

Post Reply

Return to “Testing”