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

                   (c) 1998-2002 Stefan Glasauer
                   (PDK version by Heiko Schlenker)

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)

   Copyright (C) 1998-2002 Stefan Glasauer

   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://www.blutmagie.de/vagabond/addons/pqboost/pqboost.html>
<URL:mailto:the_vagabund@gmx.de>