Programming

=Programming VASSAL=

A collection of queries, tips and code fragments that might be useful.

PLEASE NOTE: The code examples are fragments to illustrate the point and are incomplete and displayed out of context.

I want to help with VASSAL programming. How do I go about this?
In no particular order you should:
 * Read the programming tutorials.
 * Install a Java Development Environment (Look here).
 * Register at the Sourceforge site. Look at the Requests For Enhancement (RFE) and Bug Reports.
 * Download the source. Use the latest stable version or work from the cutting edge by anonymous CVS
 * Start studying! Use the debugger in your IDE to see what makes VASSAL tick!
 * Have a look at the Developer's Corner page.
 * Ask questions! Don't be afraid to ask for help, VASSAL is a complex, but brilliantly engineered piece of software - the learning curve is steep!

Where can I find out more about Java?
The online Java Tutorial from Sun is ESSENTIAL reading!

It covers
 * Java language.
 * Swing - The display mechanism used by VASSAL.
 * Utility classes provided by the Java SDK.
 * Much, Much more.

What version of Java should I be using for development?
All of our code targets Java 5 (also known as Java 1.5). We can't yet move to Java 6 due to a large number of users still running Mac OS X on PPC chips, for which there is no Java 6.

I have created a new custom counter Trait, but it keeps dissappearing from my counters!
Make sure you have created a custom CommandEncoder that overrides createDecorator to create your new trait (See here). Unless you do this, you custom traits will dissappear from your counters each time you load a game.

What's the difference between State and Type?
Type data is defined at Module creation time and is stored in the buildfile in the module. Type data will generally not change while a game is in progress and is not saved in the game savefile. The type data for a component is maintained using the AbstractConfigurable interface. The type data for a Counter Trait is maintained by a user written PieceEditor class returned by the EditablePiece.getEditor call.

State data is the data that changes as a game is in progress and represents the current state of components. State data is saved either in the game savefile or logfile (for shared state data), or in User Preferences (for local state data).

How do I make a Dialog or Window stay on top?
Create the window or dialog with the VASSAL main frame as the owner:

What is an easy way to display an Image?
Create an ImageIcon and use a JLabel:

Can I subclass a VASSAL component?
Yes, as long as it is a component defined in the buildfile and any instance variables you need to access are either protected or have protected or public getters and setters.

To activate your new component, you will need to edit the buildFile of your module. e.g. Change:

 to 

How do I use preferences?
Preferences record state information that is local to a single user. Preferences are stored on each players PC and are accessed from the File -> Edit Preferences menu option. Preferences are automativally saved to disk.

Preferences are added by first creating an appropriate Configurer, and then adding it to the appropriate Preferences tab. The following code creates a preference tab name "VSQL Preferences" if it does not already exist and adds a String preference with a key of "ruleLevel" and value of 3: You would typically place this code in the addTo method of a component. Use to just set the value. To read this preference use: See VASSAL.preference.prefs.java for more details.

Eclipse cannot find my main class org.vassalengine.main?
Couple of things to check in the Run... or Debug... setup (as opposed to the the VASSAL project properties setup):

1. Main Tab Make sure the main class is org.vassalengine.Main exactly...not org.vassalengine.main Make sure you have 'Include external jars when searching for a main class' clicked on.

2. Classpath Tab Make sure VASSAL.jar is included here.

How do I process every piece on a board?
Use Map.getPieces to get an array of all GamePieces on the board. Each GamePiece in the array will be either a Stack or an individual piece. Process the pieces using the PieceVisitor pattern. For a good example on how to do this, see see GlobalCommand.java.

Alternatively, you can do something quick and nasty like: