[PHost Logo]© 

The Command Processor
The Portable Host
Version 3.2.3.5g
 

INDEX

Introduction

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.

Back to the index 


Sending Command Messages

Players communicate with the command processor via command messages. These are simply messages composed within the client program's 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:

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.

==> Note that EchoView[Remote] and PCC[Remote] will automatically generate command messages in response to menu-driven functions from its graphical interface. Using EchoView in this fashion is preferable to sending command messages directly as it is simpler and there is less chance of error.

Back to the index 


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.

Parameters can be separated by any amount of whitespace.

Commands that don't fit on one line can be continued on the next line (PHost 3.4b and later). Just start the next line with a "+" sign to tell PHOST that it actually belongs to the previous one. For example,
racename long The Vorticons
+of Fribbulus Xax
will set your race name to "The Vorticons of Fribbulus Xax". This does not apply to the message and rumor (resp. rumour) commands. These will fit on one line, the next line will always be the first line in the message.

Back to the index 


Command Message to Add-Ons

Since version 3.4b, PHOST accepts a special format for messages to add-ons.

name: command
(first word ends with a colon). This will do exactly the same as the old way,
x name: command
see under xtern for more information. This will only work with add-ons that accept these commands, but we hope new add-ons will support it. The idea is that add-ons can recognize that a command was sent to them and can generate error messages if they don't understand it. Without such a addressing mechanism, they would always have to assume that the command was for some other add-on and ignore it silently.

For consistency, PHOST recognizes the word "phost:" to mean commands addressed to PHOST itself.

Back to the index 

Externalizing Commands

Since version 3.4d, the commands "allies", "remote" and "give" can be externalized. When players send these commands, PHost will not perform the respective operation; it will instead just write the command into xterncmd.ext. An external program can gather them up there, and perform the requested operations. While doing so, it can employ all sorts of restrictions ("players may not have more than one alliance", "you may not remote control ships over 200 kt", ...).

For example, when player 7 gives the command a add 3, PHost will write the following line into xterncmd.ext:

7: allies: add 3

(note how PHost has expanded the first word of the command and added a colon). Note that PHost will not validate the command (apart from checking its first word). For example, a b c is happily expanded into 7: allies: b c. Your program must cope with that. After all, a player could also have put this line into xterncmd.ext using the normal xtern command.

Back to the index 

The AUXCMDS.TXT Interface

PHOST since version 3.4h reads a file AUXCMDS.TXT at the beginning of phase 2. The file has the same format as xterncmd.ext:

7: allies add 3

This file has two purposes:

The commands message, rumor and xtern, as well as command messages to addons (which are just xtern in disguise, see above), are not allowed in this file. PHOST deletes AUXCMDS.TXT after processing it.

Back to the index 


Command Descriptions

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 enabled).

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 hosting 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.


 
Command Name:  language (minimum characters: 'l') 
Command Syntax:  language {ENglish|German|French|Spanish|Italian|Dutch|Russian|EStonian|Polish|NEWENglish} 
Enabled By:  CPEnableLanguage 
Files Written:  PCONFIG.SRC
This command allows a player to specify the language in which he/she receives messages from PHOST. Currently, the valid parameter values are English, German, French, Spanish, Italian, Dutch, Russian, Estonian, Polish and NewEnglish. The first letter of each language may be used as an abbreviation (in the same way that command names can be abbreviated), except for English and Estonian which require the first two letters as a minimum, and NewEnglish which needs five letters minimum.
When you use a program which relies on message scanning (such as VPA 3.51), you should use the English messages for the program to work find. If your program evaluates util.dat, you can choose any language you like. NewEnglish is intended to be a "better" version of the English messages.
 

EXAMPLE: 
    lang english
    l ger

 
Command Name:  bigtargets (minimum characters: 'bi') 
Command Syntax:  bigtargets {Yes|No} 
Enabled By:  CPEnableBigTargets 
Files Written:  PCONFIG.SRC 
The AllowMoreThan50Targets configuration option allows DOS Planets and VPA players to select whether or not they wish  to receive more than 50 scanned ship records (targets) in the RST file generated by PHOST. 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.

==> The bigtargets command is irrelevant for WinPlan players. There is no need to use it and it has no effect.

==> 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.
 

EXAMPLE: 
    bigtargets y 

 
Command Name:  bigminefields (minimum characters: 'bigm') 
Command Syntax:  bigminefields {Yes|No} 
Files Written:  PCONFIG.SRC 
The AllowMoreThan500Minefields configuration option allows players to select whether or not they wish to receive information about minefields with IDs higher than 500. It is currently unknown which clients and utilities support minefields with high IDs or many minefields (>500).

