![]() |
Command Processor
|
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.
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:
<<< Universal Message >>> |
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, Planets Command Center and
recent versions of VPA 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.
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.
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.
(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.
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)
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.
Parameter | Action |
---|---|
+priv | Offer privilege unconditionally |
~priv | Offer privilege conditionally |
-priv | Withdraw privilege |
+/-ships | Offer/withdraw ship level |
+/-planets | Offer/withdraw planet level |
+/-mines | Offer/withdraw mine level |
+/-combat | Offer/withdraw combat level |
+/-vision | Offer/withdraw vision level |
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.
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.
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.
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.
Last updated 20 March 2004.