©	Custom Hull Functions The Portable Host Version 3.2.3.5g Jump to Table of Contents

INDEX

• Introduction
• Hosting with Custom Hull Functions
• Playing with Custom Hull Functions
• The HULLFUNC.TXT File
• Displaying a Modified Ship List
• Examples
• The SHIPLIST.TXT File
• The HULLFUNC.DAT File
• List of Special Functions
• List of Hulls

Introduction

It is commonly known that certain ships are capable of certain special functions. For example, the Meteor Class Blockade Runner is capable of both cloaking and gravitonic movement. Prior to PHOST 3, however, both HOST and PHOST had no flexibility in deciding which ships could perform which functions. If, for example, a ship list designer wanted to add cloaking to a usually non-cloaking ship, there was no way to do so. Thus, ship list designers were limited to the special functions found in the original ship list. In other situations, hosts would sometimes want to modify a ship list to effect various scenarios or host special-purpose games. Again, they were limited by the special functions built in to a fixed set of hulls.

In PHOST 3, a new feature is introduced that removes this association between special functions and fixed hull numbers. A new ship list file, HULLFUNC.TXT, is used to specify these associations directly, allowing for total flexibility in ship list design or game customization. This documentation file explains the format of the HULLFUNC.TXT file, how to host a game using customized hull functions, what you need for playing in a game with custom hull functions, and also provides some examples for writing or modifying a HULLFUNC.TXT file.

PHOST 3 implements two features to help hosts and players keep track of special hull functions. A new PHOST command line option displays a full ship list in textual format, including all custom hull assignments. This same command line option causes PHOST to write a HULLFUNC.DAT file which contains a binary-coded version of the HULLFUNC.TXT file, suitable for interpretation by other programs.

Since PHost 3.4b, you can collect all ship-list specific parameters in SHIPLIST.TXT.

Return to index

Hosting with Custom Hull Functions

Custom hull functions are specified using a HULLFUNC.TXT file. If you received this file together with a ship list, simply keep this file together with the other ship list files (HULLSPEC.DAT, ENGSPEC.DAT, BEAMSPEC.DAT, TORPSPEC.DAT, TRUEHULL.DAT). As is done for the other ship list files, PHOST will look for HULLFUNC.TXT in the game directory first, followed by the root directory if it is not found. When PHOST executes it will display a message indicating whether a HULLFUNC.TXT file was found or whether PHOST is using the built-in default hull functions. If no HULLFUNC.TXT file can be found, the customary hull functions (as in the original ship list) will be in effect.

Hosts should remember to send a copy of the HULLFUNC.TXT file (along with the other ship list files, of course) to the players for reference purposes. Hosts may also wish to generate a HULLFUNC.DAT file and send it to the players.

Return to index

Playing with Custom Hull Functions

If you are playing in a game that uses custom hull functions, make sure your host sends you a copy of the HULLFUNC.TXT file in effect for the game. Make sure you familiarize yourself with how your ships are different, with respect to special hull functions. With most client programs (such as DOS Planets) you will find that the client program will not let you select a Cloak mission unless the ship is one that the client program recognizes as being cloak-capable. That is, the client program is most likely not aware of the custom hull functions being used. There are several alternatives available. The VPA 3.51 program is an alternative DOS-based client program that is more flexible in letting you set missions. Also, make sure you familiarize yourself with PHOST's extended missions so that you can use the Cloak extended mission on any cloak-capable ship.

If you use any utilities that make use of the HULLFUNC.DAT file (which is just a binary-encoded version of the HULLFUNC.TXT file) then make sure your host also sends you this file.

Return to index

The HULLFUNC.TXT File

The HULLFUNC.TXT file is the mechanism by which the host or ship list designer communicates to PHOST how special hull functions are assigned to hulls, and which players may use them. The HULLFUNC.TXT file is a regular text file. PHOST first looks for this file in the game directory, and if not found, in the root directory. If the file is still not found, PHOST uses the default original special function assignments and enables them to all players. Please see the "Examples" section for some examples of the HULLFUNC.TXT file syntax.

