Randmax v3.0

Randmax v3.0
By Steffen Pietsch and Thomas Voigt

1. Introduction

2. Overview

3. Using Randmax

4. Detailed Operation

5. Formulas

6. Version History

7. Copying

8. Contact and Disclaimer

1. Introduction

Randmax is a player addon for VGA Planets 3. VGA Planets 3 is a strategy game developed by Tim Wisseman. Most of the planet management is routine: Build factories, mines, defense posts and tax your natives and colonists. Randmax can help you do a lot of these tedious commands automatically. Controlled by a file (randmax.ini) that you can edit manually or generate automatically using the companion utility RANDGEN, randmax will automatically execute the actions defined in the ini file.

Randmax will read your player data in a subdiectory, perform the commands and write back the data. Note that you mustn't run WinPlan, VPA, PCC or any other client while randmax is running, because they will eventually overwrite the player data when they exit, or even crash because randmax altered their data.

Randmax was invented and written by Steffen Pietsch and is now maintained by Thomas Voigt.

Note that version 3 is a new major revision that introduces new features (including base maximization). The main idea behind the rewrite is that you can use randmax "out of the box" without generating a randmax.ini file, so you can just call "randmax [Game_Dir]" and get a reasonable taxation for natives and colonists. The syntax of most commands remained identical even if there were redundancies (some commands were kept only for backwards compatibility), so most older randmax.ini files should work with this new randmax version. However, you may want to update your randmax.ini files to make sure that everything works.

However, a few changes were introduced (see version history).

2. Overview

Randmax can do the following actions for you: - Randomize the friendly codes on all your planets - Automatically build factories, mines and defense posts on your planets, and sell supplies - buy defense posts or fighters on your starbases - tax your natives, either in a way that they grow fast but still allow you to collect money (growth tax), or in a way that they reach and maintain a certain happyness.

In order to build structures, randmax will automatically sell supplies.

Randmax is controlled by the randmax.ini file, which has 3 sections: "Safe" friendly codes, planetary orders and global parameters. The sections are separated by lines containing at least 3 stars at the start of the line. A "#" denotes a comment and all entries of a line after a "#" will be ignored.

The first sections contains a list of friendly codes that should not be changed. Randmax will randomize all friendly codes not contained in this list. There can be at most one friendly code per line. Wildcards "*" and "?" are allowed. A "0" is treated as a wildcard that matches any numerical value. So for example an entry "000" would match any numerical value, while "PB0" would match any priority build order (PB1..PB0).
A special entry is the word "default", which will add the following special friendly code patterns:

"NUK", "ATT", "PB0" (all build orders), "mf?" (universal mine field friendly codes), "bum", "dmp", "con", "noc" and "000" (all purely numerical codes, e.g. "042" will be protected, but "42d" or "d42" would be randomized).
The second section contains a list of commands for every planet. The first entry must be the ID of the planet, which is followed by an arbitrary number of commands, which will be executed in the given order. So for example a line "042 f50 m20 f n c1" would mean that randmax first tries to build factories until the planet has 50 factories (f50). If this is achieved and there are credits and supplies left, randmax will build mines until there are 20 mines on the planet (m20). After that it will build as many factories as possible (f) and tax the natives according to the grow tax method.
A list of all commands can be found in section 3, Using Randmax. The grow and build strategies are explained in section 4, detailed operation.

There can be an entry for a planet with id 000. This is considered a default order and will be applied to all planets that have no special order.
The third section can contain various control parameters that are described in section 3, Using Randmax. Among these orders are configuration-related parameters like the maximum income per planet or the maximal number of hissing ships, and several parameters that control the taxation and build strategies.

Note: There are several levels where commands can be defined for a planet: The command line and the second and third section of the ini file. In case of contradicary orders, they will be resolved as follows:

The most general orders are in the third section of randmax.ini.
Command-line orders will override orders given in the third section.
Orders given in the second section will override all other orders. Even a default order for planet "000". will override orders from the command line and the third section.

Note : Planets uses several files containing checksums and information about the planets version. It is necessary for RANDMAX to find these files (otherwise the checksums would be wrong). Writing of these data depends on the client, however, if a client was run once for the game then randmax will find and generate the correct checksums and register information. These information can be taken from old turns, so if you used your client normally in the previous turn, unpack a new result and run randmax immediately thereafter, everything is fine.

