Vagabund (VGA Planets): PQBOOST - PHOST3 Build Queue modification

+------------------------------------------+
| PQBOOST PHOST3 Build Queue modification |
| version 2.0.4 |
+------------------------------------------+
(http://phost.de/~vagabond/addons/#pqboost)

0. NOTE

If you switch from QBOOST to PQBOOST, then you cannot use your old
configuration files. The syntax of the command line is different
and the first line of pqboost.cfg has to start with "% PQBOOST".

1. WHAT IS PQBOOST?

PQBOOST is a small freeware host add-on for the VGA Planets host program
PHOST Version 3 and higher. It is a PDK version of QBOOST. QBOOST's
TeamGameMode has been replaced by an AllianceGameMode.

This add-on is meant to be executed in the AUXHOST phases of host
processing.

PQBOOST is a program for MS-DOS and UN*X which modifies the PHOST
configuration file PCONFIG.SRC in order to give weak players better
chances to build ships after the 500 ship limit is reached.

The current implementation of the PHOST3 build queue favors strong players
who already have a large number of ships. Weak players cannot build ships
if the stronger players have accumulated a high player activity level
(PAL) and get turn activity level points (TAL) each turn.

The PCONFIG parameter PALPlayerRate configures how much accumulated
player activity (PAL) and current player activity (TAL) will affect the
build queue priority of old and new ship build orders. Therefore, PQBOOST
aims to modify this parameter each turn in order to adjust the effect of
TAL and PAL so that weak players get a higher boost for the same activity
than strong players.

Consider a race with 200 ships successfully destroying an enemy starbase
and a weak race with 10 ships doing the same. Evidently, the weak race
took a much higher risk. But both races get the same TAL, their new build
orders will therefore get the same build queue priority. With PQBOOST, the
weak race will get a much higher priority than the strong race.

Take another case: the strong race fights 20 battles per turn, the weak
race cannot do the same, therefore the build orders for the strong race
will always get a higher priority. Thus, the weak race won't build any
ships anymore once the ship limit is reached.

Get the PHOST docs for more information about the PHOST build queue.

2. QUICK START

If you have no other utilities running in AUXHOST2 (no AUXHOST2.INI file
present), then your PQBOOST setup becomes easy:

To run PQBOOST, copy all files into the host game data directory, then
change the following 2 lines in PCONFIG.SRC:
ShipBuilding_1 = Normal
to
ShipBuilding_1 = Execute pqboost1.ini
and
ShipBuilding_2 = Normal
to
ShipBuilding_2 = Execute pqboost2.ini

For security purposes, PQBOOST is configured to hide the extent of the
changes from players. This can be changed (see below PROGRAM OPERATION).
To increase the effect of PQBOOST, modify RelativePower in PQBOOST.CFG up
to 5. See below (PQBOOST.CFG) for more info.

If the game is a game with "CPEnableAllies = Yes", consider to set the CFG
parameter AllianceGameMode to 1 (see below PQBOOST.CFG).

If your PHOST setup already contains an AUXHOST2 phase, or other add-ons
running in the PHOST3 fine grain phases, then follow the instructions
in DETAILED PROGRAM OPERATION below.

3. FILELIST:

PQBOOST comes with the following files:

PQBOOST.EXE the executable (MS-DOS only)
PQBOOST.C the source code
PQBOOST.TXT this file
PQBOOST.CFG default configuration file for PQBOOST
PQBOOST1.INI PHOST3 PCONTROL file
PQBOOST2.INI PHOST3 PCONTROL file
AUXHOST2.INI file for the AUXHOST2 phase

PQBOOST.EXE can reside anywhere on your harddisk, PQBOOST.CFG, PQBOOST1.INI,
PQBOOST2.INI and AUXHOST2.INI must reside in the host game directory.

4. DETAILED PROGRAM OPERATION

PQBOOST takes up to four commandline parameters, the first determines the
phase (-p1, -p2, -p3), the second an optional error log file, the third
the host game directory and the fourth the VGAP root directory:

pqboost [options] <GameDirectory> [<RootDirectory>]

options:
-h OR -H -- prints help summary and exits
-v -- prints program version and exits
-e file -- use `file' as an error log file
-p phase -- PQBOOST phase

Example: pqboost -p1 c:\vgapl\game1

PQBOOST runs in three phases:
-p1 before the PHOST3 fine grain hosting phase ShipBuilding_1
-p2 before the PHOST3 fine grain hosting phase ShipBuilding_2
-p3 in the AUXHOST2 phase
For a detailed description of what PQBOOST does in those phases see below
under PQBOOST phases.

Instructions for setting up your PCONFIG.SRC file for running PQBOOST:
Copy the files PQBOOST1.INI and PQBOOST2.INI to your PHOST game directory
and modify PCONFIG.SRC in the section called %PCONTROL.
Replace the line
ShipBuilding_1 = Normal
with the new line
ShipBuilding_1 = Execute pqboost1.ini
and replace the line
ShipBuilding_2 = Normal
with the new line
ShipBuilding_2 = Execute pqboost2.ini
Copy the file AUXHOST2.INI to your host game directory, too.
If you already have an AUXHOST2.INI file, copy the line from the PQBOOST
AUXHOST2.INI file to your AUXHOST2.INI file.

If you run PHOST from a different directory than the game data directory,
you must modify the three INI files to contain the current path to PQBOOST.EXE
and to the game data directory.

Example: Assume that PHOST.EXE and PQBOOST.EXE reside in C:\PHOST and the
game directory is C:\PHOST\GAME1. Then each call to PQBOOST in the
three INI files must be as follows:
C:\PHOST\PQBOOST -p# C:\PHOST\GAME1
where -p# denotes the respective PQBOOST phase.

Now PQBOOST is ready to run.

PQBOOST uses the following files from your game directory:

SHIP.HST (the host file containing all ships)
HULLSPEC.DAT (the hull specification file)
PCONFIG.SRC (the PHOST configuration file)
PQBOOST.CFG (the configuration file, if present)
AUXDATA.HST (the PHOST file containing the alliance info)

Since PQBOOST is linked with the PDK library these files are
required too:

beamspec.dat
torpspec.dat
race.nm
engspec.dat
truehull.dat
xyplan.dat
planet.nm
nextturn.hst
pdata.hst
bdata.hst
mines.hst
gen.hst
hullfunc.txt

All files have to be in the same directory, otherwise PQBOOST will quit with
an error message.

PQBOOST modifies only the line containing the parameter PALPlayerRate in
the PCONFIG.SRC file. PQBOOST will generate a backup of the old PCONFIG.SRC
file called PCONFIG.OLD. PQBOOST will skip all empty lines containing no text.

PQBOOST will create a ASCII text log file in the game directory called
PQBOOST.LOG. Study this file to see whether PQBOOST ran successfully.

PQBOOST will additionally create a temporary file called PQBOOST.TMP which will
be deleted during phase 3 and a temporary file named PCONFIG.QBO which will be
erased automatically in each phase.

6. PQBOOST.CFG

The first line should be "% PQBOOST". Lines beginning with the character #
will be regarded as comments, like in the PHOST file PCONFIG.SRC.

The CFG file contains up to eight parameters (see also FORMULAS below).
- EnableSecurity (1 or 0, default 1) determines whether the players can see
the modifications made by PQBOOST to PCONFIG.SRC (see SECURITY ISSUES below).
- BeamsRequired (default 5, minimum 0) determines how many beams a ships must
have to count for the computation of battlemass.
- Baysrequired (default 3, minimum 0) determines how many torpedo tubes or
fighter bays a ship must have to count for the computation of battlemass.
- RelativePower (default 2, minimum 1, recommended range 2 to 5) determines
how the battlemasses of each race will be weighted for the computation of
the PALPlayerRate parameter. The value can be any real number, such as 2.3.
RelativePower allows the host to modify the effect of PQBOOST on the stronger
races. The higher the setting, the more pronounced will be the difference
between the stronger and weaker races (with the weaker getting even more
of an advantage).
- EnableESBandFCB (0 or 1, default 0) if 1, the hull mass is boosted according
to the pconfig.src parameters EngineShieldBonusRate and AllowFedCombatBonus.
- AllianceGameMode (0 or 1, default 0) if 1, alliances have an influence on
the allies' PALPlayerRate -- it will decrease.
* ShipFactor (range 0.0 to 1.0, recommended value 0.4) determines how
a ship level alliance will be weighted for the computation of the
PALPlayerRate parameter.
* PlanetFactor (range 0.0 to 1.0, recommended value 0.2) determines how
a planet level alliance will be weighted for the computation of the
PALPlayerRate parameter.
* MinefieldFactor (range 0.0 to 1.0, recommended value 0.3) determines
how a minefield level alliance will be weighted for the computation of
the PALPlayerRate parameter.
* CombatFactor (range 0.0 to 1.0, recommended value 0.4) determines how
a combat level alliance will be weighted for the computation of the
PALPlayerRate parameter.
* VisionFactor (range 0.0 to 1.0, recommended value 0.2) determines how
a vision level alliance will be weighted for the computation of the
PALPlayerRate parameter.
- ShowRanking (0, 1, 2 or 3, default 0) if 1, an individual message about the
ranking list position will be sent to each player. If 2, a public ranking
list according to the battlemass will be generated. If 3, the battlemass
of each player will be shown too.
* ShowTotalBattlemass (0 or 1, default 0) if 1, each player will be
informed about the total battlemass.
* RankinglistInterval (min. 1, max. 255, default 1) determines wether a
ranking list will be shown each turn.

Examples of the effect of RelativePower on PALPlayerRate:
A RelativePower of 1 means that a player owning 30% of the battlemass of all
races will have a PALPlayerRate of 70.
For higher values of RelativePower, the PALPlayerRate will change depending
on the relative strength of other players. In our example, let us assume for
simplicity that only 4 players are playing. Two cases are considered, one in
the battlemasses are distributed as 50% 30% 10% 10% and one in which they are
30% 25% 25% 20%. The tables below gives the resulting PALPlayerRate for
different values of RelativePower:

Mass | 50% 30% 10% 10% Mass | 30% 25% 25% 20%
-------|----------------- -------|-----------------
RelP 1 | 50 70 90 90 RelP 1 | 70 75 75 80
RelP 2 | 31 75 97 97 RelP 2 | 65 75 75 84
RelP 3 | 19 82 99 99 RelP 3 | 59 76 76 88
... | ... |
RelP 10| 1 99 100 100 RelP 10| 25 88 88 99

As one can see, the higher the RelativePower parameter, the more pronounced
is the difference between the PALPlayerRate of the strongest and weakest
player. Furthermore, the player owning 30% of the battlemass will not have the
same value for a RelativePower larger than unity in both cases, rather his
PALPlayerRate now depends on his relative strength.
Very high settings, such as 10, will make it almost impossible for strong
players to build new ships (as in case 1) or will make the difference between
players with almost equal battlemass (see case 2) inadquately large.

7. FORMULAS

PQBOOST calculates the sum of squares of the masses of all battleships of all
races. Battleships are ships with more than BaysRequired fighter bays or torpedo
tubes and/or more than BeamsRequired beamweapons. The PALPlayerRate is then
computed by the following formula:

PALPlayerRate[i]=round(100*(1-mass[i]^RelativePower/sumofmass))

where mass[i] is the sum of battleship masses for race i and sumofmass is the
sum of all mass[i]^RelativePower. For explanation of RelativePower see section 5
above.

If AllianceGameMode is 1, PQBOOST will "punish" alliances:

PALPlayerRate[i]=round(100*(1-(mass[i]^RelativePower+k[j]*mass[j]^RelativePower+...)/sumofmass))

k[j]=min(1,sumof(K))

+a K=0 (alliance accepted)
+c or ~c K=CombatFactor/C (combat level enabled)
+m or ~m K=MinefieldFactor/C (minefield level enabled)
+p or ~p K=PlanetFactor/C (planet level enabled)
+s or ~s K=ShipFactor/C (ship level enabled)
+v or ~v K=VisionFactor/C (vision level enabled)

C=sumof(AllianceFactors)/1.5 if sumof(AllianceFactors) > 1.5
C=1.0 if sumof(AllianceFactors) <= 1.5

sumof(AllianceFactors):=CombatFactor+MinefieldFactor+PlanetFactor+ShipFactor+VisionFactor

8. SECURITY ISSUES

A player can, if he knows the PQBOOST parameters, compute the battlemasses of all
other players from his own battlemass and the current PALPlayerRate given in the
PCONFIG.SRC file. Especially in games without scores this is not desired.
To prevent this, you should enable the EnableSecurity parameter in the PQBOOST.CFG
file by setting it to 1. By doing this, the player will receive an unmodified
PCONFIG.SRC file and will not be able to deduce the strength of other players.

9. KNOWN PROBLEMS

Other possible add-ons which modifiy the PALPlayerRate setting cannot run
together with PQBOOST. There is, however, no problem using other add-ons modifying
the file PCONFIG.SRC.

10. THE POOH EXCEPTION

The Pooh Exception (courtesy Joshua Io) is a way to run PQBOOST only in AUXHOST1.
Simply add a line to AUXHOST1.INI which calls PQBOOST, that's all.
However, running PQBOOST in AUXHOST1 is not recommended for the following reasons:
- the outcome of battles etc. will no longer influence the PALPlayerRate
- players can see the PALPlayerRate regardless of the EnableSecurity setting
Therefore, don't use the Pooh Exception!

10. REVISION HISTORY

Version 2.0.4
- Fixed a bug: The FedCrewBonus (FCB) was not properly considered.

Version 2.0.3
- EnableESBandFCB implemented. Suggested by Daniel Bruedigam.

Version 2.0.2
- Added replacement snprintf() function.

Version 2.0.0
- Switched to automake/autoconf.

Version 1.15
- Fixed a bug reported by Piotr Winiarczyk. PQBoost spoiled pconfig.src if
sumofmasses was zero.

Version 1.14
- ranking list implemented

Version 1.12
- AllianceGameMode implemented

Version 1.6
- first release version

11. PQBOOST PHASES

As mentioned above, PQBOOST should be run in three phases, two of them just
before ship building, the third before PCONFIG.SRC is sent to the players.
PQBOOST performs the following operations in each phase:

Phase 1 just before ShipBuilding_1: PQBOOST makes a backup of the original
PCONFIG.SRC file to PCONFIG.OLD, remembers the original PALPlayerRate setting
in the file PQBOOST.TMP, and modifies PCONFIG.SRC according to the current
player strength.

Phase 2 just before ShipBuilding_2: PQBOOST modifies the PCONFIG.SRC again
according to the current player strength.

Phase 3 in AUXHOST2: If EnableSecurity is not 0, PQBOOST modifies PCONFIG.SRC
so that the original line containing the PALPLayerRate appears again.
Therefore PHOST will send the unmodified file to the players. The file
PQBOOST.TMP is deleted.

In each phase a temporary file called PCONFIG.QBO is created and erased again.

12. ACKNOWLEDGEMENTS

From the original QBOOST docs:
Many thanks to Joshua Io for the idea to this add-on and for suggestions,
to Andrew Sterian for important comments and hints, to Joshua Io and his
players for testing the program in a real game, and Oliver Korn for
suggestions.

I, Heiko Schlenker, would like to thank Stefan Glausauer for giving me the
source code of QBOOST and for his patient support, Matthias Degenhardt for
testing and his valuable suggestions and Mathew Rathgeb for testing PQBOOST
in a real game.

13. DISCLAIMER

pqboost -- An add-on to boost the PHOST3 build queue (PDK version of QBOOST)

Author: Stefan Glasauer <S.Glasauer@lrz.uni-muenchen.de>
PDK version by Heiko Schlenker <hschlen@gmx.de>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

PQBOOST was written in ANSI-C.

The original QBOOST was written in Borland-Pascal.

PQBOOST is linked with PDK software library.

VGA Planets is a trademark of Tim Wisseman.

PHOST and PDK is copyrighted by Andrew Sterian, Thomas Voigt,
Steffen Pietsch and Stefan Reuther.

If you find any bugs or if you want to make any suggestions,
please contact me. Please report ANY problems.

Stefan Glasauer
E-Mail s.glasauer@lrz.uni-muenchen.de

Maintainer of the PDK version: Heiko Schlenker <hschlen@gmx.de>

Last Modified: 1-Jun-2002
<URL:http://phost.de/~vagabond/addons/pqboost/pqboost.html>
<URL:mailto:the_vagabund@gmx.de>