Script not executed will stop foreign frames.

UGMT/Technical Details

Introduction

The current state of affairs does not warrant a CVS repository. Source Code is always included in the jar-files. Regarding the licenses please read the header files of the included Java-files. Each separate zip file should also include a separate license file, which gives details on the files that are not source code.

There is still much to do with respect to this documentation. If you find something missing, questionable or misrepresented or otherwise wrong, tell me. I will adjust it. That having been said, let's get down to the details. The UGMT consists of two separate pieces. (1) The framework, features of which are only interesting to the developer. If anyone is interested in contributing code - whatever the license and be it in plugin or framework - feel free to contact me. (2) The plugins, each of which solves a different purpose. You can streamline your application by omitting the plugins you don't need to save memory or other scarce resources. Or you can add plugins as they become available. The download section contains all downloads.

The discussion below assumes you have the data and state files at your disposal. All files, except the java property files adhere to an XML-syntax. The syntax is specific to each plugin. The file formats will be discussed in excerpts. They are not hard to understand.

Framework

The framework will look for all directories in the location it is started. There must exist a jar-file of the same name as the directory and a property file. The Main-class form the jar-file is started. For details on the interfaces used, consult the code. All valid plugins are then put in a tabbed pane, from which the user can select. A listener pattern is used for inter-plugin communication. The framework has properties with respect to the layout. Windows (which contain tabbed panes) can be created for plugin groups by specifying "window.1 = x,y,...", where "x,y,..." is a comma-separated list of plugins to show in that window. Plugins not listed will get a separate window. If you set the property "tabs.popup" to "true", plugins are allowed to raise a other plugins programmatically.

All plugins support the properties display.width and display.height in their own respective property files. It is the responsibility of the plugin to read them. These properties determine the initial requested size for the major part of the plugin, e.g. a map display.

The frameworks reads in all files COPYRIGHT* in the individual plugin directories before actually reading the plugins. It reads the first line of each file and shows these in a splash screen. You can thus add several data sections whith different copyrights for a single plugin.

Calendar

The plugin reads in a file called data.xml. The field node daytime carries an attribute delta, which specifies the number of minutes the dusk and dawn may vary in the course of a year. E.g. 120 means the shortest daylight time is 8 hours, the longest 16 hours. The moon field is obvious - only one moon is allowed. Each month has a name, a number of days, and a season it belongs to. The index specifies the order in which the months appear in a year. An event has a date(within the month) and a name, which appears on the GUI. The type is optional to allow for grouping. It is currently just shown and otherwise unused. The img attribute is optional as well, and allows to display an ion beside an event.

The sunsign node, a singleton, has a name for a sunsign, the length this sunsign lasts and and index to give the order in which the sunsigns appear. Note that according to Hârnmaster rules the leading and trailing days are called cusps, which belong to both adjoining sunsigns. This is depicted on the GUI as well but cannot be altered through changing this file.

The properties file contains the standard properties, compound.width and compound.height, which specify the size of each individual event on the GUI. The entries yesterdays and tomorrows control how many events into history and the future are shown.

Characters

The properties file contains the standard properties, and branch.hide, which when set to true will initially hide subtrees of skills on the GUI. Otherwise they will be shown. The state.xml will contains the skills and attributes of all characters in a straightfoward format. The data.xml has a rather complicated structure, which is detailed in the accompanying chars-rules.dtd.

Export

The plugin has three properties. The port which is the port the HTTP server socket listens to. Another is the default mapsize, which is initially shown on the spinner. The last is export, which is a comma-separated list of other plugins, which are exported.

Groups

The plugin reads in a file called data.xml. It contains a list of all available travelmodes. Each such node contains the name of the mode and it's type, whether land or water. Water modes also have the attributes grades and deploy. The former is a colon separated list of letters, which must match grades avaliable to the Travel plugin, which evaluates these to obtain a speed for given weather and water conditions. the latter gives the maximum deployment available to this travel mode, typically the amount of sail that can be set. All of these entries are seen as combo-boxes on the GUI.

The properties file contains the standard properties, speed.number and speed.increment. These two give the number of options available for the land speed combo-box and the step increments of these option, which always start at zero.

The plugin reads in a file called state.xml. This file may change whenever the user saves his state, for instance after adding members to a group. Each group node contains a name attribute and map, x, y attributes, The latter three specify the map-coordinates the group is currently on. The default speed of the group is also an attribute as is the current date and time. The format of the date is specified by the Calendar plugin. Subnodes are travelmode, which is obvious and members. Members are only names in this version.

Index

