[PHost Logo]© 

Developer Information
The Portable Host



This document pulls together relevant information for developers interested in writing addon programs for PHOST. Most of the information is contained within other pages, and this page is simply a summary.

Back to the index 

AUXHOST Programs

PHOST supports the same AUXHOST1.INI, AUXHOST2.INI, and AUXBC.INI hooks as HOST. The one main difference is that PHOST allows AUXHOST programs the full amount of low memory available in which to run. HOST remains resident in memory and uses up about 320K of low memory.

Back to the index 

What Happens When AUXHOST Programs Run

The developer writing an add-on program for AUXHOST operation may wonder what aspects of the game data can be modified and, in general, exactly what happens when PHOST shuts down to run an AUXHOST program (this includes programs that run from the fine-grain hosting control interface). This section attempts to describe this operation in detail. The following steps are performed in order: After the add-on program has finished, PHOST basically performs the above steps in reverse, opening up all of the stated files. In addition, PHOST performs ship adjustments so that add-on effects are properly incorporated: Back to the index 

Auxiliary Data Files

One of the main interfaces for addon developers is the auxiliary data interface to player-side utilities. In addition to the usual RST files, PHOST generates an auxiliary data file for each player known as a UTIL*.DAT file. This information is mostly the same as what is contained in the player messages, but in binary format. This makes message scanning obsolete (important for non-English player messages). Addon developers can also include information in these auxiliary files for use by player-side utilities. For more information please see the "Auxiliary Data Files" page.

Back to the index 

Fine-Grain Hosting Control

It is assumed that developers are familiar with the AUXHOST1.INI, AUXHOST2.INI, and AUXBC.INI hooks supported by HOST. PHOST supports these hooks as well, but allows for even finer-grain hooks into its operation. External programs can be inserted between any two stages of PHOST operation, and most PHOST stages can be skipped if necessary, allowing replacement by external programs. For more information please see the "Fine-Grain Hosting Control" page.

Back to the index 

Handling Player Command Messages

The PHOST command processor can be used by addon programs as well, without having to scan incoming messages. The xtern command processor command can be used as an "escape mechanism" by addons. Any xtern command given by the player is automatically written to a file named XTERNCMD.EXT in the game directory. This file will be available at the AUXHOST1 stage.

The XTERNCMD.EXT file is a plain text file. The format of this file is as follows:

PHOST handles command concatenation internally, hence there are no limits on line length. Otherwise, commands are copied verbatim. (In versions before 3.4b, the limit was 40 characters per command, and PHOST would have compressed multiple blanks into one.)

It is recommended that add-ons recognize commands of the form name: command (i.e., the xterncmd.ext line would read 3: name: command). This way, it is clear whom a command was addressed to which is useful for error detection. Since version 3.4b, PHOST allows to omit the xtern from the command message when this convention is used. For backwards compatibility, your add-on should still accept the form without name. Recent versions of the PDK contain a function CommandFileReader which does all that for you. Back to the index 

Additional Special Friendly Codes

Add-on or external programs sometimes introduce new special friendly codes to implement new behavior. PHOST's handling of special friendly codes with respect to matching (i.e., special friendly codes never match) is a simple and consistent rule for players to follow, but it does not take into account any friendly codes introduced by add-on programs. PHOST implements a mechanism, however, that allows it to recognize an add-on's new friendly codes as being special for the purposes of matching.

To implement this mechanism, PHOST makes use of a file in the game or root directory named XTRFCODE.TXT, if it exists. This file should contain a list of friendly codes that PHOST is to consider special and will therefore never allow to match (not for combat, not for gathering minerals at planets, etc.) The format of this file is free-form, it may contain tokens of up to 3 characters each (representing friendly codes) interspersed with any amounts of white space. Each friendly code is case-sensitive. If the friendly code contains N characters, where N is less than 3, then a ship or planet's friendly code is considered special if it matches just the first N characters.

See the Additional Special Friendly Codes section on the "Hosting with PHOST" page for some examples.

Back to the index 

Interfacing to PVCR

If you are interested in using PVCR as a back-end battle viewer or simulator, take note of the PVCR data file specifications described in the "The PVCR Program" page. PVCR is flexible enough to be included in many kinds of applications requiring the display of PHOST combat.

Back to the index 

PCONFIG.SRC File Sections

If you are writing an addon that uses PHOST-style configuration assignments, consider looking for the configuration information in the PCONFIG.SRC file. PHOST can split this file up into logical section using %-lines. For example:
tells PHOST that the assignment lines following this %-line are only relevant to a program looking for the section MYADDON. The section name PHOST is reserved for PHOST itself, as is the section name PCONTROL, which is used for assignment statements related to fine-grain hosting control.

Back to the index 

File Format Changes

PHOST 3 has a common file format across all platforms for all data files. For the DOS version of PHOST, this is not a change, but for all other platforms it means that the file formats are now different. Specifically, all data files are now stored exactly the same, byte-for-byte, as the DOS data file format.

The one exception to this rule is standard text files. Text files (such as PCONFIG.SRC, WORMHOLE.TXT, etc.) use the native text format of the underlying operating system. This means, for example, that Unix-ish host platforms will have text files that end in linefeed (LF) characters while DOS-ish platforms will have text files that end in carriage-return/linefeed (CR-LF) characters.

Back to the index 

Adding Extra Battles

If you are writing an add-on that performs combat (perhaps using the Combat() API in the PDK[Remote]) and you wish the battles to be viewed as normal battles on the player side, then you need to write the battles to the VCR.HST file in the game directory. This file consists of a 2-byte count of the number of battles, followed by this many battle records. It is assumed that you are familiar with the format of each record. If not, please browse through the Battle Specifications section of the "The PVCR Program" page.

When it comes time to write RST files, PHOST will read through the VCR.HST file and copy each battle into the appropriate RST file. If you have added battles to the VCR.HST file, then they too will become part of the RST files.

==> Your add-on needs to take care to not corrupt the VCR.HST file and to always keep the count of the number of battles (i.e., the first 2 bytes of the file) synchronized with the number of battle records that follow.

Note that this mechanism for adding battles to the VCR.HST file was not supported before PHOST 3 since the VCR.HST file was kept open at all times for writing, making it inaccessible to other programs. In PHOST 3, the VCR.HST file is opened for writing during combat, then it is closed. It is opened again (for reading only) during RST generation. At all other times, other programs may add (or otherwise modify) the VCR.HST file.

During PHOST's initialization phase (i.e., before reading TRN files), PHOST will overwrite any existing VCR.HST file in the game directory and create a new VCR.HST file containing nothing but two 0 bytes (indicating an empty VCR.HST file with 0 battles).

Back to the index 

Ship Scan Information

PHOST 3 writes a file named SHIPSCAN.EXT to the game directory during Phase 3 of operation. This file is generated by PHOST but is not otherwise used by PHOST. It is meant to benefit add-on programs by indicating which ships were scanned by whom during the current turn.This is a plain-text file with the following format: For example, suppose that player #1 owns ship #500. Player #2 is an ally of player #1 and player #1 has granted player #2 the Ship Level of alliance. Player #3 is not allied with either player but he has scanned the ship this turn. Then, the last line of the file (i.e., ship #500) will read:
8 6

Back to the index 

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

Last updated 7 December, 2001