Creating Variant Plugins

Variants may be created from scratch or by modifying an existing variant in a variant plugin. Variant plugins are in the "variants" directory of the jDip installation.

Adding a variant plugin is as simple as moving the plugin file to the variants directory.

Descriptions of the variant file formats are covered in the Advanced Topics section of the help file. It is highly recommended to use the existing variant plugins as examples to get started. This is easily done, as a variant plugin is just a Zip archive file.

When creating variant files, it is recommended that a proper XML editor (or XML-aware editor) is used. At the very least, check your XML files to make sure they are valid; invalid XML will almost cause jDip to report errors.

Variant Plugin File Structure

Varant Plugin Naming

Variant plugins must have one of the following file extensions (case sensitive):

*Variants.zip
*Variant.zip
*Variants.jar
*Variant.jar

For example, the file "StdVariants.zip" is valid, but "Stdvariants.zip" is not.

Variant Plugin Loading

When jDip is started, the variants/ directory is scanned for files with one of the above extensions. When found, the file is opened and the "variants.xml" contained within is parsed. During startup, only the variants.xml file and the adjacency file(s) are parsed. The SVG map files are not parsed until the map is loaded.

Variant Plugin File Format

All variant files are .zip (Zip format) files. Note that .jar is a Java-specific variant of the Zip format, and is also acceptable. The Zip format confers several advantages:

Standard across most platforms
Wide tool support for creating and viewing files
Hierarchical format permits good organization
Compression, to save disk space and network bandwith

Note that the .jar files may be renamed to .zip and opened with any standard tool for viewing or extracting the contents of Zip files.

Variant Plugin File Structure Details

A variant plugin must contain, in the root directory, a "variants.xml" file (all lowercase). The structure of the variants.xml file is detailed in the variants.xml file section.

A plugin may contain multiple variants.

An Example: SailhoVariants.zip

Inside SailhoVariants.zip, there are the following files:

sailho.svg: the SVG Map file
sailho_adjacency.xml: the Province definition and adjacency description
sailho_thumb.jpg: the SVG Map thumbnail
variants.xml: the Variant descriptions for SailHo! and SailHo! Crowded

Variant XML File Format

Introduction

All variant plugins must have the required "variants.xml" (all lowercase) file contained within. This defines one or more variants, including their SVG map, their adjacency/province information, and the starting information.

The variant.xml file decouples the map graphic, province information, and starting options which allows for easy creation of some types of variants without altering province or map information. For example, the Crowded and Standard variants only differ in their variant.xml <VARIANT> entry, which defines new supply centers, starting positions, and powers.

URI Specification

Several attributes within the variant.xml file define URIs. Valid URIs may be of the following format:

http: Loads data from an http server.
file: Loads data from a specific path on the local file system.
(directory path) Loads data from within the .zip (or .jar) variant file. Recommended.

The "directory path" version is recommended, as it does not depend upon the existence a network connection or specific local file system path. For example, if the uri was uri="dir/file.svg" the file "file.svg" would be loaded from the directory "dir" within the variant .zip (or .jar) plugin file. If the file is in the root directory of the variant plugin, only the file name need be specified.

DTD Reference for variant.xml

VARIANTS

The root element.

CONTAINS: (DESCRIPTION, VARIANT+)

ATTRIBUTES:

version [REQUIRED]

A positive integer or floating-point value denoting variant version.

VARIANT

The enclosing element for a single variant description.

CONTAINS: (DESCRIPTION, MAP, RULEOPTIONS?, POWER+, STARTINGTIME, VICTORYCONDITIONS, SUPPLYCENTER+, INITIALSTATE*)

ATTRIBUTES:

name [REQUIRED]

The name of the variant

default [IMPLIED:"false"]

Boolean ("true" or "false") value indicating if this is the default variant.

version [REQUIRED]

Valid positive integer or floating-point value denoting variant version. If two (or more) variants with the same name exist, the the highest version is used.

DESCRIPTION

Brackets the text description. Note that HTML markup (properly escaped) is not only permitted but also recommended.

