![[PHost Logo]](logo.gif) © |
Developer Information
The Portable Host
Version 3.2.3.5g
|
INDEX
Introduction
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:
-
PHOST writes all game data to disk and closes the files (so that the files
may be modified). The files involved are:
-
PDATA.HST
-
SHIP.HST
-
BDATA.HST
-
MINES.HST
-
AUXDATA.HST
-
GEN.HST
-
SHIPXY.HST
-
XYPLAN.HST
-
The global data files (e.g., HULLSPEC.DAT, BEAMSPEC.DAT,
etc.) are closed. Add-on programs may change these files in the middle
of hosting, although the effects of doing so are unpredictable at best.
-
The player message files MESS.TMP and MESSPNT.TMP are
updated and closed. Player messages may be written by add-on programs.
-
The HOST.LOG file is closed. Add-on programs may append text data
to this file.
-
The PCONFIG.SRC file is closed. Add-on programs may change the
configuration, although the effects of doing so in the middle of hosting
may lead to surprises.
-
The HULLFUNC.TXT file is closed. Add-on programs may change the
set of special hull functions, although the effects of doing so in the
middle of hosting may lead to surprises.
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:
-
Ships with more than 99% damage are removed from the game
-
Ship warp speeds are limited by damage
-
Ships towing or intercepting illegal ships (e.g., destroyed ships) have
their missions cleared
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:
-
The first line will contain the current turn number, a blank, and an 18-character
time stamp for the current turn. This information is provided so that add-on
programs do not inadvertently use stale information. On the first turn
of the game (i.e., immediately after mastering a new universe), the first
line of the XTERNCMD.EXT file will simply contain the single number
0 and no time stamp.
-
Subsequent lines are of the form:
P: ARGS
where P represents a player number (in the range 1 through 11)
and ARGS are whatever words followed the xtern
command in the command message.
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:
% MYADDON
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]](remote.gif)
)
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:
-
The first line contains the turn number as a decimal integer, a space,
and an 18-character time stamp for the current turn. The purpose of this
information is to allow add-on programs to check that the SHIPSCAN.EXT
file does indeed correspond to the current turn (the time stamp and turn
number should match the information in the NEXTTURN.HST file).
-
The first turn of the game is an exception to the above. For the first
turn of the game (i.e., immediately after mastering and before TRN
files are submitted) the first line of the SHIPSCAN.EXT file will
simply contain the digit 0 by itself.
-
Following the first line are 500 lines, each line corresponding to a ship
slot. Thus, the first line of 500 is for ship #1, and the last line in
the file is for ship #500.
-
For each ship, there are two decimal numbers on the line. The first number
is a bit mask indicating which players scanned the ship as an enemy ship.
The second number is a bit mask indicating the ship's owner and any allies
to whom the Ship Level of alliance
has been granted.
-
Each one of the two decimal numbers on a ship line is to be interpreted
as a bit mask. Bit 0 (the least significant bit) is ignored. Bit 1 corresponds
to player 1, bit 2 corresponds to player 2, and so on up to player 11.
Bits 12 through 15 are unused and are always 0.
-
If a bit is set in the first number on a ship line, it means that the corresponding
player has scanned the ship. If a bit is set in the second number on a
ship line, it means that the corresponding player either owns the ship
or is an ally to whom the ship owner has granted the Ship
Level of alliance. The two numbers will not have any set bits in common.
-
A line that simply contains the numbers 0 and 0 indicates that there is
no ship in the game for that ship slot.
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
(support@phost.de).
Last updated 7 December, 2001