Plugin interface

Foreword

Plugins are software components that will run along with Sc2gears, but they are developed independently by 3rd party developers and vendors.

Plugins can be a great asset to make your Sc2gears and StarCraft II experience better.

Sc2gears has a plugin interface which allows developers to create plugins and extensions for Sc2gears.

Since plugins are NOT developed or maintained by me, you should have the same reservations about them as about any applications you download from the Internet.

ONLY DOWNLOAD AND ADD PLUGINS THAT COME FROM TRUSTED SOURCES!

Plugins are distributed as folders. To add a plugin to Sc2gears, you just have to copy the plugin's folder into the "Plugins" folder inside Sc2gears. You can manage your plugins from the Plugin Manager which is available from the Tools menu inside Sc2gears.

When a plugin is copied into the "Plugins" folder inside Sc2gears, it is disabled by default. So you have to manually enable it in the Plugin Manager.

Since plugins are NOT developed by me, I take zero responsibility for what they do or how they do it. Poorly or viciously written plugins can make your Sc2gears or your whole system slow, unstable, or can even damage it. Plugins can also access and steal your private data.

AGAIN: ONLY DOWNLOAD AND ADD PLUGINS THAT COME FROM TRUSTED SOURCES!

Google Ads

Plugin development

The following information is intended for developers.

You can download the Plugin API (Plugin interface library, example plugins with source code, Javadoc) from the Downloads page.

If you have any questions, suggestions or you want to share your opinion, visit the Sc2gears developer forum.

The Plugin API Javadoc is also available on the web: Sc2gears Plugin API Javadoc

Plugins are written using the Java language. There are no restrictions, everything can be used from the public Java API. Since the Java requirement of Sc2gears is 7.0, for the sake of portability it is highly recommended to use only the Java API 7.0 (and not newer versions). Plugins can write to the standard output (System.out) or to the standard error (System.err), they will appear in the application Log ("User Content/Logs" folder).

A plugin is a set of files within a folder. It must contain a plugin descriptor file and java libraries (*.jar files) that contain the code of the plugin - in simple cases it can be one jar file. All Java libraries (*.jar) in the plugin folder will be loaded and will be available for the plugin. Classes may only be loaded once, keep that in mind if you plan to use static attributes and initializers (static initializers may only run once and static attributes may only be initialized once).

The Plugin API library must not be included in the plugin jars, because it is contained in Sc2gears!

The plugin descriptor is an XML file which must be in the root of the plugin folder and must be named "Sc2gears-plugin.xml", and contains meta-data about the plugin including the plugin name, author, description and main class.

Here is an example of "Sc2gears-plugin.xml":

<?xml version="1.0" encoding="UTF-8"?>

<!-- Plugin descriptor, contains plugin meta-data. -->

<plugin docVersion="1.0">

<name>File info</name>

<authorFirstName>András</authorFirstName>

<authorLastName>Belicza</authorLastName>

<authorEmail>someemail@somesite.com</authorEmail>

<version>1.0</version>

<releaseDate>2011-07-08</releaseDate> <!-- Format: "yyyy-MM-dd" -->

<apiVersion>1.0.1</apiVersion> <!-- Plugin API version implemented/used by the plugin. -->

<homePage>https://sites.google.com/site/sc2gears/</homePage>

<!-- Description can be plain text or HTML text, can contain multiple lines. -->

<description isHtml="true"><![CDATA[<br>A test plugin that adds a new <b>replay operations</b> menu item which shows info of the selected replays in a dialog.]]></description>

<!--

The main class must implement the "hu.belicza.andras.sc2gearspluginapi.Plugin" interface,

and must have a public no-arg constructor (a constructor that takes no arguments).

The main class must also be unique: cannot be added 2 plugins with the same main class!

-->

<mainClass>hu.belicza.andras.fileinfoplugin.FileInfoPlugin</mainClass>

</plugin>

The main class must implement the hu.belicza.andras.sc2gearspluginapi.Plugin interface or extend a class that implements it (for example hu.belicza.andras.sc2gearspluginapi.impl.BasePlugin). Moreover the main class must provide a public no-arg constructor (a constructor that takes no arguments).

To Sc2gears a plugin is identified by its main class. This means that the main class must be unique: cannot be added 2 plugins with the same main class. Plugins may store settings and persistent files which will be saved in the plugin's own context. This plugin context is bound to the main class of the plugin, so the main class cannot be changed. If the main class of the plugin is changed (the package name and/or the class name), a new context will be assigned to the plugin.