Welcome to the home page of Starmapper

Index:

  1. News
  2. What is Starmapper?
  3. Features and requirements
  4. Download Starmapper
  5. How to run it?
  6. How to use it?
    1. StarmapperApp commands
    2. Configuration files
    3. Options cascading
    4. File naming conventions
    5. AR races
    6. External image encoders
  7. Known issues
  8. Feedback
  9. Version history

Starmapper 1.x API
Starmapper 2.0 javadocs
Download page

Sample image: game 'Apocalypse', huge galaxy, team game (5 teams), year 2510
Here's how it would look like when drawn with options:

-outsize -1 -1 -names -uninhabited -names-uninhabited

(see below to see what this means ;))


1. NEWS!


2. What is Starmapper?

Very brief description is: Starmapper is a mapping utility for Stars! (and Stars! is a space conquest game, you can find more info at official Stars! site). It takes reports generated by the game and generates a map showing approximate empire territories.

Starmapper versions 1.x are applications. Starmapper 2.0 was completly redesigned and was changed to StarmapperLib - a library that can be used to write applications performing task described above. There's also StarmapperApp that is a default or sample console application that uses StarmapperLib, very similar to Starmapper 1.x with just some incompatibilities.


3. Features and requirements

StarmapperApp reads reports generated by Stars!, but with a bit different naming convention (see below), and a map definition file, also generated by Stars! (I've tested it with Stars! 2.60/2.70 patches I and J, but it should work with previous versions as well). It can also use optional configuration file (INI or XML) which contains numbers, names and (optional) colors of all races in the game, drawing setting for that map, definitions of AR bases and other parameters. Configuration file is not required, but strongly recommended - see below. Finally, StarmapperApp calls StarmapperLib to generate a map and writes it using one of the encoders.

All it requires is a Java-enabled operating system and Java Runtime Environment (see below) version 1.4+ (it's been awhile for enough time already, I think).

The main thing about Starmapper is that it can do batch processing - and that's why I started to write it. I like doing yearly Stars! reports and generate an animated GIF showing history of my empire :) But I didn't find any utility that could draw 100 maps at one session (I used special BAT file with good, old Starmap, but it stopped working on my computer)... And here comes Starmapper! :) You can collect all the maps from the game (from any number of players) and draw a series of maps... Starmapper includes year number on the output image (sort of timestamp), so you won't get lost in the history. And the "side effect" is that it is very fast (that wasn't my goal, actually) - on my Celeron 500 machine it generates a typical map (640x480 pixels) of game in a huge galaxy in about 4 seconds :) Anyway, that's why it uses a special naming convention for report files (it has to distinguish reports from different years).


4. Download Starmapper

See download page for a list of available downloads for Starmapper.


5. How to run it?

Starmapper was written in Java (more precisely, Java2, which is a fancy name of JRE from version 1.2 - it won't work with JRE 1.1.x and below) and therefore requires Java Runtime Environment (in current version - 1.4 - it's about 11 MB, 1.3.1 is about 5 MB; Starmapper 1.x requires JRE 1.3+ and Starmapper 2.0 requires JRE 1.2+). The good thing about it is that you can run it on any Java-emabled platform (which includes any type of Windows, Linux, Solaris, Mac and a few others). You can get JRE for example from SUN's Java page.

There's no special installation procedure for Starmapper, just copy all the files into separate directory and that's all (more detailed instructions are listed in readmes included with downloads). One important thing is that Starmapper 2.0 is not an application itself but a library and can't be run directly, so you'll need an application such as StarmapperApp or StarmapperGUIApp. These two applications are also part of the Starmapper 2.0 project and are available on the download page.

Default Starmapper 2,0 applications are packed into executable-jars (starndard Java deployment method), that simplifies the launching process, but not to a level of typical luser ;) so I included a DOS BAT file with StarmapperApp that can be used on Windows to launch it (just go to console and type commands ;)). StarmapperGUIApp doesn't require such tricks, duoble-click on the jar should launch it without problems.


6. How to use it?

Here's a description of StarmapperApp (which also applies to Starmapper 1.x in most areas) which is a console application. Check out Apocal.ini and related MAP and PLA's for examples.

6.1 StarmapperApp commands

You can run StarmapperApp without any parameters to see the usage info, but here's the summary of options:

The syntax of StarmapperApp is:

starmapper [switches] <gamesig> <playernum-1> [<playernum-2>...]

In Starmapper 1.x <gamesig> is just an abbreviation of game name (you should know it - it's the part of names of all game files before dot ;)). Starmapper 2.0 also accepts here a name of configuration file (e.g. Apocal.ini) which in turn can define game signature. Following are numbers of players whose reports are to be used to draw the maps (StarmapperApp will search the current directory or the source directory specified in configuration file for files matching the naming convention and all supplied player numbers). The basic usage is for example:

starmapper game 1

which will draw maps for game named "game" according to reports of player 1.

There's a bit more about signature (I should rename this part) and configuration file: for Starmapper 2.0 the default behavior is that "signature" is a name of configuration file - it recognizes it by an extension, that is by existence of dot (Apocal is not a file name, but Apocal.ini is). This can also be any relative or absolute path in a filesystem, so you can lauch StarmapperApp from it's installation directory and point it to a configuration file somewhere else. If "signature" is a file, StarmapperApp tries to load settings from it (and throws error if the file does not exist), removes extension and pathname and sets it as the signature (e.g. c:\starmapper\pla\Apocal.xml becomes Apocal). If this is just a signature, it tries to load <gamesig>.ini from a current directory and proceeds without configuration file if this file doesn't exist. There's also possibility to load settings from a XML file (by pointing it to <something>.xml), but XML is rather user-fiendly (opposed to user-friendly)... If you're desperate to use XML for this, check out StarmapperApp.dtd and Apocal.xml in StarmapperApp's download :)