==> WARNING: DO NOT ENABLE THIS OPTION IF YOU DO NOT USE A PROGRAM THAT CAN HANDLE IT!!!

==> This option has no effect if the CPNumMinefields option is set to a value of 500 or less.
 

EXAMPLE: 
    bigminefields y
    bigm n 

 
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 lo The Mighty Gaggle of Geese
    ra short The Geese
    ra a Goose
    rac get

 
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, please refer to the "Alliances" page.

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), '-' (disable), or '~' (conditionally enable) 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

 
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 client program messaging facility were used except that the specific players to receive the message can be specified (unlike some client programs which only let 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 enabled for this command to operate (but AllowPlayerMessages need not be enabled 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.


 
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 enabled 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


 
Command Name:  xtern (minimum characters: 'x') 
Command Syntax:  xtern Parm Parm ... 
Enabled By:  None 
Files Written:  XTERNCMD.EXT 
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. For each turn, 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 

 
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: OR 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. That is, if a ship is being given away using both the friendly code and a command processor command, the friendly code determines the new owner.

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

 
Command Name:  send (minimum characters: 's') 
Command Syntax:  send {Config | Racenames | Fcodes} 
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), or a list of special friendly codes (send fcodes) in the player's UTIL.DAT file (in a File Transfer record). 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. Two player utilities that currently perform this function are EchoView[Remote] and ListUDat[Remote].

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.

For the send fcodes command, PHOST will send a file named XTRFCODE.TXT. This file will contain all friendly codes that PHOST considers to be special and will never be allowed to match. This file will include the contents of any XTRFCODE.TXT file that is present on the host's system (see the Additional Special Friendly Codes section of the "Hosting with PHOST" page for more details). Thus, the player's XTRFCODE.TXT file (obtained via the send fcodes command) will actually be a superset of the host's XTRFCODE.TXT file (if it exists) as the player's file will contain PHOST's internal friendly code list.
 

EXAMPLE:
    send config
    s r

 
Command Name:  extmission (minimum characters: 'e') 
Command Syntax:  extmission Ship Mission [Parm1 [Parm2]] 
Enabled By:  AllowExtendedMissions
Files Written:  None 
This command is meant to provide players using the DOS Planets client program access to the PHOST extended missions. WinPlan players can use the M.I.T. interface from the ship mission screen to access extended missions and need not use this command. Similarly, VPA players can simply choose an extended mission the way they would select a normal mission. Both WinPlan and VPA players should place the MISSION.INI file that comes with PHOST (or one that is provided by the game's host) into the game subdirectory. ==> To repeat, only players using the DOS Planets client program need to use this command.

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 "Extended Ship Missions" page for a list of extended mission numbers.

Some extended missions require parameters. In WinPlan/VPA, 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.

The extmission command may also be used to set an extended mission that is in use by another add-on and not recognized by PHOST (but in no case can the mission be set to a number less than 20). In this case, PHOST will not check to see that the command includes sufficient parameters (for the Parm1 and Parm2 fields). The player is responsible for specifying sufficient parameters, otherwise the unspecified parameters may have unpredictable values.

It is not to be debated that this interface to the extended missions is gruesome. For those players not using WinPlan or VPA, one can only hope that alternative interfaces (such as EchoView[Remote], which uses 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

 
Command Name:  client (minimum characters: 'c') 
Command Syntax:  client Word [Word ...] 
Enabled By:  always enabled 
Files Written:  REG.LOG 
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[Remote] (VGA Planets Assistant) client program by Alex Ivlev. Additional client program codes known to be in use (though not recognized by PHOST) are xk and PCC.
 

EXAMPLE:
    client VPA 3.49a
    c Yoyodyne 1.11

 
Command Name:  remote (minimum characters: 're') 
Command Syntax:  remote {Control|Drop} ShipID
remote give ShipID [to] PlayerId
remote {Forbid|Allow} {ShipID | "Default"}
Enabled By:  CPEnableRemote 
Files Written:  AUXDATA.HST 
This command is used to interface to the remote control feature of PHOST. Please see the "Remote Ship Control" page for more information on what this feature does.

The control subcommand allows a player to gain control of an ally's ship. The drop subcommand is used by a player currently controlling a foreign ship to terminate the remote control. The forbid subcommand is used by a ship's owner to prevent other players from acquiring remote control over the ship. Finally, the allow subcommand is used to once again allow players to control a ship, if it was previously forbidden. All subcommands may be abbreviated up to a single letter.

The give subcommand places a ship under some other player's remote control. It is perfectly identical to remote allow by the original owner, followed by remote control by the other player.

In all cases, the ShipID parameter must specify a valid ship ID. For the control and drop subcommands, this must be a ship that is owned by another player who is an ally and has enabled the Ship Level of alliance to the player issuing this command. The forbid and allow subcommands must refer to a ship owned by the player issuing this command.

The forbid and allow commands can be given a parameter of "Default" (abbreviated up to a single letter) instead of a ship ID. In this case, the command indicates the default forbid/allow state for all ships built after this command is processed. That is, this command does not apply to existing ships. The forbid default command indicates that by default, all newly-built ships may not be remotely controlled. The allow default command indicates the opposite. At the beginning of the game, it is assumed that all newly built ships are allowed to be remotely controlled.

EXAMPLE:
    remote control 349
    rem d 221
    re f 498
    remote forbid default

 
Command Name:  beamup (minimum characters: 'be') 
Command Syntax:  beamup ShipID  [Nnnn] [Tnnn] [Dnnn] [Mnnn] [Cnnn] [Snnn] [$nnn] 
Enabled By:  AllowBeamUpMultiple 
Files Written:  None 
This command is used to in conjunction with the Beam Up Multiple extended mission. Together, a ship is allowed to beam up any mineral, clans, supplies, or credits from a friendly planet (e.g., an ally's planet, a planet which is unowned, a planet which matches the ship's friendly code, etc.) The extended mission sets the ship's mission, while the beamup command processor command tells PHOST how much of each resource to beam up. Sending the beamup command is sufficient, however, since it automatically sets the ship's mission to be Beam Up Multiple. The extended ship mission is really only there to remind the player of what the ship has been instructed to do. ==> Note that sending this beamup command sets the ship's mission and overrides any other mission that has been set for the ship. ==> Note also that setting the Beam Up Multiple extended mission without sending an associated beamup command does nothing. In summary, setting the extended mission is optional, sending the beamup command is not.

The first parameter must be the ID number of the relevant ship. This is followed by any number of resource amount specifications. Each specification begins with a single character, such as N for neutronium, C for clans, and $ for megacredits (see the command syntax above). The letter must be immediately followed by a number indicating the maximum amount of this resource to beam up. There must be no space or other character(s) between the character identifying the resource and the amount of that resource to beam up. Resource amount specifications may come in any order.

If there is no resource specification for a resource, then none of that resource will be beamed up. ==> As a special case, if the amount of a resource to beam  up is listed as max, then as much of that resource as possible is beamed up.

Subsequent beamup commands override any previous command for that ship. That is, the commands are not additive. All resources to beam up must be specified in a single command.

==> Note that the beaming up of clans is further restricted by the AllowBeamUpClans config option. With this option disabled, clans cannot be beamed up.

==> Note that, as a safety feature, at least 1 clan will be left remaining on a planet after beaming up clans with this mission. That is, this mission will not remove the last clan from a planet.

Finally, the beaming up of  minerals, clans, and supplies goes in the order: tritanium, duranium, molybdenum, clans, supplies. If a ship becomes full before beaming up all specified resources, no more resources are beamed up (this does not interfere with beaming up fuel and megacredits, however).
 

EXAMPLE:
    beamup 312 N100 T200 C50 $2000
    be 217 Nmax Tmax Dmax Mmax Cmax $max

 
Command Name:  filter (minimum characters: 'f') 
Command Syntax:  filter {Yes|No} 
Enabled By:  None
Files Written:  PCONFIG.SRC 
The FilterPlayerMessages configuration option allows players to select whether they receive all messages (as usual) or only messages not duplicated in their UTIL.DAT files. Please see the Message Filtering section of the "Playing with PHOST" page for more details. The filter command processor command allows players to modify this config option without host intervention.
 
EXAMPLE: 
    filter y 

 
Command Name:  password (minimum characters: 'pass') 
Command Syntax:  password NewPassword 
Enabled By:  DisablePasswords
Files Written:  GEN.HST 

This command allows players to change their passwords. The main use, however, is to let hosts change the password of a dropped-out player, using the auxcmds.txt interface. This avoids having to use CRACK and tell the replacement player the old password.

This command is otherwise identical to the client function. If multiple password change requests are received, the last one gets effective. If both the command message and the client function are used, the client function gets effective because it is processed last.

EXAMPLE: 
    password NOPASSWORD
    password LKsgf2
Back to the index 
This document is maintained by The Portable Host Project[Remote] (support@phost.de).

Last updated 24 July, 2005