-outsize -1 -1 -names -uninhabited -names-uninhabited(see below to see what this means ;))
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.
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.2+ (Starmapper 1.x requires 1.3+).
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).
See download page for a list of available downloads for Starmapper.
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.
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.
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 1which 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:
-outsize <width> <height>: image size; followed by two numbers: width and height. The default is 640x480 (like in Starmap). You can also give -1 or -2 as a dimension: -1 means "this dimension is equal in pixels to map (current clip) size in Stars! light years"; -2 means: "scale this dimension to keep proportions". Size of -2 -2 is equal to -1 -1.-preserve: tells StarmapperApp not to reset galaxy information when proceeding to next year (it will increase all report ages by one, instead, and then apply new reports). It doesn't have extra parameters. It is turned off by default.-clip <west> <south> <east> <north>: clips the map to a clipping rectangle; parameters: x1, y1, x2, y2 - that is west, south, east, north (in Stars! coords). Each of these values can be equal to -1, which means "map border".-uninhabited: tells StarmapperApp to draw uninhabited planets. Inhabited planets are little crosses, planets with stabases are squares and uninhabited planets are dots. (avaiable in 2.2+)-names: tells StarmapperApp to draw planet names; current version can only draw all names or none (none by default). Future versions will probably enhace this functionality (50% of planets, 25% of planets, e.t.c.).-names-uninhabited: tells StarmapperApp to draw names of uninhabited planets. This switch works only if -names and -uninhabited were set. (available in 2.2+)-year <year>: followeb by a year number, tells StarmapperApp to draw only one map for the specified year instead of drawing one map per year found in reports. It will still read all reports (before the specified year).-encoder <class_name>: Starmapper is using special image encoders to write generated images to disk (actually, encoders can do whetever they want, not necessarily write to disk). This switch takes one parameter - encoder's class name (e.g. jezuch.utils.starmapper.encoders.PCXEncoder, the default encoder). Encoders can accept special parameters (which are encoder-specific; see documentation for each encoder to see its parameters) - passed to it by adding one or more -encparam switches. Encoder's class has to be placed on the classpath; this can be also in a zip or jar in encoders subdirectory of StarmapperApp's installation directory.-outfmt switch used by Starmapper versions before 1.2 is no longer supported and is ignored.-encparam <param_name> <param_value>: passes a parameter to encoder; this can be image format, output directory or anything else, but is dependent on encoder. Default encoder (PCXEncoder) doesn't take any parameters.For example, the command:
starmapper -outsize 1024 768 -clip 1200 1500 1500 1800 -preserve game 1will 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".
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.
[game]: this section defines some game-level parameters (it was introduced in StarmapperApp 2.0 mainly to reduce mess in Starmapper's directory :)) - location of MAP and PLA files (in future it will also be custom filename pattern for PLA files, but right now I don't have a clear vision of that). The keys are:
map: location of MAP file that contains Stars! map definition; can be any relative or absolute pathpladir: location of directory containing PLA files; can be any relative or absolute path to a directory, not file (actually directory is a file, so this should not be a problem :))[names]: this section contains names of races and their numbers, keys in this section must be named "playernn", where nn is any integer in range 1-16, inclusive ("player00000000015" is still OK :)), and values for these keys are just race names. For example in Apocal.ini you'll find this:
[players] player01=Elezi player02=Balrog player03=NorthparkYou don't have to define all races. This section is highly recommended if you draw series of maps and don't want to have players changing their colors - if Starmapper isn't told how to assign race names to player numbers, it assigns them almost randomly (in order of occurence in PLA). Definition of race in this section is required if you're using AR starbase mapping (see below).
[colors]: like [names], this section maps player numbers to colors which will appear on the image. Keys are named the same as in [names] and colors are defined in RGB color space as 3 numbers separated by spaces or commas, that is red, green and blue (each in range 0-255, inclusive). In Apocal.ini that's:
[colors] player01=255 000 000 player02=225 000 000 player03=195 000 000Of course, everything is optional here, if you don't specify color for a race, Starmapper will use default color for this race number.
[settings]: you can optionally specify the same parameters as you would at command line: -outsize, -encoder, -clip, -names, -preserve and -year with these remarks:
-' is skipped-outsize and -clip are specified as numbers separated by spaces or commas, e.g. clip=1000 1000 1500 1500-preserve and -names are turned on by using literal true as a value, e.g. preserve=true - any other value will be treated as false-encparams will not be recognized, each encoder parameter is specified as a separate key: encoder.<param_name>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).
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.
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.
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.
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).
If you have any suggestions, problems or anything else, contact me: jezuch@interia.pl.
draw.uninhabited and draw.names.uninhabited.buffer.reuse)