Content:
Introduction
Addin library
Building addins
Build setup
Addin structure
Property panels
Events
Markers
Storing data
Getting resources
Deploying addins
Samples
API documentation (download)
Note
Introduction
Addins in JVC are seperate modules from the JVC core that third party programmers can create and distribute.
Addins are dynamically loaded by JVC.
You will need the relevant JDK (and not JRE) if you're going to compile java files!
Addin library
On the addins page of JVC's web site available addins will be listed. If you have
created an addin, let me know and i will add it to the list. This way people will only have to look at one place
in order to find out what addins exists for JVC.
The addin library will also include a list of suggestions for addins, if someone would be interested in creating it. A list of addins that is under development will also be recorded on that page.
When JVC loads it looks for *.jar files in the addin directory, but it also looks for directories in the addin directory. Each jar file, and each directory is treated as a single Addin. Therefore you can put your *.java and *.class files in a directory in the addin directory. Here you can compile the files; jvc will find them autoatic when you start JVC.
The important thing is that your class should be named the same as the *.jar file, or the directory of your addin. E.g. developing the AutoTax addin, the *.java and *.class files goes into a directory called <yourplanetsgamedir>/addins/AutoTax/*
If you're using some IDE to develop your addin; all you have is to put jvc.jar in the classpath; set the main class to jvc.JVC and set "-masterdir <yourplanetsgamedir>" as the commandline options.
Building addins
This section describes a simple setup, so you can compile java files used for addins. If your're familar with
java programming, you can skip this section.
Assuming you have installed the JDK, so the compiler is ready, you will then need to setup the files JVC uses. Use the AutoTax addin as an example. Get the sources for the addin on the addins page.
You should put the sources (*.java files) into a directory called '<planetsdir>\addins\AutoTax' (make sure the autotax addin is not in the addins directory, or jvc may use that file, instead of your compiled classes).
Now that the *.java files are in the right place, you can compile them. You may want to try to edit them first in order to change something. E.g. try change the getName() method in AutoTax.java to return "MyAutoTax" instead of "AutoTax", remember to save it.
To compile you have to type 'javac -classpath <pathtojvc.jar\>jvc.jar *.java' - hopefully this will happen without any errors. Now the addin is ready for jvc; start jvc, enter the game property dialog, and see that the name of the addin has changed to "MyAutoTax" :-)
That's all there is to it, go have fun and be creative!!!
Addin structure
In order for JVC to use your addin, it must implement the jvc.util.GameAddin interface. Besides having a few 'Information'
methods, where it describes the addin, the interface holds 3 methods JVC uses to control the addin, and 2 methods
the userinterface uses to let the addin integrate into the GUI.
The controlling methods
When an addin is installed into a game (first time, or when the game is reloaded, and the addin has been used
earlier), JVC calls the activate() method; when that methods is called, the addin can plug into the game data.
It can e.g. attach an ActionListener or a PropertyChangeListener in order to listen, and react upon game events
When JVC closes the game, all addins are shutdown, using the deactivate() methods. Addins should remove listeners, and in general shutdown themself.
When a user chooses not to use the addin anymore, JVC calls remove(). It is important that the addin 'respects' the users decision not to use the addin anymore, and it should remove all data it has stored in the game database.
The userinterface
When a user interface is used, it calls installActions() on the addins, in order to let the addins insert menus,
keyboard shortcuts and toolbar buttons. Check the GameController class to insert actions.
When the userinterface shuts down, it calls removeActions(), where the addin should remove it's actions. Note that the addin should also remove actions when it is deactivated, or removed.
PropertyPanels
Property panels are panels that is used to show and change data of some object. There are two types of property
panels; one used in general (jvc.gui.JPropertyPanel), and a specialized version used for propertydialogs(jvc.gui.JDialogPropertyPanel).
The last type has methods to apply and restore data.
An addin can insert property panels in three different places; for JVC (dialog type), for a game (dialog type), and for a single planets object (normal type).
When a property panel is used, the class name of the property panel is inserted at the proper place. JVC will then load the panel when used, and tell the panel about the object that should be presented in the panel; The panel must check to see if the object is of the propertype, otherwise it should ignore it, and deactivate components on the panel.
Global property panels
Global property panels are inserted into JVC's properties, as the "JVCPropertyPanels" property. This
is a Vector, containing strings with the class names of the property panels for JVC.
Game property panels
Game property panels are inserted into the games properties, as the "GamePropertyPanels" property. This
is a also a Vector, containing strings with the class names of the property panels for JVC.
Object property panels
Object property panels are used when a marker is selected; the marker holds a list of property panel class names,
that can display/change information of the object in the marker. So in order to use an Object property panel, the
class name should be added to the marker's list of panels (the addPanel() method).
Events
JVC fires many events and property changes. Many should be obvious when looking into the API docs; but to find
out precisely; add a listener, and print out the eventname.
Markers
A marker is an entity that represents an object in the game; The marker knows how to display the object on the
map, and what property panels are used for the marker. The marker is the 'glue' between data objects, and the user
interface.
Storing data
You can store data easily, by putting your data in the properties of JVC, a game, or a single object. JVC will
store it in the jvc's database, or the game database for you. However all the data you insert, must be removed
if the addin is removed.
All the data you store must also be Serializable, or saving will fail.
Getting resources
If your jar file contains resources you need, e.g. a toolbar image, you can use this.getClass().getResourceAsStream(sResourceName);
in order to get it.
Samples
Many of JVC's internal features are made as addins, check the addin page for samples with source
Deploying addins
When you deploy your addin you need to create a .jar file named the same way as your directory with the *.class
files, and optional data files (e.g. images, or docs). This jar file should be distributed to the players. If you
want to release the source too, zip them into a seperate file called "<AddinName>Src.zip".
API documentation
The API documentation is available as a set of JavaDoc'ed html pages. Download the API
Documentation here. Unzip it in some directory of your favorite choice and point your browser to the index.html
page.
Note:
Please note that this section is under development; as people starts program addins for JVC i will include
more information on this page. I do not want to spend too much time describe a lot of technical details, if it
is not necessary. So if you miss some information regarding addin programming, please mail me with your request,
and i will insert it into this documentation.