[PHost Logo]©

Fine-Grain Hosting Control
The Portable Host
Version 3.2.3.5g

INDEX


Introduction

The HOST 3.2 program introduced three "hooks" into its operation in support of host-side add-on programs. These are the AUXHOST1.INI hook, which executes after turn processing but before host operations, the AUXHOST2.INI hook which runs after host operations but before generating RST files, and the AUXBC.INI hook which runs immediately before combat. PHOST 3.x expands these hooks to cover nearly all aspects of operation. That is, PHOST 3.x implements a hook between nearly every stage of its operation. Moreover, the host can configure PHOST to completely skip over any or (almost) all of its internal processing stages. This allows the replacement of a PHOST processing stage with an external add-on. For example, PHOST's web draining stage can be disabled and replaced with an external program that implements web draining in a different manner, while all other PHOST stages execute normally.

Fine-grain hosting control is obviously not for novice hosts. Most likely, there will be an add-on that is written to take specific advantage of this level of flexibility. This add-on will (hopefully) come with instructions regarding proper configuration.

==>  Note that it is not possible to change the order of execution of PHOST's stages.

Back to the index


The PCONTROL Configuration

Fine-grain hosting control is configured in the usual PCONFIG.SRC file but in a special section that begins with the following delimiter, on a line by itself:

% PCONTROL

Assignment statements that follow this line are considered to be hosting control commands, up to the end of the PCONFIG.SRC file or until the next special delimiter line (i.e., %-line) is encountered.

Normal Execution

Each assignment statement tells PHOST what to do with one of its 51 processing stages. The most common assignment is of the form:

Stage = Normal

where Stage is one of the processing stages listed below. The assigned value of Normal indicates that PHOST is to execute this stage normally.

Normal execution is what occurs when a stage has no assignment in the PCONTROL section (i.e., it is the default action, obviously). Thus, this assignment will normally never need to be used in practice except as a placeholder.

Skipping Execution

To skip a processing stage, the assignment statement should read:

Stage = Skip

PHOST will then simply not execute this one stage. ==> Note that some stages are always executed regardless of the PCONTROL configuration (see below).

Replacing a Stage

To skip a processing stage and execute an external INI-file in its place, the assignment statement should read:

Stage = Replace file.ini

PHOST will then skip its own execution of the processing stage and instead execute the commands found in the file file.ini. This file name can, of course, be any valid file name. The file specified must be found in the game directory.

The INI-file specified is interpreted in the same fashion as AUXHOST.INI files. That is, it is a text file containing commands to be executed, one per line. PHOST provides one enhancement in these files: the use of sections. In the same way that %-lines in the PCONFIG.SRC file delimits the file into various sections, a line beginning with % in the INI-file indicates a separate section. The name of the section follows the % character.

To execute a single section from a multi-section INI-file, follow the INI-file name with the % character and the section name, like this:

Stage = Replace file.ini%Section1

In the above example, the file file.ini will be processed but only the commands in section Section1 will be executed.

Execution Before or After a Stage

The final form of assignment tells PHOST to execute an INI-file first and then execute the processing stage normally. The assignment should read:

Stage = Execute file.ini

Before = Execute file.ini

PHOST will then execute the contents of the file.ini file (in the game directory), then execute the processing stage normally. As with the Replace assignment, section names can be appended to the INI-file specification.

(v3.4g and later:) You can also execute something after a stage by specifying a line

Stage = After file.ini

PHost will then execute the stage first, followed by the .ini file.

You can specify multiple entries for a stage if you wish.

Abbreviations

Note that all the special assignments may be abbreviated to as few letters as desired (up to the first, single letter). For example:

Stage = E file.ini

There must be at least one space, however, between the action and any filename that follows (if present).

Executing a Single Command

(v3.4g and later) If you have just one command to execute, you can specify that directly in pconfig.src. To tell PHost that you specified a command and not a file name, prefix the command with an asterisk. For example:

Movement = E *echo Start moving!

There still must be at least one space between the action and the command.

Placeholders in Commands

(v3.4m and later) Commands can contain placeholders.

This way, you can write command files that work independant of the game they are used in. For example, Stage = E *pqboost %d will execute pqboost, passing it the right game directory automatically.

Note that, in .ini files, these placeholders cannot be first in a line to avoid that they are confused with section delimiters.

Add-Ons

(v3.4m and later) Many add-ons are used again and again with the same set of PControl settings. To simplify setup, you can write these PControl settings in a separate file, and refer to that file from the PControl section.

   Addon = filename

PHost will look for that file in both the game and the root directory, so you can use the same file for many games. PHost will look for a %pcontrol section delimiter and read just that section. Therefore, if the add-on understands these section delimiters, you can directly place the instructions in the add-on configuration file.

Example: Here is an example to use with the Stargate add-on:

   % pcontrol
   TowResolution = Execute *stargate 1 %d %r
   SensorSweep   = Execute *stargate 2 %d %r

