Plug-in Kit Documentation Index
What is the Plug-in Authoring Kit
and Who is the Audience?
Prerequisites
Overview of the Plug-in System
Lifecycle of a Plug-in
Scripts Versus Compiled Classes
Scripted Plug-ins
Writing Scripted
Plug-ins
Testing Scripted
Plug-ins
The Scripting
Environment
Resources
Compiled Plug-ins
Writing Compiled
Plug-ins
Testing Compiled
Plug-ins
Resources
Distributing Plug-ins
What Next?
Using the Included
Examples
Tutorials
This kit is for people who want to customize or extend Strange Eons. That is a pretty broad statement, so here are some examples:
You
should read about extension plug-ins, and look at the examples in the
extensions folder. Depending on how
different or complex any new card types you want to create are, you may want
to look into diy components.
The basic steps are to write an extension plug-in script that uses the GameData object
to register your new material. For custom components you will need to make a
class map file, and a creation script for each component. For custom tiles
you'll need to make a tile map file. An expansion can be added by simply
calling a method. You will pack everything up into an extension plug-in
bundle, including all of the images and other required data.
The following skills are helpful if you want to create plug-ins for Strange Eons. I don't want to discourage you. These prerequisites are not always strict; they will vary depending on what you want to do. If you have these skills, your life will be a lot easier and this kit will be easier to understand and use. If not, you will require a bit more patience and determination, and a willingness to learn and experiment.
General Background: You should have a decent amount of computing experience generally in order to tackle SE plug-ins. For example, you should feel comfortable creating and expanding a ZIP archive, creating folders (directories), copying files, etc. If you are going to add in custom card types, you will probably need to have at least a passing familiarity with a pixel-based graphics editor such as the GIMP or Photoshop.
Programming: When you create a plug-in you will end up writing at least a small amount of program code, usually in the scripting language JavaScript (ECMAScript). Therefore, knowing a little about programming will be very helpful. However, if the plug-in you want to make is simple and there is an existing example that you can modify to suit your needs, it is possible to bluff your way through. A bright and determined person with no programming experience can even make whole new DIY components in this way (it's already been done!). If you are an experienced programmer but are not familiar with JavaScript, you can probably pick it up quickly. It is a weakly typed, prototype-based scripting language with first-class functions and a C/Java-like syntax. It can interact with Java objects in Strange Eons and the Java 6 runtime environment, and it can implement Java interfaces and extend (subclass) Java objects. You can probably pick up enough from the example code and the scripting libraries to get along. If you want a more in-depth treatment, David Flanagan's JavaScript: The Definitive Guide is exactly what its title suggests. (Note that although they share similar names, Java and JavaScript refer to two quite different programming languages.)
A plug-in is a small program that can extend Strange Eons with new features, new card types, new expansion board tiles, and more. Usually, a plug-in cannot be run independently, but rather it depends on SE in order to function correctly. Plug-ins are usually packaged up into plug-in bundles, which make them easy to distribute. A plug-in bundle packages all of the files needed by a plug-in into a single archive file. Plug-in bundles can be installed from the Plug-in Manager in SE or by dragging and dropping the plug-in bundle onto the main application. There are different kinds of plug-ins, and each must be packaged up into a bundle with a particular file name extension. SE uses the file name extension to load the plug-in at the correct time. The basic plug-in types are:
| Plug-in Bundle File Extension | Type | Description |
|---|---|---|
| .seplugin | Activated Plug-in | These are tools that are listed in the Toolbox menu and activated by the user. They are loaded last (just before the application starts) and they can unloaded and reloaded while the application is running. They either implement the Plugin interface or its scripted equivalent. This interface is the main way that Strange Eons will interact with the plug-in: it uses it to get the plug-in's name and description, and to tell it to "do something" when the user chooses it in the Toolbox menu. When SE activates a plug-in, it will pass in a PluginContext that the plug-in can use to "talk back" to Strange Eons. |
| .seplugin | Injected Plug-in | These are similar to activated plug-ins, except that they do not appear in the Toolbox menu. They are not used often. |
| .seext | Extension Plug-in | These are plug-ins that are loaded early on while SE is starting up. They are allowed to modify aspects of the application that an activated (or injected) plug-in can't. In particular, they are allowed to modify the SE game model, which means that they can do things like add new card types, expansions, items, monsters, neighbourhoods, and so on. An extension cannot be loaded or unloaded while SE is running, because this would lead to inconsistencies in SE's game model. |
| .setheme | Theme | Themes are started very early during program start-up. They determine the look-and-feel ("skin") of the application, and so they need to be loaded before any windows might be opened. Because they are used before the scripting subsystem is started, they must be written in Java rather than JavaScript. They do not implement Plugin. Instead, they must subclass the abstract Theme class. |
| .selibrary | Library | These are loaded very early in program start-up. They are packaged in a bundle like a plug-in, but they do not do anything by themselves. Rather, they provide resources (usually compiled Java classes or JavaScript files) may be shared by other plug-ins. (For those who are familiar with Java, the contents of these bundles will be added to the class path.) |
The basic lifecycle of a plug-in is as follows:
Themes are not derived from Plugin and so they work differently. Internally, they are not even considered plug-ins; they simply use some of the plug-in system infrastructure for loading. Libraries are also different. Their content is available to other code but they don't do anything by themselves. Typically, they are used to package a third-party Java class library used by one or more plug-ins into a format that makes them easy to install (the user does not need to specify a class path, and they can have an installation read me.)
Script-based plug-ins are the most common and so this authoring kit focuses mainly on this type. For some, scripting may present performance concerns. Because of the dynamic nature of the language, script code will never be as fast as compiled Java. However, the script engine is able to compile scripts to byte code (and the JRE can then compile them to native code), so the performance of the scripting system is more than sufficient for most purposes. Besides, SE usually does most of the heavy lifting, so even script files do most of their work within compiled classes. And if you wish, you can also mix script code and compiled classes in the same plug-in. The easiest way to so this is to write a plug-in script "shell" and then create your Java objects within the shell.
Each of these approaches to creating plug-ins will be described in more detail later on.
CAUTION Never develop plug-ins while editing unsaved data that you care about. Plug-ins modify the internal state of Strange Eons, and can therefore cause the program (or potentially your entire system) to become unstable. Only use plug-ins with real data once you are confident that they are safe and work correctly.
A script-based plug-in consists of a plain text file that contains JavaScript code. Most plug-in developers will prefer to create script-based plug-ins due to their ease of development. They can often be developed entirely within a running copy of Strange Eons using Quickscript. It is suggested that you start with script-based plug-ins and only use compiled code if there is some significant advantage.
Scripted plug-ins are JavaScript files that contain one or more functions that parallel the methods in the Plugin interface. At a minimum, the script must include a run() function. It may optionally include getName(), getDescription(), getVersion(), isShowing(), and hide() functions. There is no explicit function call when your scripted plug-in is initialized. Instead, SE will compile and run your script. Any code in the global scope (that is, in the script but not inside a function definition) will be executed at this time, so it acts as your initialization code. SE will retain the script code after this initial run, and call your plug-in functions as needed.
The following variables will be pre-defined in your script: Eons (the main application), Editor (the active component editor), Component (the game component edited by the active editor), PluginContext (a PluginContext object), and sourcefile (the file name or URL of the plug-in script file). To see what values of a component can be changed, create a component of the desired kind and then activate the Component Viewer plug-in. To modify the way a card is laid out, you will need to set custom settings on the card. These override the settings from SE's built-in resources. There are many examples of how to do this in the extensions folder. Use the SE Resource Tool to extract the standard resources to see what settings are available to change.
You can create a plug-in bundle for your plug-in and install it normally. You can also test your script as you develop it by pasting it in the Quickscript window and adding a call to the run() function. However, this doesn't normally work for extensions because many of the actions they take are not normally permitted once the application starts. You can get around this by running the program in debug mode, although this is mainly useful for checking your script for syntax errors before going to the bother of packing it up in a bundle for testing. Running in debug mode prevents the usual checks that lead to an error if you modify the game database after the application starts, but it does nothing to ensure that the application will be consistent with your changes.
Getter/setter methods in Java may be accessed as fields in scripts. For example, all components support a getFullName() method. This method can be called from scripts using syntax like the following: println( Component.fullName ). The included examples demonstrate many of the other technical aspects of interacting with a Java application from JavaScript, and this Web page covers some of the most commonly encountered issues.
You may refer to Java classes by writing Packages. followed by their fully qualified class name, for example: Packages.javax.swing.JDialog. Shortcuts are provided for most of the standard Java packages that allow you to leave off the Packages. prefix (so javax.swing.JDialog also works). In addition, ca (the top-level package for Strange Eons classes) is predefined as Packages.ca, resources is predefined as Packages.resources, and arkham as Packages.ca.cgjennings.apps.arkham. The resources/libraries folder contains a number of utility libraries that you can include with uselibrary( libraryname ). The libraryname can be the name of any file in that folder (leave off the .js extension), or it can be a URL. (The special res:// protocol is resolved as a file in the resources folder; either the main application's, or your plug-in's.)
Examples:
Plug-in Script Template
Basic Scripting and Activated Plug-in Examples
Extension Examples
See also:
The Strange Eons Standard Scripting Library Documentation
To create a new plug-in, write a class that implements the Plugin interface. In your IDE, start a new project and add strange-eons.jar as a library. Set the "run" settings for the project to use the main(String[]) method in ca.cgjennings.apps.arkham.Splash and make sure that the virtual machine settings allow at least 512 MB of memory (-Xmx512m). Create a new class that implements Plugin, then test the result.
An activated or injected plug-in can be added dynamically from the Plug-in Manager: compile and run your project, start the plug-in manager from the Toolbox menu, choose +, Show Advanced Options, select class rather than script, and enter the plug-in's fully qualified class name (including all packages). Press Add Class or Script and the new plug-in will become available in the Toolbox menu.
An extension or theme needs to be packaged as a bundle and copied to the plug-in installation folder, but this can be made part of your build process if it is configurable.
Examples:
Activated Plug-in Examples
Case Book Formatter Examples
Theme Example
See also:
Plug-in API Documentation
The preferred way to package plug-ins for distribution is as a plug-in bundle. Plug-in bundles are easy for end-users to install and their contents are dynamically added to the class path at run time. Both class and script plug-ins can be packaged as bundles. This page explains how to create plug-in bundles.
The Plug-in Kit Documentation Index provides an overview of the rest of the documentation in this kit. I suggest that you at least look over it and the Glossary before getting started. You can look at the many examples to see particular techniques in action. To get a sense of how the various pieces fit together, check out some of the online tutorials.
Most of the "documentation" in this kit is presented in the form of examples. Some of these are standalone scripts that you can drag and drop or paste into the Quickscript window and run. Many of them, though, are complete plug-ins. Most are script-based, but a few are Java-based plug-ins which must be compiled to class files before packing. To make it easy to work with the examples, the entire plug-in kit has been set up as a project that you can open in Strange Eons using the File | Open Project menu item. From the project view, you can right click on files to: run scripts, compile Java source, pack up a plug-in task folder as a bundle, and even build and test a plug-in in a single step.
The Strange Eons web site provides some plug-in writing tutorials in Miriam Beecher's Basement. The Adding a Custom Expansion tutorial covers the basics of writing and packaging a simple extension plug-in that registers a new expansion. The Allies into Enemies tutorial builds on this background, and shows how you can add a new card type that is a customization of an existing type by modifying its private settings. The Doing it for Yourself tutorial shows you how to create whole new card types using DIY components. It also provides an example of an effective workflow for plug-in development, and it describes some of the tools that are available to help you.