However, if you unpack your very first result into a fresh directory and run randmax first, then randmax will create the shareware register information and your client may or may not report an error (for example planets.exe will report that the data was tampered with, while VPA should run fine).

3. Using Randmax

3.1. Command line parameters

The basic use of randmax is calling randmax.exe with at most two additional parameters specifying the working directory (the directory where the player data files are located) and the name of the initialization file (default randmax.ini).

So "randmax c:\games\planets\vpwork1 my_randmax.ini" would tell randmax to process all game data in c:\games\planets\vpwork1 and execute commands defined in my_randmax.ini. Observe that paths that contain whitespaces must be put in paranthesis.

A number of options can be used to control the behaviour of randmax on a command-line level. Most of these commands are kept only for backwards compatibility and should better be put into randmax.ini. However, command line parameters do override entries in the third section of randmax.ini.

-h: (help) show a brief summary of randmax usage and commands and exit
-pN: process only planets of player N (1..11) (fcode randomization and structure building)
-r: don't randomize friendly codes
-cN: tax colonists on all planets with growth-tax if there are at least N million
-nN: tax natives on all planets with growth-tax if there are at least N million
-tN: tax colonists on all planets with safetax to happyness 70 if there are at least N million
-aN: tax natives on all planets with safetax to happyness 70 if there are at least N million
-d: dump a default randmax.ini
-sN: on all planets with more than N supplies, sell the excess supplies
-w: Winplan compatibility (obsolete, winplan files are detected automatically)

3.2. Planetary orders (2nd section of randmax.ini)

A planetary order starts with the ID of the planet, or 000 for a default order that is executed for all planets without an order. Leading zeros are optional (042 works as well as 42), but the randmax.ini looks somewhat nicer if you stick with 3-digit numbers.

The planet ID is followd by the build and taxation orders. All orders are executed in the order in which they are given. There is no check if there are contradictory orders, so if you put "t40 n" in your command line then the resulting tax will be according to the growth method (the taxation routine is invoked twice and the later one wins).

The following build orders for randmax are available. All orders can be given with or without a numerical parameter which gives the maximal number of structures to build. If no such parameter is given then randmax will build as many structures as possible. (So "f40" will build up to 40 factories, while "f" will build as many factories as possible.)

f: Build factories.
m: Build mines.
d: Build defense posts.
bd: Build starbase defense posts (up to 200).
bf: Build starbase fighters (up to 60).

There is a number of taxation and sell orders available. For a description of the taxation strategies see section Detailed Operation. Here N always stands for an arbitrary integer value.

n[N]: Tax natives with the growth method. Once they reach their population maximum, tax them with safetax to happyness N (if no numerical value is given this value will be defaulted to 70).
t[N]: Tax natives with safetax, aim for happyness N (default is 70).
c[N]: Growth-tax colonists (similar to n).
a[N]: Safetax colonists (similar to t).
mnN: (min natives) Tax natives only if the number of clans exceeds N.
mcN: (min colonists) Tax colonists only if the number of clans exceeds N.
ntc: (no tax colonists) Don't tax colonists at all. (Overrides the ctx command in section 3.)
ntn: (no tax natives) Don't tax natives at all. (Overrides the ntx command in section 3.)
s[NNN]: If the planet has more than NNN supplies, sell the excess supplies.
l: don't sell supplies (overrides the -s command given in the command line).

All other commands are simply ignored. This allows other utilities to add their own configuration (for example randgen may store orders here).

3.3. Configuration parameters (3rd section of randmax.ini)
The configuration parameters control several aspects of the working of randmax. Note that some of these commands work globally.

Some commands take an optional numerical value, or a yes/no value. The convention to use commands who allow both types of parameters is as follows:

If no additional parameter is given, "yes" is assumed. The numerical value is set to some default.
If a numerical parameter is given, "yes" is assumed.

Example:

"ctx" or "ctx yes" would enable colonist growth taxation.
"ctx 1" would enable colonist growth taxation with parameter 1 (at least one million clans).
"ctx no" would disable colonist taxation.