You would refer to that file by using Addon = stargate.txt (unfortunately, Stargate doesn't support % section delimiters).

Between Phases (Auxhost)

(v3.4m and later) Instead of making auxhost1.ini and auxhost2.ini files, you can specify the commands directly in pconfig.src.

   Auxhost1 = Command
   Auxhost2 = Command

The command is just a reference to another ini file or a shell command, as in Auxhost1 = *mfq %d. There is no point in specifying Before, Skip, etc.

Back to the index


Processing Stage Names

This section lists the PHOST processing stages that come under fine-grain control. Each one of these names is valid as the left-hand-side of an assignment in the PCONTROL configuration section of the PCONFIG.SRC file (see above). Note that the names are not case sensitive, but they cannot be abbreviated.

==> Note that some of these stages cannot be skipped. A Skip or Replace command for these sections is treated as Normal or Exec, respectively. Note, too, that the stages are listed in order of execution. However, the assignment statements in the PCONTROL configuration section can come in any order, they need not appear in the same order as the order of execution.

Stage Name Description
LargeMeteors Checks for large meteors impacting
MeteorShowers Checks for meteor showers on planets
TransferOwner Planets and ships given away, gsN friendly code
AntiCloak_1 Loki anti-cloak ships
DeluxeSuperSpy Birdman Deluxe Super Spy missions
NewNativesAppear New natives may appear on planets
RobMission Privateer Rob mission
GamblingShips Aries gambling ships produce credits
CargoDump Ships dump cargo, ground attack, Imperial Assault
CANNOT BE SKIPPED
CargoTransfer Ships transfer cargo to each other
CANNOT BE SKIPPED
TrimShipCargo Ships with excess cargo lose cargo
CANNOT BE SKIPPED
BeamTransfers btm, btf, btt friendly code actions and related extended missions
GatherMission All ship gather missions (including extended missions)
BeamUpCredits bum planetary action and related extended mission
MinefieldDecay Minefields shrink due to decay
MineLaying Ships lay mines and minefields explode
MinesDestroyMines Minefields which still overlap explode
MineSweeping Ships sweep and scoop minefields
MinefieldScan Ships scan for enemy minefields
WormholeScan Ships scan for wormholes (WRS action)
WebDraining Web minefields drain fuel
SpecialMissions_1 Super Refit, Hiss, Cyborg self-repair mission
BuildFighters Ships build fighters mission (and lfm action)
BuildTorpedoes Ships build torpedoes
Alchemy Alchemy ships produce minerals or fuel
ShipBuildOrders Gathering ship build orders and filling the build queue. Up to PHost 3.3e, this stage was part of ShipBuilding_1.
ShipBuilding_1 Ship building and cloning
DumpOldBaseParts dmp planetary friendly code action
BaseMissions_1 Fix, Recycle, Load Torps, Max Defense, Force Surrender
SupplyRepair_1 Ships repair themselves with supplies
BoardingParties Privateer/Crystal boarding parties (tow capture)
FreeFighters Starbases build free fighters
TowResolution Tow resolution: determines what tows shall succeed and clears those which shall not. Up to PHost 3.3e, this stage was part of Movement.
Movement Movement, intercept resolution, intercepts, wormhole travel, gravity wells
CANNOT BE SKIPPED
GloryDevices Klingon glory devices explode
Chunneling Chunneling ships travel
AntiCloak_2 Loki anti-cloak ships (again)
ColonizeMission Ship colonization missions
SupplyRepair_2 Ships repair themselves with supplies (again)
BaseMissions_2 Refuel, Unload Freighters, Repair Base
Combat Ship-to-ship and ship-to-planet combat
SupplyRepair_3 Ships repair themselves with supplies (again)
Terraforming Terraforming ships heat/cool planets
SensorSweep Ship sensor sweep mission
SpecialMissions_2 Pillage, Rebel Ground Attack, Dark Sense
PlanetaryProduction Mining, supply production, TUDR
PlanetaryHappiness Colonists and natives change in happiness
PlanetaryTaxation Colonists and natives generate revenue
PlanetaryGrowth Colonists and natives grow in numbers
PlanetaryLosses Climate deaths, overpopulation supply loss, structure decay, riots, civil war, Amorphous losses
ShipBuilding_2 Ship building and cloning (again)
Assimilation Cyborg colonists assimilate natives
SuperSpyMission Birdman Super Spy missions
ShipExploration Ship Exploration missions

Back to the index


Interaction with Other Hooks

The three existing hooks (AUXHOST1.INI, AUXHOST2.INI, and AUXBC.INI) are still supported as usual. The AUXHOST1.INI file, if present in the game directory, is run prior to the first stage (LargeMeteors) and prior to any hook that may be installed for this stage. The AUXHOST2.INI file, if present in the game directory, is run after the last stage (ShipExploration). Finally, the AUXBC.INI file, if present in the game directory, is run prior to the Combat stage and prior to any hook that may be installed to run before this stage.

Back to the index


Examples

Here are some examples of using fine-grain hosting control.

Example #1

This PCONTROL section instructs PHOST to skip the usual web minefield draining stage and execute an external INI-file named webdrain.ini instead:

    % PCONTROL

    WebDraining = Replace webdrain.ini

Example #2

This PCONTROL section instructs PHOST to skip the second ship building phase, replace the assimilation phase with the external INI-file named newassim.ini, and run the TForm section in the INI-file named others.ini immediately before terraforming:

    % PCONTROL

    ShipBuilding_2 = Skip
    Assimilation   = Replace newassim.ini
    Terraforming   = Exec others.ini%TForm

Back to the index


This document is maintained by The Portable Host Project[Remote] (support@phost.de).

Last updated 8 July, 2006