This is a detailed list of switches that can be applied to StarmapperApp:

For example, the command:

starmapper -outsize 1024 768 -clip 1200 1500 1500 1800 -preserve game 1

will draw maps 1024 pixels wide and 768 pixels high of a 300ly x 300ly rectangle somewhere in the middle of map for player 1 in game "game".

6.2 Configuration files

You can create optional configuration files (INI, XML, maybe other in future - .properties?), which can hold lots of useful information. In Starmapper 1.2 the format of INI files was changed, so users of previous versions will have to convert their INI files to new format (Windows-like). The file is split into sections (marked with name in braces, e.g. [name of section]), which contain set of values assigned to keys in form <key>=<value>, one pair per line; everything before "=" is a key and everything after is a value.

StarmapperApp's configuration file can have following sections: [game], [names], [colors], [settings] and sections for AR starbase mapping named [starbases.<race_name>] (see below). All sections are optional, and all of them can be empty.

WARNING! all section names and keys are case sensitive, so StarmapperApp won't see section [Names] or key Player1. Unrecognized sections and keys are ignored.

Configuration files are not limited to INI, they can also be written as XML files - the syntax is defined by StarmapperApp.dtd included with StarmapperApp. You need to have dom4j installed, probably augmented by a XML parser, such as Xerces (dom4j itself doesn't require a XML parser as it has a small internal parser).

6.3 Options cascading

There are three sets of settings in StarmapperApp - internal defaults, settings in configuration file and setting specified at command line. Options cascading means that settings from lower level are "shadowed" by settings from higher level. Defaults have the lowest priority, settings in configuration file override defaults and settings from command line override defaults and settings from configuration file. Of course, only parameters assigned a new value change their values, the rest is left unchanged from lower level. The same applies to encoder's parameters with the exception that defaults are defined in encoder, not in StarmapperApp and if you change encoder defined in configuration at command line, all encoder parameters (both from configuration and from command line taking into account possible overriding) are passed to it. Encoder should ignore parameters it doesn't need, but that's up to encoder's author.

6.4 File naming conventions

StarmapperApp uses up to three types of files: PLA, MAP and configuration files. When you specify the game signature (the <gamesig>), it reads the map in <gamesig>.map (generated by Stars! with Reports/Dump to Text File/Universe Definition menu option). Then, it tries to read all the settings from configuration file (see above). Configuration file is not required, but it is strongly recommended - Starmapper must know numbers of players whose reports it uses. If there's no configuration file, there's no way to find out which player has which number. If in one of the reports it finds unknown player, it gives him first free number, and usually it is not the one in the game.

After reading the universe definition and players definitions, StarmapperApp looks for reports (in current directory or in a location defined in configuration file). If it finds any file named <gamesig> <year_number>.p<player_number> and the player_number is in the list of player numbers to draw, it adds it to drawing pool. It then iterates through years, starting at 2400, and if there's any report in the pool from this year, it starts to draw the map. Future versions will probably allow to override the default filename pattern.

6.5 AR races

Like in Stars! help file, in Starmapper AR races need a separate chapter, because they're a nasty thing (special AR handling was added in Starmapper 1.2). When Stars! creates a report (PLA) and encounter a planet owned by enemy AR race, it writes "0" as its population (and it writes nothing for non-AR planets with unknown population). Of course, there's no way to tell what's the real population of that planet. If you don't tell that, Starmapper assumes default planet influence as for AR planet with 1500000 population. The way to override this is to define another section in configuration file (INI), named [starbases.<race_name>]. To do that, you must define <race_name> in section [names] (due to internal performance reasons...). Keys in that section(s) are names of starbases used by that race, value for a key may be estimated population for that base or name of previously defined base (sarbase hulls are predefined with default values, which can be overriden). So, you could do something like:

[starbases.Elezi]
Orbital Fort=100000           ;override default value
Shores of Hell=Orbital Fort   ;reference previously defined base
Gate to Limbo=Shores of Hell  ;reference to reference to previously defined base will work as well ;)

Predefined populations for starbase hulls are 3/4 of maximum population that can fit in that hull (e.g. 750000 for Space Station). Populations defined in this section are "converted" to sizes comparable with non-AR races, that is maximum population of AR race becomes maximum population of non-AR race. This sort of scaling is not possible if the report was made by AR, so if you're playing AR, your territory will look bigger than it should :)

Information defined in these sections are used only if Starmapper encounters planet with 0 population and Starmapper treats race as an AR only if it has a starbases section.

6.6 External image encoders

Installing external encoders is as simple as copying the file containing encoder to encoders subdirectory of StarmapperApp installation folder. Starmapper will seek this directory for *.zip and *.jar files which can contain image encoders. After copying the file, you can use the encoder with -encoder switch followed by encoder's class name (case sensitive).


7. Known issues


8. Feedback

If you have any suggestions, problems or anything else, contact me: jezuch@interia.pl.


9. Version vistory


SourceForge Logo Valid XHTML 1.0! Valid CSS!

Jezuch, 2002-2003