CONTAINS: (#PCDATA)

ATTRIBUTES: None

MAP

Defines the province adjacency file and map graphic(s).

CONTAINS: (GRAPHIC*)

ATTRIBUTES:

adjacencyURI

URI to the Adjacency XML file. For details on the province adjacency XML file format, see Help.

GRAPHIC

Defines a map graphic (in SVG format).

CONTAINS: [Empty]

ATTRIBUTES:

uri [REQUIRED]

The URI of the map graphic SVG file.

default [REQUIRED:"true" | "false"]

Whether this is the default graphic for this variant. There should be only one default graphic per variant. This is a boolean value.

title [REQUIRED]

The displayed name of the map graphic. This is displayed under the thumbnail map image in the New Game dialog.

description [REQUIRED]

A brief description of the map graphic. This is displayed as a mouse-over.

thumburi [REQUIRED]

The URI for the thumbnail graphic of the map. This should be a 75 x 75 pixel image, in GIF, JPG, or PNG format.

RULEOPTIONS

Container for RULEOPTIONS, which describe default rule options.

CONTAINS: (RULEOPTION+)

ATTRIBUTES: None.

RULEOPTION

A Rule Option default.

CONTAINS: [Empty]

ATTRIBUTES:

name

The name of the rule option. This must correspond to a known rule option, as defined by dip.world.RuleOptions or subclass.

value

The value of the rule option. This must correspond to a known value of a known rule option, as defined by dip.world.RuleOptions or subclass.

POWER

Defines a Power

CONTAINS: [Empty]

ATTRIBUTES:

name [REQUIRED]

The name of the power; for example, "England".

active [REQUIRED:"true" | "false"]

Boolean describing if this power is active. Inactive powers have units that always hold. This is "false", for example, in the 5- and 6-player Standard variants.

adjective [REQUIRED]

The power adjective. For power "France", this would be "French".

altname [OPTIONAL]

An alternative power name. For example, Power "England" has an alternative name of "Britain".

STARTINGTIME

Details the starting phase, year, and seaon of the game.

CONTAINS: [Empty]

ATTRIBUTES:

turn

The starting season/phase/year. For example: "Spring 1901, Movement". Note that the Season, year, and phase must be a valid combination.

allowBCYears [OPTIONAL: "true" | "false"]

Boolean attribute indicating if player can start games using BC years ("negative" years). Default value is false. If a BC starting phase is found, this will default to true.

VICTORYCONDITIONS

Describes the default variant victory condition(s).

CONTAINS: (WINNING_SUPPLY_CENTERS, YEARS_WITHOUT_SC_CAPTURE?, GAME_LENGTH?)

ATTRIBUTES: None

WINNING_SUPPLY_CENTERS

The number of supply centers required for victory. This victory condition is required.

CONTAINS: [Empty]

ATTRIBUTES:

value [REQUIRED]

Positive (nonzero) integer value.

YEARS_WITHOUT_SC_CAPTURE

The number of years, without a supply center changing ownership, before a draw is declared. This victory condition is optional. If set to zero, it is ignored.

CONTAINS: [Empty]

ATTRIBUTES:

value [REQUIRED]

Zero or positive integer value.

GAME_LENGTH

The maximum length of a game, in years. This is an optional condition. If set to zero, it is ignored.

CONTAINS: [Empty]

ATTRIBUTES:

value [REQUIRED]

Zero or positive integer value.

SUPPLYCENTER

Defines a supply center for a province.

CONTAINS: [Empty]

ATTRIBUTES:

province [REQUIRED]

The province in which this supply center is located.

homepower [OPTIONAL:Power | "any" | "none"]

Power name for which this supply center is a home center. In most variants, new units may only be built at home supply centers. By default, this value is "none". If the value is "any", this supply center is a home center for any power.

owner [OPTIONAL:Power | "none"]

The power name (or "none" if no power) that owns this supply center.

INITIALSTATE

Defines the placement of a unit.

CONTAINS: [Empty]

ATTRIBUTES:

province [REQUIRED]

The province in which this unit is located.

power [REQUIRED]

Name of the power that owns the unit.

unit [REQUIRED]

The name of the unit. Typically, this is either "fleet" or "army".

unitcoast [OPTIONAL]

Defines the coast ("nc", "sc", "wc", "ec") for a fleet in a multi-coastal province. This is not optional if the province is multicoastal!

Adjacency XML File Format

Introduction

The Adjacency (or Province) XML file format defines the provinces (long names, abbreviations, and alternate names) as well as their "connectedness" (which provinces connect to other provinces).

The adjacency file may be shared between different variants when the variant differs in starting unit positions, supply center positions, or powers. However, a new adjacency file must be created for maps with different connectedness.

Defining Adjacenct Provinces

The <ADJACENCY> element defines adjacency for a given province. A province may have multiple 'layers' of adjacency; in other words, land adjacency and fleet (sea) adjacency may be different. The adjacency also defines what type a province is. Valid province may have:

mv: an inland province
xc: a sea province
mv and xc: a coastal province or an island
mv and (1 or more) coasts (nc, sc, wc, or ec): a multi-coastal province or island

It is illegal to specify an "xc" with a coast ("nc", "sc", "wc", or "ec"). This is because "xc" is the "any" or "single" coast.

If a province is an island (adjacent to multiple sea provinces with "xc" or coastal adjacency), an "mv" adjacency is still required. Since an island is not (and cannot, by definition) be adjacent to other land provinces, the "mv" definition is just a link to itself.

Borders

Borders can exist between Provinces, which can disallow certain types of orders depending upon the Border options. For example, and "ice" Border could disallow orders for units in the Fall seasons.

Note: the Border entity and attributes specifications is not yet final, and is subject to change.

DTD Reference for Adjacency (Province) XML Files

PROVINCES

The root element..

CONTAINS: (BORDER_DEFINITIONS?, PROVINCE+)

ATTRIBUTES: [None]

BORDER_DEFINITIONS

Encloses the Border definitions, if present..

CONTAINS: (BORDER+)

ATTRIBUTES: [None]

attribute_name

xxxx

BORDER

Describes a Border, which modifies how units travel between provinces.

CONTAINS: [None]

ATTRIBUTES:

id [REQUIRED]

The unique XML attribute ID of this Border. Provinces use this ID to associate the Border with the Province.

description [REQUIRED]

A text description of this Border

unitTypes [OPTIONAL]

Which units this applies to; e.g., "fleet", "army"; if none specified, it is assumed to be all units ("fleet, army").

from [OPTIONAL]

Optionally specifies if this Border only applies to certain provinces or coasts that a unit is coming from. If not specified, all 'from' locations are assumed.

orderTypes [OPTIONAL]

Defines which order types this border applies to. Order types must be full class names; e.g., to prohibit a Move order, this would be "dip.order.Move". Multiple order types must be comma-separated. If not specified, applies to all orders.

baseMoveModifier [OPTIONAL]

The amount of support (positive or negative) given to a Move or Support order for this Border. If not specified, defaults to 0.

prohibited [REQUIRED]

Defines optional restrictions (e.g., based on season, year, etc.).

PROVINCE

Defines a Province.

CONTAINS: (UNIQUENAME*, ADJACENCY+)

ATTRIBUTES:

shortname [REQUIRED]

The default province abbreviation. E.g., "stp" for "St. Petersburg". This must be unique to the province.

fullname [REQUIRED]

The full name of the province. E.g., "St. Petersburg". This must be unique to the province.

isConvoyableCoast [OPTIONAL: "true" | "false"]

Boolean value indicating if this coastal province is a convoyable coast (indicates that inland fleets can convoy). If true, and the province is not a coast, an error will occur.

borders [OPTIONAL: IDREFS]

Defines which, if any, Borders apply to this province.

UNIQUENAME

Defines an alternate unique name for the province. This is used for alternate abbreviations or spellings. There is no limit to the number of unique names attached to the province; however, each name must be unique to the province and to all other provinces.

CONTAINS: [Empty]

ATTRIBUTES:

name [REQUIRED]

The optional unique name.

ADJACENCY

Defines the connectness of a province.

CONTAINS: [Empty]

ATTRIBUTES:

type [REQUIRED: "mv" | "xc" | "nc" | "sc" | "wc" | "ec" ]

A connection layer. Army units move in the "mv" layer, sea units move in the "xc" layer, and coasts are used (for sea units only) if a province has coasts. A province may have upto 4 coasts. See the above section on adjacency for more details.

refs [REQUIRED]

Space or comma separated list of province abbreviations to which this province is connected. To reference a coast, append a hyphenated coast (e.g.: "stp" vs. "stp-sc").