THE PORTABLE HOST The PHOST Command Processor Version 3.2.2.12 PHOST implements a mechanism by which players can affect the actual operation of the program. A PHOST module known as the command processor interprets special messages from the players and modifies the game configuration without any host intervention. This mechanism allows for players to set up formal alliances, to change and view their race names, and other such functions. The host can configure which aspects of the command processor will be available to players. Command Messages ================ Players communicate with the command processor via command messages. These are simply messages composed within the Planets messaging facility that are sent back to the player. For example, for player 3 to send a command message he/she would compose a message to player 3. The command processor realizes that the sender and receiver of the message are the same player and interprets this message as a command message. This mechanism works even if the AllowPlayerMessages option is turned off. As a special case, if the first non-blank character of a command message is a left angle-bracket '<', then the message is not treated as a command message but is processed as an ordinary message. This feature exists for two reasons: 1) When a player sends a universal message, then the player himself becomes a recipient of the message. But this means that the sender and the receiver of the message are the same player and PHOST would interpret the message as a command message for the sending player. Since the first line of a universal message is always <<< Universal Message >>> then the leading '<' causes PHOST to treat a universal message as a normal message. 2) Players that use the message facility to send reminders to themselves can do so without triggering the command processor simply by beginning their message with a '<' character. A player may send any number of command messages in a single turn. Each command message may consist of more than one actual command. Each single command occupies a single line of the message. Multiple commands may be placed on multiple lines. Blank lines are ignored. Command Message Formats ======================= Every command message has the following format: command [parm] [parm] .... where 'command' is one of the valid commands listed below. The number of parameters accepted by each command varies. If too many or too few parameters are specified, the command processor will return an error message on the following turn and ignore the command. Similarly, if a command is not recognized, an error message will be returned to the player. Each complete command (command name and parameters) must fit on a single line. Commands may not be split over multiple lines. Parameters are separated by any amount of whitespace. There can only be a maximum of 15 words in a single command (including the command itself and any parameters). There are no special meta-characters such as \ or ". List of Commands ================ The valid commands currently recognized by PHOST are listed below. Each command lists the corresponding configuration option which enables player access to the command's functionality (for example, the 'allies' command does nothing unless the CPEnableAllies configuration option is ON). Each command has a minimum number of distinguishing characters which must be found for the command to be recognized. This saves typing and also creates more room on each message line for long commands. The minimum number of characters for each command is listed with the command descriptions. For example, the 'racename' command may be shortened to simply 'ra'. Also valid are 'rac', 'race', etc. but not 'racn'. That is, whatever characters are specified must match those of the command, even if more than the minimum number are present. Commands are case-insensitive. Commands may change the configuration of PHOST. Since the configuration of the program is saved across multiple files, certain commands will write to one or more of these files. In all cases, files are written in the game directory, never in the main Planets directory. For example, if a player changes his race name, the RACE.NM file in the game directory will be overwritten, or created if it does not exist. The files that can be affected by each command are listed in the descriptions below. Set Language Command -------------------- Command Name : 'language' (minimum characters: 'l') Command Syntax : language {English|German|French|Spanish|Italian|Dutch} Enabled By : CPEnableLanguage Files Written : PCONFIG.HST This command allows a player to specify the language in which he/she receives messages from PHOST. Currently, the only valid parameter values are 'English', 'German', 'French', 'Spanish', 'Italian', and 'Dutch'. EXAMPLE: lang english l ger Allow Many Targets Command -------------------------- Command Name : 'bigtargets' (minimum characters: 'b') Command Syntax : bigtargets {Yes | No} Enabled By : CPEnableBigTargets Files Written : PCONFIG.HST The AllowMoreThan50Targets configuration option allows each player to select whether or not he/she wishes to receive more than 50 scanned ship records (targets) in the .RST file generated by PHOST (see CONFIG.DOC). This command allows a player to modify this entry without host intervention. If the player uses third-party utilities that can handle .RST files with more than 50 targets, then the player can use this command to enable this option. WARNING: DO NOT ENABLE THIS OPTION IF YOU DO NOT USE A PROGRAM THAT CAN HANDLE IT!!! The standard UNPACK utility that comes with VGA Planets CANNOT handle this option. You must use a program such as VPUTIL version 3.0 or later, or VPUNPACK version 3.0 or later to unpack your RST file. If you are using WinPlan, this option is ignored. EXAMPLE: bigtargets y Race Name Processing Command ---------------------------- Command Name : 'racename' (minimum characters: 'ra') Command Syntax : racename {Get | {Long|Short|Adjective name}} Enabled By : CPEnableRaceName Files Written : RACE.NM This command allows a player to view or modify his race names. The 'Get' subcommand takes no further parameters and returns a message showing the player's race names (long name, short name, and adjective) as reflected in the current contents of the RACE.NM file on the host's system. The 'Long', 'Short', and 'Adjective' subcommands allow the player to set either of these race name components. Each of these subcommands take any number of parameters which are concatenated into a single string to form the actual name. Length restrictions are imposed on race names. Submitted names which are longer than the allowed limits are silently truncated. Currently, the following restrictions exist: Race long name : 30 characters Race short name: 20 characters Race adjective : 12 characters EXAMPLE: ra l The Mighty Gaggle of Geese ra short The Geese ra adj Goose rac get Alliance Management Command --------------------------- Command Name : 'allies' (minimum characters: 'a') Command Syntax : allies {Config R CP CP...} | {Add|Drop R R...} Enabled By : CPEnableAllies Files Written : AUXDATA.HST This command allows players to make (and break) formal alliances. PHOST implements a configurable alliance mechanism allowing players to control the degree of alliance. For more information, refer to the ALLIANCE.DOC file. An alliance is offered with the 'Add' subcommand. This subcommand takes any number of race parameters indicating the players to whom alliance is offered. These race parameters are numbers in the range 1 to 11 (note that 'A' and 'B' are not to be used for players 10 and 11). An alliance is rescinded with the 'Drop' subcommand. This subcommand also takes any number of race parameters. The alliance levels are configured using the 'Config' subcommand. The first parameter to this subcommand is a race number (1 through 11) and the remaining parameters specify which levels of alliance are to be enabled or disabled for this player. An alliance level parameter consists of a '+' (enable) or '-' (disable) character followed by a code name for the level. Each code name may be abbreviated simply by using the first letter. The code names are as follows: Ship Alliance Level -- 'ships' Planet Alliance Level -- 'planets' Minefield Alliance Level -- 'mines' Combat Alliance Level -- 'combat' Vision Alliance Level -- 'vision' EXAMPLE: al add 5 6 allies config 5 +ships +plan -m allies config 6 -s -p -m +com -v a d 7 Player Message Command ---------------------- Command Name : 'message' (minimum characters: 'm') Command Syntax : message {R [R R...] | Universal} Enabled By : CPEnableMessage plus AllowPlayerMessages Files Written : None This command allows a player to send a message to a list of other players. The effect is the same as if the usual Planets messaging facility were used except that the specific players to receive the message can be specified (unlike Planets which only lets you send a message to one recipient or to all players). The parameters of the message command are race numbers. There may be as few as 1 or as many as 12. Note that race numbers must be numeric only and, specifically, races 10 and 11 are NOT to be specified as 'a' or 'b'. As a special case, if the single word 'universal' (or just 'u' for short) is given as the only parameter, then this is equivalent to specifying all 11 races. A race number of 12 will send the message to the HOST.LOG file. If the host person reviews the HOST.LOG file after a host run, then this is one way of sending a message to the host. The remainder of the command message is the body of the text to send to the receivers, hence no other command processor commands should be contained in the message. Note that this command is enabled by both the CPEnableMessage and AllowPlayerMessages configuration options. Both must be ON for this command to operate (but AllowPlayerMessages need not be ON for messages sent to the host via race 12). The message generated by this command bypasses the command processor hence it need not begin with '<' if the player lists his own race as a recipient. EXAMPLE: +---------------------------------------+ |mess 2 3 4 11 | |Hey guys, we're attacking the Feds | |next turn. | | | |The Cyborgs. | +---------------------------------------+ Player Rumor Command -------------------- Command Name : 'rumor' or 'rumour' (minimum characters: 'ru') Command Syntax : rumor {R [R R...] | Universal} Enabled By : CPEnableRumor plus AllowPlayerMessages Files Written : None This command is identical to the 'message' command except for one difference, the sender of the message is not seen by the players. This command can be used to send anonymous messages to one or more players. Note that this command is enabled by both the CPEnableRumor and AllowPlayerMessages configuration options. Both must be ON for this command to operate. Also, the words 'rumor' and 'rumour' are synonyms. Be aware that the identity of the player sending the rumour can be discerned in certain circumstances. Since messages are processed in order, then if a player sends a universal message, a rumour, then another universal message, it will be clear to the recipients that the same player originated the rumour. Rumours, then, are meant only for fun, not as a means of guaranteeing anonymity. EXAMPLE: +-------------------------------------+ |rumor 1 10 | |I've heard a rumor that next | |turn, you'll be toast. | | | |Deep Throat | +-------------------------------------+ External Processing Command --------------------------- Command Name : 'xtern' (minimum characters: 'x') Command Syntax : xtern Parm Parm ... Enabled By : None Files Written : None The purpose of this command is to allow external host utilities to have a player input mechanism to control their behavior. Much like the other command processor commands modify PHOST behavior, the 'xtern' command can be used to pass application-specific parameters to an add-on utility to modify its behavior. This command can be used as an "escape mechanism" for communication with other utilities. This command will add one line to the file "xterncmd.ext" in the game directory. Any existing file by this name will be overwritten, and the file will be created if it does not exist. The first line of this file contains the turn number followed by the 18-character time stamp of the current turn. The format of each subsequent line in this file is as follows: P: ARG1 ARG2 ... where 'P' is the player number (1 through 11) and 'ARG' are the parameters of the 'xtern' command as specified by the player. For example, if the command processor command from player 3 is: xtern buy a vowel then PHOST will write the following line to the "xterncmd.ext" file: 3: buy a vowel The 'xtern' command has no other function other than writing to this external file. It does not affect PHOST in any other way, and this command never returns an error. Note, also, that the "xterncmd.ext" file will not be written to if PHOST is running in read-only mode (with either the -r or -c flags). EXAMPLE: xtern cmd parm parm Give Ship/Planet Command ------------------------ Command Name : 'give' (minimum characters: 'g') Command Syntax : give {Ship|Planet} NNN [To] R Enabled By : CPEnableGive Files Written : None This command is used to transfer ownership of a player's ship or planet to another player. A player may give his ship or planet to any other race (they need not be allies) as long as: * The player that is to receive the ship or planet has at least one of their own ships in the same location. OR * If a ship is being given away, the ship is in orbit over a planet owned by the player that is to receive the ship. The transfer of ownership takes place immediately (i.e., during TRN file processing and before any host operations) but not until all 'give' commands have been scanned. Thus, it is possible for two races to trade ships in a single turn. The 'gsN' friendly code has the same effect as the 'give ship' command. Note that the friendly code, however, has precedence over 'give ship'. When a ship is given away, its waypoint is cleared (hence the ship will not move this turn), its mission is cleared, its primary enemy is cleared, and its friendly code is randomized. When a planet is given away, its friendly code is randomized. If there is a base orbiting the planet, then all hulls in base storage are recycled and any pending build order is cancelled. Any number of 'give' commands may be submitted in one turn but only the last command for a given ship or planet is remembered. That is, if a ship is given to race 4 and then another command gives it to race 5, then race 5 will receive the ship. The word following 'give' in the command must be 'ship' or 'planet' but both can be shortened to a minimum recognizable sequence, 's' or 'p' are the shortest cases. The next word must be a ship or planet number in the range 1 to 500. The next word is optional, but if it is present, it must be "to" or simply 't'. Finally, the last word is the race number that is to receive the ship or planet. It is a number in the range 1 to 11. EXAMPLE: give ship 123 to 5 g p 321 4 give sh 2 t 11 Send Command ------------ Command Name : 'send' (minimum characters: 's') Command Syntax : send {Config|Racenames} Enabled By : CPEnableSend Files Written : None This command is used to request that PHOST include the contents of the host's PCONFIG.SRC file ('send config') or RACE.NM file ('send racenames') in the player's UTIL.DAT file. Player-side utilities can then extract the file contents from the UTIL.DAT file and leave it as a separate file on the player's system. Note that the functionality of 'send config' is duplicated by the 'con' planetary friendly code. Both have the same effect, and both are either enabled or disabled by CPEnableSend. If the requested file is not available in the game directory, then this command does nothing and no error is generated. EXAMPLE: send config s r Extended Mission Command ------------------------ Command Name : 'extmission' (minimum characters: 'e') Command Syntax : extmission Ship Mission [Parm1 [Parm2]] Enabled By : always enabled Files Written : None This command is meant to provide DOS Planets players access to the PHOST extended missions (see MISSIONS.DOC for more details). WinPlan players can use the M.I.T. interface from the ship mission screen to access extended missions. The 'extmission' command always takes at least two parameters, the ship whose mission is to be changed and the extended mission number for the ship. Extended mission numbers are those set in the MISSION.INI file (for WinPlan players) and nominally begin with 20, increasing up to however many extended missions PHOST currently supports. Note that the host can change the base extended mission value so the player using the 'extmission' command needs to receive this value from the host. Please see the MISSIONS.DOC file for a list of extended mission numbers. Some extended missions require parameters. In WinPlan, the "Intercept" and "Tow" numbers represent these parameters. Here, they are simply specified following the ship and mission numbers ('Parm1' and 'Parm2'). Not specifying all required parameters for a given mission will cause the 'extmission' command to fail. It is not to be debated that this interface to the extended missions is gruesome. For those players not using WinPlan, one can only hope that alternative interfaces (using the 'extmission' command as a service) will lessen the burden on the player. EXAMPLE: extmission 123 20 ext 235 21 100 0 e 301 24 30 Client Identification Command ----------------------------- Command Name : 'client' (minimum characters: 'c') Command Syntax : client Word [Word ...] Enabled By : always enabled Files Written : None This command is not for use by players. It is intended to be used by client programs as a means of identifying themselves to PHOST. If PHOST knows what client program a player is using then it can adjust its operation to take into account any special features offered by that client, or work around any known bugs in that client program. If PHOST receives a 'client' command then it will write the client name information to the REG.LOG file. The client name information is arbitrary, although the main name of the client program should be the first word following the command. Once again, this command is not meant to be directly issued by players. It is expected that the client program will directly insert a message with this command in it into the list of outgoing messages for that turn. PHOST currently recognizes any client name beginning with "VPA" to represent the VPA (VGA Planets Assistant) client program by Alex Ivlev. EXAMPLE: client VPA 3.49a c Yoyodyne 1.11