Basic Syntax

The HULLFUNC.TXT file consists of assignment statements, similar to the PCONFIG.SRC file. As in this latter file, lines in which the first non-blank character is '#' are considered comments and are ignored. Similarly, blank lines are ignored. The remainder of the file must consist of assignment statements of the form:

The assignable items and their allowable values are described below. Note that each line in the file is limited to a length of 255 characters. Unlike the PCONFIG.SRC file, the HULLFUNC.TXT file is interpreted sequentially.  Thus the assignment statements are actually action statements, and their order is important. See the "Examples" section for an illustration of this concept.

The Empty File

An empty HULLFUNC.TXT file is the same as a file with only a single statement:

See the Initialize statement description below for an explanation. An empty HULLFUNC.TXT file means that there will be no special functions associated with any hulls (there will be no cloaking ships, no gravitonic ships, no chunneling ships, etc.) Do not leave the HULLFUNC.TXT file empty unless this is your intention.

The Initialize Assignment

A line of the form:

will remove all special functions from all hulls. A line of the form:

will set all special functions to be associated with the customary hulls (as in the original ship list). This will also enable all special functions to all players.

Note that both of these Initialize statements completely erase any actions prior to the statement. Thus, anything above either of these statements in the HULLFUNC.TXT file can be ignored. The Default initialization is useful if the HULLFUNC.TXT file is to be used for making minor modifications to the usual special function assignments.

The word Initialize may be shortened to any abbreviation of the word, up to the single letter 'I'. Similarly, the words Clear and Default may be abbreviated up to a single letter.

The Hull Assignment

A line of the form:

indicates that all subsequent assignments will apply to hull #57, up to the next Hull assignment. Any amount of comment text may follow the hull number; this text will be ignored. For example:

is legal.

Rather than specifying a hull by number, a part of the hull's name can be used. For example:

or simply:

There is no distinction between uppercase and lowercase letters. Care must be taken, however, to spell the name correctly and to not use too few letters so that the name is ambiguous. For example, using a hull name of Super will select the Super Transport Freighter even though it may have been the intention to select the Super Star Destroyer.

Note, also, that the name of the hull will be compared against the names stored in the HULLSPEC.DAT  file. Thus, using a hull name is ship-list dependent, while using a hull number is not.

The Hull assignment statement does nothing except set the hull number for subsequent assignments. The associations between special functions and hulls are not changed after such an assignment.

Finally, the word Hull may be abbreviated to any number of letters, including the single letter 'H'. Please see the "List of Hulls" section below for a list of hull numbers and hull names in both the original ship list and PLIST.

The Function Assignment

A line of the form:

indicates that all subsequent assignments will apply to special function #16, up to the next Function assignment.

Any amount of comment text may follow the function number; this text will be ignored. For example:

is legal.

Rather than specifying a special function by number, a part of the function's name can be used. For example:

or simply

There is no distinction between uppercase and lowercase letters. Care must be taken, however, to spell the name correctly and to not use too few letters so that the name is ambiguous. For example, using a special function name of Heats will select the HeatsTo50 special function even though it may have been the intention to select the HeatsTo100 function.

The Function assignment statement does nothing except set the special function number for subsequent assignments. The associations between special functions and hulls are not changed after such an assignment.

Finally, the word Function may be abbreviated to any number of letters, including the single letter 'F'. Please see the "List of Special Functions" section below for a list of special function numbers and names.

The RacesAllowed Assignment

An assignment of the form:

indicates that the current hull and special function should be associated and available to races 1 through 5.

Unlike the Hull and Function assignments, the RacesAllowed assignment is an action statement. That is, it makes a connection between a hull and a special function. You can think of it this way, Hull and Function assignments are like typing numbers in edit fields of a dialog box, a RacesAllowed assignment is like pressing the 'OK' button of the dialog box. The Hull and Function assignments set up the parameters, the RacesAllowed assignment makes the actual connection.

The right-hand-side of this assignment consists of a list of race numbers that may either allow or disallow a race from having access to the current special function on the current hull. Acceptable values for each race number term are:

This list of race number terms is interpreted sequentially from left to right. Some examples:

Note that the RacesAllowed assignment uses the PlayerRace config option to determine which players are given access to a special function on a hull. For example, with the following config setting:

then the assignment:

                Hull = Merlin 
                Function = Cloak
                RacesAllowed = +1 

will allow a Merlin to cloak if it is owned by players 1 through 5, since these players are all playing race #1.

Note that a RacesAllowed assignment discards any previous association between the current hull and current special function. For example:

                Hull = Meteor 
                Function = Cloak 
                RacesAllowed = + 
                RacesAllowed = +5 

The first RacesAllowed assignment enables the Meteor Class Blockade Runner to cloak, no matter who owns it. But this statement is completely irrelevant, because the next RacesAllowed assignment enables cloaking only to race #5. All other races may not cloak the MBR.

Finally, the word RacesAllowed may be abbreviated to any number of letters, including the single letter 'R'.

The PlayersAllowed Assignment

An assignment of the form:

indicates that the current hull and special function should be associated and available to players 1 through 5.

Like the RacesAllowed assignment, this assignment is an action statement, making a new association between a special function and a hull. The PlayersAllowed assignment is identical to the RacesAllowed assignment in all ways except that the PlayerRace config option is not consulted. That is, this assignment specifies player numbers, not race numbers. For example, with the same PlayerRace config setting as above:

then the assignment:

                Hull = Merlin 
                Function = Cloak 
                PlayersAllowed = +1

will allow a Merlin to cloak if it is owned by player 1 only, even though other players are also playing race #1.

Finally, the word PlayersAllowed may be abbreviated to any number of letters, including the single letter 'P'.

Return to index

Displaying a Modified Ship List