The properties file contains only the two standard properties. The plugin will read all directory and the index.xml therein and interprets them as index files. An index file contains entry nodes with a name and value. The name appears on the GUI (without the trailing ".xml", while the value specifies the HTML-page to display on the right, if the name is selected on the left. An entry may contains area subnodes which have shape attribute, with allowed values "poly", "rect", and "circle" and coords which specify this shape. The href attribute names the map this area belongs to. Basically these can be read like a clickable image maps, that are in common use on the Web. The targets are the maps from the Map plugin.

Maps

The plugin reads the file specified in the property fog, which contains the fog of war overlay. It also reads all directories in it's own directory and expects to find an XML-files in it. These files are all read and united. All must have a name in it's root node and a vicinity attribute. This number is used to determine the travel rate by surrounding color values, if the original pixel does not return a proper value (s.b.). Each atlas has color subnodes which map a color value to a vegetation, a terrain, none, or both. All colors on the map must be present as nodes. The values calculated are forwarded to the Travel plugin. Additional subnodes specify maps. Each has attributes name, img, scale, and tacticalspeed. The first is for selection lists on the GUI, the second specifies the actual map file. The third gives the scale in pixels/league and the last the importance of a groups default speed. A "0" means this speed is ignored and the travel plugin will only determine a rate through weather and terrain effects, while a "1" means the opposite: only the group speed is used for determining travel times.

The map nodes can now have additional attributes raster, layer1, layer2, layer3. The first gives the image that is used to determine terrain type, if the genuine map image cannot be used. The layer attributes specify overlays, preferably with large transparent sections, that can be swicthed on and off (cf. maps tutorial.)

Each map node may have an arbitrary amount of border subnodes. Each has four attributes which specify a rectangular region on the map, which is considered a border region. Any time the active group enters that region the group moves onto the map given in the map attribute, whereby its coordinates on the current map undergo the transformation given in the transform attribute. The transform is a sequence of six numbers "a;b;c;d;e;f" separated by semi-colons. The new coordinates (x',y') are then calculated from the old (x,y) through x'=ax+by+c and y'=dx+ey+f. Make sure that the scales fit, if you use non-isometric mappings. Also make sure the border regions are chosen in a manner to avoid endless regressions and constant map changes when groups straddle the borders.

The properties file contains the two standard properties plus highlight, a color with alpha channel to highlight the polygons from the Index plugin. Another color called hyperlink is used to show linked maps.

Sketch

Each sketch entry may contain a corresponding txt, png and/or html file. Within the plugin only the former two are created, and the PNG is 1000x1000. Others must be supplied through external means. Don't combine HTML and TXT. Moreover, HTML is only readible. Othrwise read-only flags are honored, such that drag/drop does not work then. (Color PNGs may be brought in, but not created with the plugin.)

Skills

The properties file contains the two standard properties. The plugin also reads in a file called data.xml. This file contains the list of categories/types which will further determine a rolled skill success level. The state.xml file, which is also read, contains the skill-lines mapped to skill-groups in XML-format.

Sounds

The properties file contains the two standard properties. The plugin also reads in a file called data.xml. This file contains the list of valid weather events/conditions that may be keyed to sounds. The state.xml file, which is also read, contains the sound-lines in XML-format.

Travel

The properties file contains the two standard properties plus mark, the image which focuses the group on a map. The plugin reads in a file called data.xml. It contains a list of all travel modes and their value given a certain terrain and vegetation. The hierarchical manner in which this is organized explains itself. A travel mode may be missing for certain terrain/vegetation/weather combinations. In that case, a travel rate of "0" is assumed. A special role is played by the terrain "water". It does not use vegetation sub-nodes, but rather wind subnodes. This node has a name with two numbers separated by a colon. The left number is an angle between the direction the vessel is moving in and the direction the wind is blowing from. The right is a wind speed. The next subnodes then give all movement rates this combination in an again self-explanatory way.

There may be arbitrary forcedspeed nodes which give a multiplier value for a certain travel mode specified in the name attribute. Default is "1.25". There must be a direction node for each direction the wind may be blowing from. This gives the angle (degrees) of this wind direction from the x-axis. The North direction is generally the y-axis, and thus has the value of "90".

Weather

The properties file contains the two standard properties plus mark, the image which focuses the group on the right weather GUI. compound.width and compound.height, which specify the size of each individual event on the GUI. The entries yesterdays and tomorrows control how many events into history and the future are shown. There may be more entries, each of which specifies an image to be shown on the weather table for certain weather phenomena. If one is found the icon will be used, if not the string will be displayed instead.

The plugin also reads in a file called data.xml. It contains compound nodes, which specify cloudcover, winddirection, events, etc. Except for "event", all items must be present. The nodes are later referenced from the state file, which matches dates to weather compounds. There are also condition nodes which specify whether a travel-impairing condition is present. Each condition has a name and a value. If a value attribute is not present, it defaults to "1". If this threshold value is reached, the condition is present. Each condition may be effected through various events. This is documented with effect nodes. Any time an event is active that is listed for a condition, the value of the condition is increased. Everything else will lead to a decrease of "1". As this value increases or decreases above or below the threshold, the condition becomes present or absent, respectively. Instead of various effect nodes, a single reference node may be present. In that case the referenced and referencing conditions use the same value but with different thresholds. Conditions listed higher up take precedence over conditions lower in the list. A condition may be missing both effect and reference nodes. In that case an effect node with the name name and value 1 as the condition supernode is taken.

The plugin also reads in a file called state.xml. This file contains a name attribute - which is a date-time as given by the Calendar plugin - and a compound attribute, a reference to a compound from the data file. For each of the conditions from the data file, there may be a attribute, which specifies the value present during that day-time. (Note that the threshold need not be reached.) Everything not present is taken as "0".

Other Plugins

Technical details will be provided on request. It takes time to write these details and whenever they change, this page has to be updated. Currently I have no feedback for this page. If you want the details of one of the newer plugins, write me an e-mail and I will tell you.

Last modified 2005-10-10 by Michael Jung <miju@phantasia.org>
Contents