©	The Command Processor The Portable Host Version 3.2.3.5g  Jump to Table of Contents

• Introduction
• Sending Command Messages
• Command Message Formats
• Command Descriptions

Introduction

Back to the index 

Sending Command Messages

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:

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



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

Note that EchoView and PCC 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

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.

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:

(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:

This file has two purposes:

• If you have some add-on that processes externalized commands, AUXCMDS.TXT is a simple means to have PHOST execute the commands. You do not have to implement your own version of "allies add", you can let PHOST execute the command for you. For plug-compatibility with xterncmd.ext, a colon after the command name is accepted and discarded.
• Hosts can use the file to "inject" commands into the host runs. Commands given this way bypass most command restrictions. For example, you can turn off CPEnableAllies to prevent players from changing their alliances, but still set up some fixed alliances using AUXCMDS.TXT.

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

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.
 

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.
 

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.
 

Length restrictions are imposed on race names. Submitted names which are longer than the allowed limits are silently truncated. Currently, the following restrictions exist:
 

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:
 

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.
 

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.
 

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:

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:

then PHOST will write the following line to the XTERNCMD.EXT file:

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

• the player that is to receive the ship or planet has at least one of their own ships in the same location

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

EchoView

ListUDat

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.
 

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, which uses the extmission command as a service) will lessen the burden on the player.
 

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. Additional client program codes known to be in use (though not recognized by PHOST) are xk and PCC.
 

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.

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

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.

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