[PHost Logo]

Command Processor
The Portable Host
Version 4.0e

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 top


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], Planets Command Center[Remote] and recent versions of VPA[Remote] can automatically generate command messages in response to menu-driven functions from its graphical interface. Using these features is preferable to sending command messages directly as it is simpler and there is less chance of error.

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.

(v3.4b:) Commands that don't fit on one line can be continued on the next line. 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 always fit on one line, the line following the command will always be the first line in the message.

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. phost: send fcodes will do the same as just send fcodes.

Externalizing Commands

(v3.4d:) Some commands can be externalized:

To externalize a command, set the corresponding configuration option to External. When PHost receives such a command, it will not execute it itself; it will instead write it to xterncmd.ext. An add-on program can then read them there, and execute them. Such an add-on program can enforce a variety of restrictions without requiring the players to talk to the add-on directly.

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

7: allies: add 3

Note how PHost has expanded the first word, and added a colon. PHost does not validate the command (apart from checking the first word). a b c is happily expanded into 7: allies: b c. Your program must cope with that. After all, the player could as well have used the normal xtern command to write this line manually.

Executing Commands from the Host-Side

New v4.0e: Hosts can also provide PHost with a list of commands to execute on players' behalf. Directly after Auxhost1, PHost reads a file auxcmds.txt and executes the commands contained therein. The file consists of lines of the form race: command, similar to xterncmds.ext. The command would then be executed (almost) as if it were contained in race's turn file.

There are some important differences between commands contained in this file and commands from turn files, though:

PHost will delete the auxcmds.txt file after executing the commands.

Example: If a host wants to set up permanent treaties between certain races, he would set CPEnableAllies = No (so players cannot modify alliances) and host turn one with a auxcmds.txt file containing, for example,

3: allies add 5
5: allies add 3
3: allies config 5 +s +p +m +c +v
5: allies config 3 +s +p +m +c +v

(This file is equivalent to running pally -t 35)

Back to top


Command Descriptions

This chapter describes all commands currently recognized by PHost. Most commands can be turned on and off in the configuration; the descriptions will list the respective configuration options.

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. If a command requires some more words, those can usually be abbreviated with their first letter, unless specified otherwise. For example, allies config 4 +mines can be shortened to a c 4 +m.

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.

allies Minimum characters: a
Syntax: allies add|drop <player...>
Syntax: allies config <player> <flags...>
Enabled by: CPEnableAllies
Files modified: auxdata.hst

The three sub-commands of the allies command are used to set up formal alliances.

Examples:

allies add 8 offer alliance to player 8, or accept alliance offered by player 8
a a 8 same
allies config 8 +mines +vision offer mine and vision level to player 8
allies config 8 ~com offer combat level conditionally, that is, player 8 can only use it when he offers it, too
a c 8 ~c same
a d 1 drop alliance with player 1

For details about alliance mechanics, see the page about alliances.

Relevant config options: CPEnableAllies, DelayAllianceCommands.

Relevant PControl stages: depending on DelayAllianceCommands, all alliance commands are performed just before Auxhost1 or just after Auxhost2.

beamup Minimum characters: be
Syntax: beamup <id> <items...>
Enabled by: AllowBeamUpMultiple

This command is used in conjunction with the Beam up Multiple mission. You can beam up any combination of minerals, cash, etc. from a friendly planet. The mission tells PHost that you want to beam up things, and the beam up tells what you want. Actually, the command alone is sufficient, because it will overwrite the ship's mission with Beam up Multiple. The extended mission is mainly there to remind the player of what the ship has been instructed to do.

==> Using this command will overwrite the ship's mission with Beam up Multiple. Using the mission without an associated beamup command will do nothing (the ship will not know what to beam up).

The first parameter of this command is a ship Id. The following parameters specify what you want to beam up. Each entry consists of one character for the element type, followed directly by the amount.

Nnnn Neutronium
Tnnn Tritanium
Dnnn Duranium
Mnnn Molybdenum
Cnnn Colonists
Snnn Supplies
$nnn Money
xmax beam up as much as possible. Note that max must be spelled out, it can't be abbreviated.
x<number> beam up specified amount

If there is no specification for a resource, nothing of that type will be gathered. If there's less than you want, or your ship has insufficient cargo space, your ship will gather as much as it can. Cargo is beamed up in the same order as the above table shows: minerals first, then colonists, then supplies, then money.

You can only beam up colonists when AllowBeamUpClans is enabled. As a safety feature, at least one clan will be left on a planet. You cannot beam up the last clan using this mission.

beamup commands are not cumulative. If you give multiple commands for one ship, only the last one will be processed, the others will be completely ignored.

Examples:

beamup 12 N40 ship 12 gathers 40 kt Neutronium
beamup 12 N 40 invalid: no space allowed between cargo type and amount
beamup 93 Nmax $100 ship 93 gathers as much fuel as it can, and 100 mc
be 93 nmax $100 same, but abbreviated
beamup 93 Nmax$100 invalid: must have space between different types
bigminefields Minimum characters: bigm
Syntax: bigminefields yes|no
Files modified: pconfig.src

This command can be used to set your entry of the AllowMoreThan500Minefields config option.

Many clients have a limit of 500 minefields (as does HOST and many previous PHost versions). With this option disabled, PHost will suppress subspace messages about high-Id minefields, and sent util.dat information in a different format (record 46 instead of record 0).

==> Do not use when your unpack program and/or client can not handle it.

bigtargets Minimum characters: bi
Syntax: bigtargets yes|no
Files modified: pconfig.src

This command can be used to set your entry of the AllowMoreThan50Targets config option.

The DOS client (planets.exe) has a limit of 50 scanned enemy ships (targets) per turn. Many replacement programs do not have this limit. Using this command, you can tell PHost to send you all targets instead.

==> Do not use when your unpack program and/or client can not handle it.

Normally, you don't need this command these days: when you use a Winplan-compatible unpack/maketurn, PHost will encode the targets in a special section of the result file. Otherwise, PHost will also pack the excess targets into util.dat (record 10) where most programs which can display them will find them.

client Minimum characters: c
Syntax: client <text>
Files modified: 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.

The following client names are known to be in use:

PHost will preserve long waypoints when VPA is being used.

extmission Minimum characters: e
Syntax: extmission <id> <mission> [<arg1> [<arg2>]]
Enabled by: AllowExtendedMissions

This command is meant for DOS Planets users to access extended missions provided by PHost and add-ons. Users of Winplan and most 3rd-party clients can use the "extended missions" or "M.I.T." interface of their clients.

The extmission command takes at least two parameters.

==> Only DOS Planets users need to use this command. The mission set with this command will override the one you enter on the ship screen.

Examples:

extmission 123 20 Set ship 123's mission to 20, that is Build torpedoes from Cargo
e 47 22 7 5 Set ship 47's mission to 22 (Lay Web Minefield), setting parameter one to 7 (i.e. lay 7 torpedoes as mines) and parameter two to 5 (i.e. mines will be owned by Privateers).
e 47 22 This command is rejected because mission 22 needs two parameters but none were given.
filter Minimum characters: f
Syntax: filter yes|no
Files modified: pconfig.src

This command can be used to turn the message filter on and off. When filtering is enabled, you'll not get certain messages; when filtering is off, you get all messages.

This command modifies the FilterPlayerMessages configuration option.

give Minimum characters: g
Syntax: give ship|planet <id> [to] <player>
Enabled by: CPEnableGive

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. The receiving race must, however, have a planet or ship at the same position as the unit whose ownership you're transferring.

All ownership transfers take place at once. Hence, it is possible for two races to trade ships in the same turn.

The gsX friendly code has the same effect as the give ship command.

Examples:

give ship 3 to 7 Give ship #3 to the Crystals
g s 3 7 same, but abbreviated

Relevant config options: CPEnableGive.

Relevant PControl stages: TransferOwner.

language Minimum characters: l
Syntax: language <language-code>
Enabled by: CPEnableLanguage
Files modified: pconfig.src

This command chooses the language you wish to receive your sub-space messages in. PHost can generate messages (sensor sweep, combat reports, etc.) in different languages:

Language Minimum Notes
English en standard, compatible to HOST
German g DOS codepage 437/850
French f DOS codepage 437/850
Spanish s DOS codepage 437/850
Italian i
Dutch d
Russian r DOS codepage 866 ("alt")
Estonian es DOS codepage 437/850 (?)
Polish p DOS codepage 852
NewEnglish newen English without HOST compatibility quirks

All language names can be shortened to the abbreviation shown in column two.

==> When you request messages in a different language, make sure you can also read them. Accented characters are encoded using a DOS codepage. If you're using a Windows-based program, that one should be able to translate the characters into Windows format.

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

message Minimum characters: m
Syntax: message <player...>
Syntax: message universal

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 player numbers. The value 12 can be used to send a message to the host. ==> Note that receiver numbers must be completely numeric. In particular, Rebels and Colonies are addressed as 10 and 11, not A and B.

As a shortcut to specifying all 11 races (message 1 2 3 4 5 6 7 8 9 10 11), you can also use the shortcut message universal (or simply m u).

The remainder of the message containing the message command will be sent as the message text; no further commands are processed there.