Other commands will allow only a numerical value or a boolean value. If these commands with boolean parameters are issued without a boolean value, "yes" is assumed. (So "cda" is equivalent to "cda yes".) Commands that take a numerical value are ignored if no parameter is given. The following parameter affect taxation: [yes|no|N]

Command	Parameters	Default	Description.
ctx	[yes\|no\|N]	yes, 0	Tax colonists on all planets with with growth method. If no numerical value is given, this applies to all planets with more than 3000 clans. If N is between 0 and 10 then it is considered to be the minimum number of colonists in million (or 10000 clans), if N is larger than 10 then it is considered to be the minimum number of clans before the colonists are taxed. Note that this command is global and is executed even for planets that contain no colonist taxation order. Examples: Assume that "ctx 1" is set in the third section, native taxation is done as follows: Colonists on planets with no tax order (e.g. "f m20") will be taxed with the growth method. Tax orders on a planet override the global setting. Colonists on a planet with order "a80 mc3000" will be taxed to happiness 80 with safetax if the population exceeds 3000 clans. If only the order "mc3000" is given then the colonists will still be taxed with growth tax, but already if there are 3000 clans. The only way to prevent taxation at all is by giving the "mtc" command. If "ctx no" is given, then colonist taxation will be turned off altogether. If "ctx" and "cts" are both given, then only the last command will be executed. It is recommended to enable this option.
ntx	[yes\|no\|N]	yes, 0	Similar to ctx, but for natives. It is recommended to enable this option.
cts	[yes\|no\|N]	no, 0	Similar to ctx, but with safetax. (Previous randmax versions would interpret N as the target happyness.) Can't be used in conjunction with the ctx option.
nts	[yes\|no\|N]	no, 0	Similar to ctx, but for natives and safetax. Can't be used in conjunction with the ntx option.
cth	N	40	Set the target happyness. If growth tax is used (Ctx), then this will affect taxation only after the population is maxed out. If safetax is used (cts) then colonists will be taxed such that they achieve happyness N. If cth is not specified, then this value is 40. Set this value to 70 if you want your colonists to grow using safetax. For most users it is not necessary to specify an cth option.
nth	N	40	Similar to cth, but for natives
gst	N	90	Triggers at which time the growth method reverts to safetax: N is a percentage (and must be between 0 and 100), and randmax will switch to safetax once the population reaches N% of the maximal population. The default threshold is 95%. If no parameter N is given, the option is ignored.
nt%	N	50	Deals with the issue of the "last percent": Should randmax set the tax so high such that the income exceeds the number of colonist clans, or one percent less such that there are more clans than income. If there are enough clans to collect N% of the money equivalent to 1% tax, then randmax will collect this last percent. Example: A planet has natives such that every percent of tax gains 100 credits. If nt% is set to 70, then the tax will be 1% if there are 160 clans on the planet (because we get just 60 credits for the last percent tax instead of 100), while the tax will be 2% if we have between 170 and 267 colonist clans.
mnt	N	100	Maximal native tax rate (in TimHost there is a limit of 20% for Borgs), default is 100. It is recommended to set mnt 20 if you play Borg with TimHost. If no parameter N is given, the option is ignored.
mct	N	100	Maximal colonist tax rate (default=100%).
mmc	N	5000	Maximal income per planet (default is 5000 MC with host 3.2 or later). To ensure optimal taxation, this value should be set to the maximum income configured by your host. If no parameter N is given, the option is ignored.
mnc	N	1	Minimal number of native clans for taxation. If the population is lower then we won't tax. Default is 1. If no parameter N is given, the option is ignored.
mcc	N	1	Minimal number of colonist clans before Randmax taxes colonists. This overrides the ctx order. Example: mcc=3000 will tax colonists only if there are at least 300000 colonists on a planet. If no parameter N is given, the option is ignored.
mcm	N	1	Minimal income for colonist taxation. If this income is not achievable then Randmax won't tax. If no parameter N is given, the option is ignored. Default is 1.
mnm	N	1	Minimal income for native taxation. If this income is not achievable then Randmax won't tax. If no parameter N is given, the option is ignored. Default is 1.
hca	[yes\|no]	yes	Ignored. Used to control the Avian happyness bonus, but since its value is not configurable in any host version there's no point to configure it for randmax.
not	[yes\|no]	yes	"Overtax" natives when using growth method (allow happiness values below 70). It's recommended to turn this on for optimal growth taxation. Enabled by default.
cot	[yes\|no]	yes	"Overtax" colonists when using growth method (allow happiness values below 70). It's recommended to turn this on for optimal growth taxation. Enabled by default.
rno	[yes\|no]	no	Prevents randomization of planetary friendly codes
ssp	[yes\|no\|N]	no, 0	Sell excess supplies on all planets with more than N supplies. (It is recommended to disable this option and use a client that will automatically sell supplies if money is needed, like VPA or PCC.)
cda	[yes\|no]	yes	Crystal Desert Advantage. Activate this option if it is enabled your hostconfig. (Note that, at least when playing PHOST, this option controls the growth of Siliconoid natives.) Enabled by default.
csn	[yes\|no]	yes	Crystal Sinus Behaviour. Activate this option if you play PHOST and it is enabled your hostconfig. Disabled by default.
cco	[yes\|no\|N]	no	Notify Randmax that the "climate limits population" switch is off for colonists, that is, colonists can grow up to N million on every planet. If no parameter N is given, randmax will assume N=25.
nco		no	Similar to cco, for natives.
wpl	[yes\|no]	no	Notify Randmax that Winplan is used.
bag	[yes\|no]	yes	Borg assimilation growtax: Use only growtaxtax if planet owner is Borg and there are still natives (except Amorphs). Disabled by default.
ctr	N	100	Colonist tax rate in percent. Set this to the value configured by your host if you have a different tax rate than 100%. In the default host config this is set to 200 for the Federation and 100 for all other races
ntr	N	100	Similar to ctr, for natives
mhs	N	10	Maximal number of hisssing ships per planet. Set this to the value configured by your host.
her	N	5	HissEffectRate (happiness bonus per hisssing ship). Set this to the value configured by your host.

