[PHost Logo]

Command Processor
The Portable Host
Version 4.0a

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

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

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

languageMinimum 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
Englishenstandard, compatible to HOST
GermangDOS codepage 437/850
FrenchfDOS codepage 437/850
SpanishsDOS codepage 437/850
Italiani
Dutchd
RussianrDOS codepage 866 ("alt")
EstonianesDOS codepage 437/850 (?)
PolishpDOS codepage 852
NewEnglishnewenEnglish 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.

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

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

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

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

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

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

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

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

sendMinimum 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.
extmissionMinimum 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.
clientMinimum 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.

remoteMinimum characters: re
Syntax: remote Control|Drop <id>
Syntax: remote Forbid|Allow <id>
Syntax: remote Forbid|Allow Default
Enabled by: CPEnableRemote
Files modified: auxdata.hst
beamupMinimum characters: be
Syntax: beamup <id> <items...>
Enabled by: AllowBeamUpMultiple
filterMinimum 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.

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 18 May 2003.