Messages sent with this command are otherwise perfectly identical to messages sent normally. In particular, *w* will send the message anonymously (see also rumor, though).

Relevant config options: AllowPlayerMessages, AllowAnonymousMessages.

racename Minimum characters: ra
Syntax: racename get
Syntax: racename long|short|adjective <name>
Enabled by: CPEnableRaceName
Files modified: race.nm

This command can be used to request or change your race name.

remote Minimum characters: re
Syntax: remote control|drop <id>
Syntax: remote forbid|allow <id>
Syntax: remote forbid|allow default
Syntax: remote give <id> [to] <race>
Enabled by: CPEnableRemote
Files modified: auxdata.hst

This command is the interface to the Remote Control feature in PHost. See there for more details.

The command has three purposes:

Examples:

remote control 42 request to be given remote control over ship 42
re c 42 same, but abbreviated
re a 42 allow ship 42 to be remote controlled
rem forbid def all ships you build in the future will not be available for remote control by default

(v3.4c:) Remote control commands are processed in the order (1) drop, (2) allow and forbid, (3) request, (4) give. In particular, you can allow remote control for a ship and have your ally control it in one turn. Earlier PHost versions process commands in whichever order they come in, so this manoeuver can fail when the control request is processed before the allow.

rumor Minimum characters: ru
Syntax: rumor <player...>
Syntax: rumor universal

This command is like message (see there for a description of the parameters), but it will be sent without an identification of the sender. The receiver will not know who sent the rumor.

You can also make a message anonymous by placing the character sequence *w* somewhere in it; you need not use this command.

PHost also accepts the spelling rumour for this command.

==> In PHost versions prior to 3.4c, this command didn't guarantee anonymity. In 3.4c and later, it does. It's just more fun this way :-)

==> Note that when anonymous messages are disabled in the game configuration, the message will be delivered with sender identification.

Relevant config options: AllowPlayerMessages, AllowAnonymousMessages.

send Minimum characters: s
Syntax: send <item>
Enabled by: CPEnableSend

This command asks PHost to send a particular file to you. The file will be sent as a file transfer record in util.dat, where client-side programs can unpack it.

The following files can be requested:

send racenames Sends you the current race names (race.nm). Message-scanning programs usually need these to understand your messages; and of course it helps when all players talk about the same race names, so everyone agrees who is playing The Frogs today. Players who use registered Winplan or compatible always get the current race names in a special section of their result file.
send config Sends you the current configuration (pconfig.src). Several clients use that file to adapt their predictions to the actual game configuration.
send fcodes Sends you a list with the current special friendly codes (xtrfcode.txt). This file just lists all special friendly codes.
xtern Minimum characters: x
Syntax: xtern <command...>
Files modified: xterncmd.ext

The xtern command can be used to give commands to add-on programs. Much like the other commands are processed by PHost, xtern commands can be processed by add-ons who wish to do that.

This command will simply write its parameters to the file xterncmd.ext in the game directory, preceded by your player number. For example, when you are player 3, and you write the command

xtern buy a vowel

PHost will write the line

3: buy a vowel

to xterncmd.ext.

When the first word of the command ends with a colon, you can also omit the xtern. That is, the following two are equivalent:

xtern mfq: keep 3
mfq: keep 3

The set of available commands depends on the add-ons running in the game. This command will never return an error. PHost can not know whether there's an add-on which evaluates a particular command.

Back to top


Storing Commands Client-Side

Programs which generate commands must be able to transmit them to the host, as well as find them again in the client data. There are two ways to accomplish that, which are described here.

In the Message File

You can store the commands directly in the message file (messX.dat, mess35X.dat). This is the cleanest way, but it needs a lot of work to find the commands again, for example, when the user chose to delete a command.

When users write commands themselves, your program might also find and manipulate a user-written command, which may or may not be your intention.

The big advantage of this method is that it works with every Maketurn program.

The Auxiliary Commands File

To address the above problems, we have defined an auxiliary command file format. In addition to PHost commands, this file can also contain any other auxiliary command data you want to write. On the downside, you need a modified Maketurn to actually send the commands to the host.

The auxiliary command file is called cmdX.txt, where X is the player number. It is a text file. Every line can be one of the following:

The following special commands are defined so far:

Every command shows what Maketurn supports the command as of March 2003. Feel free to support it in your client, and feel free to add more special commands if you wish. To avoid confusion, we recommend you to use this file format instead of inventing another incompatible one.

Example:

# Additional Commands
$time 04-14-199921:34:42
allies add 9
allies config 9 +c ~m

The first line is a comment. The second one tells us the turn this file belongs to. The third and forth line generate two allies commands.

Back to top


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

Last updated 29 December 2003.