©	Fine-Grain Hosting Control The Portable Host Version 3.2.3.5g Jump to Table of Contents

INDEX

• Introduction
• The PCONTROL Configuration
• Processing Stage Names
• Interaction with Other Hooks
• Examples

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:

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:

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:

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:

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:

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:

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

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:

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:

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.

• %d is replaced by the game directory name (first directory parameter given in PHost invocation).
• %r is replaced by the root directory name (second directory parameter given in PHost invocation).
• %d is replaced by the current random seed (3.5e and later).

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.

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 (support@phost.de).