4. Detailed Operation

Todo:

explain growth and safetax method
how does growtax work (incl. switch to safetax)
how is tax adjusted for maximum income
explain borg assimilation safetax

5. Formulas

Todo: List all used formulas

6. Version History

v3.0b	(first public version: July 2009) Added name tag to Windows GUI. Special friendly codes now include codes starting with "mf".
v3.0a	(first public version: June 2009) Fixed a bug in command line processing.
v3.0 RC4:	(first public version: January 2009) Fixed some problems with borg assimilation growth
v3.0 RC3:	(first public version: September 2008) Fixed bug that would cause randmax to crash in multiplayer games where several players were in orbit of an unowned planet
v3.0 RC2:	(first public version: February 2008) Fixed bug that would cause randmax to crash in 999-ship-games
v3.0 RC1:	(first public version: June 2007) Additional consistency checks for data added Better output for missing files TODO: Add ability to read exploremap xyplan?.dat files TODO: Make sure that no special friendly codes are generated
v3.0 beta:	(first public version: April 2007) Boolean commands in the third section take a yes or no. Many parameters are now pre-initialized to true (like colonist growth taxation, overtax flags and crystal desert advantage). Documentation was rewritten. The behaviour of the cts option was changed (for consistency). Randmax works now with 999 ship games. Randmax can now build defense posts and fighters on bases. The core taxation routines were.completely rewritten, hopefully eliminating the existing anomalies. Lizard Hisss ships are now detected and considered in the taxation.
v2.g:	(released September 2006) (bugfix) colonist taxation was sometimes off by 1 percent, causing taxes to be 1% too high or too low (bugfix) natives are no longer taxed down to 40 (or the nth value) before they reach their population maximum (bugfix) the maximum income (mmc switch) is now checked for the sum of native and colonist taxes, and works correctly for Insectoid natives. (host 3.2/ phost v3.3c change) Siliconoid max population is now 100.000*temp if the cda (Crystals prefer deserts) switch is active (new) added "bas" switch (Borg assimilation safetax): Works if planet owner is Borg and there are still natives (except Amorphs). In this case only the safetax will be used, and no tax if the happyness is below 96. (new) tax rates can be now adjusted using the ctr and ntr switches. Please note that you must set this parameter if you play a race with a nonstandard taxrate (i.e. Federation with 200% tax bonus). (new) csn switch added for Crystal sinus behaviour in PHOST. If CrystalDesertAdvantage is ON, then Crystals will grow on arctic planets if sinus behaviour is disabled, but they will not grow on arctic planets if sinus behaviour is enabled. (new) mcc switch added to define the minimum number of colonists for colonist taxations. This could be configured with the ctx option, but only in terms of millions. Now you can enter the exact amount of clans for taxation. For compatibility, the old ctx option behaves as usual, but is overridden by an mcc command. Note that the ctx option is still necessary, without it colonists are not taxed. Thomas Voigt now maintains randmax. Please report bugs and suggestions to me.
v2.f:	added "?" as Wildmark in save friendly codes; <\li> new "cco" option added for ClimateLimitsPopulation=OFF <\li> new try to correct the overtaxing option (only 69 happiness (:-(; <\li> repaired a "divide by zero" bug if You had a low nativepopulation <\li>
v2.e6:	corrected notused "cth" while safe-tax-method
v2.e5:	prevent rounding-failures with post-test of the happychange
v2.e4:	MaxOrdersAvail now limited to 20 to save memory; now also with Dump-option the comments after the planetorders are preserved (up to 40 characters);
v2.e3:	BUG-fix (nt% did not work); new WinPlan-switch "-w"
v2.e2:	only BUG-fix
v2.e1:	3rd-section-code mmc MaxMCfor host3.2-compatibility; now up to 100 safe fc's possible; 3.2-special codes implemented
v2.e0:	dump-option, now up to 20 orders possible; now coments are allowed in ini-file
v2.d4:	internal release
v2.d3:	release of v2.d2 ; a40 and t40 now works also when population not yet have reached the maximum-population (or if it decreases like natives under the oppression of cyborgs)
v2.d2:	BUG-fix for "cth" and "nth"; New code "cda" for CrystalDesertAdvantage
v2.d1:	New codes "nth","cth" (also usable for Lizard-Hiss)
v2.d0:	Planets shows false tax-incomes with insectoids; change my code
v2.C4:	BUG-fix, also with this "nt% Number" when after Number nothing came then it would go in an unterminated loop - it would hang. (FIXED)
v2.C3:	BUG-fix, when you had specified nt% and had not enough colonist, RANDMAX divided with zero and -> Runtime error. (FIXED) New switch for NoRandomizing (-r or code='rno')
v2.C2:	added output-feature. Now you can redirect all written output to a file e.g. with: RANDMAX game1 >rand.log You will get nothing on the screen, but all output in the rand.log-file. (Nice for using in automated batch-modes)
v2.C1:	now initializing of player-gamedir with '.', in former times, when you played all in one directory (without extra gamedir) RANDMAX searched in the dir \ for any files that means in the root-dir.
v2.C0:	8 new special codes
v2.B2:	now multiplayer-option (-pN like -p3 for Bird) works for shareware and registered planets-users.
v2.B1:	same as v2.B0, only register-check now works in right order (it was something in trouble with the if-then-then-else-...)
v2.B0:	new third section with special codes (= three-letter-codes) (ctx,ntx,cts,nts,ct%,nt%)
v2.A1-4:	new taxorder a; take insectoid-bonus in min; better roundings
v2.A:	new orders s and l for selling supplies
v2.9:	taxadjusting like any other order in RANDMAX.INI
v2.8:	with taxadjusting (until now only global on command-line)
v2.7b:	Only one byte changed, but without it it maximized false
v2.7a:	Fixed two bugs: 1. gets negative amounts of money and supplies when you already have more Units than allowed. 2. Did not sell supplies for getting enough cash to buy further units
v2.7:	Now support of Maxnumbers of factories, mines and defenses
v2.6:	(internal)
v2.5:	Make RANDMAX.EXE independent from my program makegood.exe
24.december 1993:	Version v2.04 is the first public version

7. Copying

8. Contact and Disclaimer

This program is provided 'as is', with no explicit or implied warranty. I disclaim all warranties with regard to this software, including all warranties of merchantability and fitness. In no event shall the author be liable for any damages resulting from the use of this program.

For suggestions and bug reports you can mail me at spock@snafu.de.
To contact the original author, send a mail to neffets@neffets.de.