The -l PHOST command line option ( that's a lowercase L, not the number 1) introduced in PHOST 3 displays the ship list in use for a game, as seen by PHOST. With this option, PHOST will display the ship list (to stdout), write a HULLFUNC.DAT file in the game directory (see below), and then exit. This option is useful for displaying a complete ship list (for sending to players, perhaps) and for debugging/verifying your work if you are modifying a HULLFUNC.TXT file.

For example:

will look for ship list files first in the game1 directory, then in the plist.dat directory, and then display the full ship list to the screen.

Here is a snippet from the possible output of the above command (this might not look right if your browser window is not wide enough to display all of the hyphens below on a single line):

Player Slot #1 ---------------------------------------------------------------------
DAEDALUS CLASS SCOUT          1B/ 0T 20ms 180ca 260fu 58cr 1en 1tl 
                                     100$ 20T 7D 3M 
APOLLO CLASS ESCORT           3B/ 2T 60ms 60ca 160fu 112cr 1en 2tl 
                                     200$ 35T 15D 10M 
OBERTH CLASS SURVEY SHIP      2B/ 0T 90ms 120ca 320fu 111cr 1en 3tl 
                                     260$ 15T 15D 15M 
    HeatsTo50 
    ScansAllWormholes 
NIAGARA CLASS DESTROYER       2B/ 4T 120ms 40ca 120fu 99cr 2en 4tl 
                                     400$ 30T 70D 100M 
MIRANDA CLASS RESEARCH VESSEL 3B/ 0T 90ms 120ca 180fu 88cr 1en 5tl 
                                     270$ 15T 15D 15M
    CoolsTo50 
CONSTITUTION CLASS FRIGATE    6B/ 3T 180ms 150ca 260fu 334cr 2en 6tl
                                     500$ 100T 125D 25M 
    AntiCloak
-------------------------------------------------------------------------------

Return to index

Examples

Here are some examples that may serve to illustrate the use of the HULLFUNC.TXT file.

Example #1

This HULLFUNC.TXT file uses the default special function associations but it restricts chunneling to Borg races only.

                Init = Default

                Hull = Firecloud
                Function = Chunneling
                RacesAllowed = - +6

Example #2

This HULLFUNC.TXT file uses the default special function associations but it prevents Privateer players from using the three hyperwarp ships.

                Init = Default
                
                Hull = 77 (PL21) 
                Function = Hyperdrive 
                RacesAllowed = + -5

                Hull = 87 (Falcon) 
                Function = Hyperdrive 
                RacesAllowed = + -5 

                # Note use of abbreviations 
                H = 51 (B200) 
                F = Hyper 
                R = + -5

Example #3

This HULLFUNC.TXT file adds cloaking capability to the PLIST K'T'INGA Class Battlecruiser, but only for player #3. Even if other players are playing the Birdman race, only player #3 is able to cloak this ship. Also, the Death Star Class Carrier is given Gravitonic engines, available to all players, and cloaking capability, but only for Empire races.

                Init = Default 

                # Specifying hull by name instead of number 
                Hull = K'T'INGA   
                # Specifying function by number instead of name 
                Function = 16     (16 is the number for the Cloak special function) 
                PlayersAllowed = - +3 

                # Give gravitonics to the Death Star (all players enabled) 
                Hull = Death Star
                Function = Grav
                PlayersAllowed = +

                # Reuse Death Star hull, no need for another 'Hull' assignment
                Function = Cloak
                RacesAllowed = 8

Return to index

The SHIPLIST.TXT File

To simplify play with non-standard ship lists, PHost 3.4b supports an alternate file for specifying hull functions.

The file is called SHIPLIST.TXT and has a similar format as HULLFUNC.TXT and PCONFIG.SRC. It can contain hull function definitions after a % HULLFUNC section delimiter. In addition, it can contain configuration options after a % PHOST section delimiter.

When SHIPLIST.TXT exists, HULLFUNC.TXT is not read, so SHIPLIST.TXT must contain the complete hull function definitions.

The % PHOST section should contain only ship-list specific parameters, mainly the combat-related ones (AllowAlternativeCombat, etc.), and those that were assumed for creation of the ship list (AllowAlternativeTowing, AlternativeAntiCloak, ...). It is an error when a parameter appears in both SHIPLIST.TXT and PCONFIG.SRC.

Return to index

The HULLFUNC.DAT File

PHOST reads the HULLFUNC.TXT file to determine the custom hull function assignments. On the player side of things, some utilities may want to do the same thing to present a clearer picture of the ship list to the player. Since reading and parsing text files is cumbersome, PHOST alleviates some of the work of these player-side utilities by writing a binary-encoded version of the HULLFUNC.TXT file to a file named HULLFUNC.DAT.

 PHOST reads the HULLFUNC.TXT file and writes to the HULLFUNC.DAT file. PHOST will never write to the HULLFUNC.TXT file, nor will it read from or otherwise make use of the HULLFUNC.DAT file. The HULLFUNC.DAT file is strictly for use by other programs. It contains the same information as HULLFUNC.TXT but is in binary format.

To generate a HULLFUNC.DAT file, simply use the -l command-line option ( that's a lowercase L, not the number 1) as described above in the "Displaying a Modified Ship List" section. PHOST will write a HULLFUNC.DAT file in the game directory. The host may then send this file to players. For example, to only generate a HULLFUNC.DAT file and not print out a ship list,

phost -l gamedir > nul       (DOS)
phost -l gamedir > /dev/null (Unix)

File Format

This section describes the binary file format of the HULLFUNC.DAT file. This information is only of interest to authors of programs that plan to make use of this file. This file will be written in standard DOS format, meaning that all quantities are stored little-endian (LSB first), word-sized quantities are 16 bits, and long-sized quantities are 32 bits.

The basic file structure is as follows:

                HULLFUNC.DAT file:
                        long     MagicNumber1;
                        word     PHOSTVersion;
                        char[32] GameName;
                        long     SynthSpecialPointer;  /* PHost 4 */
                        long     ShipDataPointer;      /* PHost 4 */
                        word[4]  Reserved;
                        word     NumberOfRecords;
                        record Hullfunc DataRecords[NumberOfRecords];

                        /* SynthSpecialPointer points here if section exists: */
                        word     NumberOfSynthRecords;
                        word     SizeOfSynthRecords;
                        record SynthSpecial SynthRecords[NumberOfSynthRecords];
                        /* ShipDataPointer points here if section exists: */
                        word     NumberOfShipRecords;
                        record Hullfunc ShipDataRecords[NumberOfShipRecords];
                        /* Possible additional data may follow here */

                        long     MagicNumber2;
                        long     Checksum;

The first field is a 32-bit magic number with the value 0xB1297F35. It simply identifies the file as being a HULLFUNC.DAT file. The second field, PHOSTVersion, identifies the version of PHOST that wrote this file. The MSB of this field is the major version and the LSB is the minor version. The next 32 bytes contain the name of the game, as set by the GameName config option in the PCONFIG.SRC file. If the game name is less than 32 characters, the remaining characters are padded with blanks. The next 16 bytes (8 words) are currently written as zeroes and are reserved for future use.

The game name information is written to the HULLFUNC.DAT file so that player-side utilities may ensure that the file corresponds correctly to the remainder of the ship list data in use for a specific game.

The NumberOfRecords field indicates the number of Hullfunc records that follow in the file (DataRecords). These records are described below. Following all data records comes the MagicNumber2 field, which always has the value 0x1F0C219A. This field is used to ensure that the program reading the HULLFUNC.DAT file has not become misaligned with the actual data. Finally, the Checksum field represents a 32-bit, word-oriented sum over the entire file prior to this field, beginning with the MagicNumber1 field and including the MagicNumber2 field. The word-oriented checksum adds every sequence of 2 bytes in the file as a 16-bit unsigned integer (stored in little-endian format, LSB first). Thus, the checksum over the first 4 bytes of the file (the MagicNumber1 field) will be 0x1305E (= 0x7F35 + 0xB129).

In PHost 3.x, the MagicNumber2 field directly follows the last DataRecord. PHost 4.x provides additional fields which have been sketched here, which follow between these fields. To take this into account, you would compute the position of the MagicNumber2 field from the actual file size as reported from your operating system.

There are NumberOfRecords actual Hullfunc data records in the file, following the NumberOfRecords field. Each Hullfunc record is of the following form:

                Hullfunc record:
                        word    HullNumber;
                        word    NumSpecialFunctions;
                        record Hullassign Assignments[NumSpecialFunctions];

The HullNumber field indicates the ship hull number (in the range 1 through 105) that this record describes. The NumSpecialFunctions field indicates the number of special hull functions that have been assigned to this hull. This field is followed by NumSpecialFunctions records of type Hullassign. The format of this record type is as follows:

                Hullassign record:
                        word    FunctionNumber;
                        word    PlayersAllowed;

The FunctionNumber field indicates the special function that has been assigned to the current hull. Function numbers are listed below. The PlayersAllowed field indicates which players (NOTE: players, not races) are allowed to use this special function on the current hull. There is one bit used in this field for each player allowed to use the special function. Bit 0 (the LSB) is not used. Bit 1 represents player 1, bit 2 represents player 2, etc. up to bit 11 for player 11. If a bit is set, it means the corresponding player is allowed to use the special function. Note that all bits may be set in this field but only bits 1 through 11 are used.

Return to index

List of Special Functions

This section provides a reference for special function names and numbers. These names and numbers are valid parameters for the Function assignment in the HULLFUNC.TXT file. The function numbers are also used in the contents of the HULLFUNC.DAT file.

Return to index

List of Hulls

This section provides a reference for hull names and numbers, both for the original ship list and for PLIST. These names and numbers are valid parameters for the Hull assignment in the HULLFUNC.TXT file. The hull numbers are also used in the contents of the HULLFUNC.DAT file. Other ship lists are supported, of course, but an exhaustive list of ship names for all ship lists would be inappropriate here. PHOST uses whatever names are present in the HULLSPEC.DAT file for recognizing ship names in the HULLFUNC.TXT file. That is, the ship names are not hard-coded into the PHOST program.

Return to index

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