PHost - Command Processor

Index

• Introduction
• Sending Command Messages
  • Command Message Formats
  • Command Message to Add-ons
  • Externalizing Commands
  • Executing Commands from the Host-Side
• Command Descriptions
  • allies
  • beamup
  • bigminefields
  • bigtargets
  • client
  • enemies
  • extmission
  • filter
  • give
  • language
  • message
  • password
  • racename
  • refit
  • remote
  • rumor
  • send
  • show
  • transfer
  • unload
  • xtern
• Host-Only Commands
  • addfunction
  • inhibitfunction
  • removefunction
• Storing Commands Client-Side
  • In the Message File
  • The Auxiliary Commands File

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:

• 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. The same goes for VPA's team messages.
• 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.

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.

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:

• allies (CPEnableAllies)
• enemies (CPEnableEnemies)
• give (CPEnableGive)
• refit (CPEnableRefit)
• remote (CPEnableRemote)
• show (CPEnableShow)

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 the command, and execute it. Such an add-on program can enforce a variety of restrictions or add new functionality 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 expanded into 7: allies: b c. Your program must therefore be prepared to handle invalid arguments. After all, the player could as well have used the normal xtern command to write invalid commands into xterncmd.ext.

Executing Commands from the Host-Side

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

• Commands read from this file bypass all configuration restrictions. Even if CPEnableAllies is off, PHost will accept (and execute) allies commands from auxcmds.txt.
• Execution order differs slightly. Normal remote control and alliance commands are performed before Auxhost1 (the latter only if DelayAllianceCommands is off, which is the default), whereas auxcmds.txt is read afterwards. Therefore, the complete mission ordering is
  1. perform all alliance changes from TRN files
  2. perform all remote control commands from TRN files, in the order "give", "allow/forbid", "control", "give"
  3. Auxhost1 runs here
  4. perform all alliance changes from auxcmds.txt
  5. perform all remote control commands from auxcmds.txt, in the order "give", "allow/forbid", "control", "give"
  In particular, a remote control from a turn file can fail if the necessary alliance is not established until step four, and a remote forbid from auxcmds.txt overrides a remote allow from a turn file.
• For plug-compatibility with externalized commands, commands may have a colon immediately after the command word, as in 6: allies: add 4 ("the Cyborgs offer an alliance to the Klingons")
• The message, rumor and xtern commands are not accepted in this file, nor are addressed commands.

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)

(v4.0i:) In addition to the normal commands, there are also special control commands for hosts. Those can be executed by prefixing the command with "control:" instead of a player number, for example,

control: inhibit 7 cloak

These commands are described below. These commands are executed while they are read, in the order in which they come in, immediately after Auxhost1.

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.

It is possible to give contradictory commands. For each command, this document describes how these conflicts are resolved.

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

• The add sub-command offers an alliance to the specified players, or acknowledges a pending offer. An alliance is active when both players have used add to declare each other as friends. The parameter list contains the player numbers, 1 for Feds to 11 (not B!) for Colonies.
• The drop sub-command cancels an alliance resp. withdraws an offer. Like add, it takes a list of player numbers as parameters.
• The config sub-command sets the privileges of an ally. The first parameter is the race, the following are alliance levels. The alliance must have been established completely for this command to take effect, but you can send it in the same turn you offer your alliance initially.

  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

  As usual, the privilege codes can be abbreviated up to their first letter.

Examples:

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

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

Relevant Configuration Options: CPEnableAllies, DelayAllianceCommands.

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

See also: enemies command

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

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:

Conflict Resolution: This command affects the mission of the ship, and therefore conflicts with other commands that do the same. The effective ship mission will be defined, in decreasing order of precedence, by: refit command, beamup command, extmission command, and mission set at the ship's control screen. For example, if a ship has both a refit and beamup order, it will do refit only.

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.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

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. However, some old programs such as VPUtil need bigtargets enabled to see everything.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

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:

• VPA: the VGA Planets Assistant
• PCC: the Planets Command Center
• xk: xk

PHost currently only handles VPA specially: when VPA submits a DOS-style turn, PHost will not truncate long waypoints, and it will not reset extended missions at the end of the turn, because it is known that VPA can display those. See also What advantages do players using Winplan or VPA have over others? in the FAQ.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

Ships normally have a primary enemy order which can be used to tell the ship to behave aggressive to one particular race. Alternatively, Kill can be used to make them aggressive to anyone.

Using enemies add, you can make your ships aggressive to several races at once (repeat the command to add several races to your set of enemies).

If your ship has a primary enemy setting of none and a mission other than Kill, it will behave peacefully as it ever did. If it has a primary enemy, however, it will behave aggressively to all your enemies (and to the ship's primary enemy). For example, assuming you have issued the commands enemies add 3 and enemies add 9, your ship will behave as follows:

These settings are global and apply to all your ships. PHost will remember these settings, and remind you about your settings each turn with a message.

To cancel a previous enemies add PLAYER, issue a enemies drop PLAYER command.

This command affects all places where the primary enemy is consulted:

• combat
• glory devices

Alliances override enemy settings. If you are allied with someone and offer him combat level, you will not be able to attack them, with neither of Kill, primary enemy, or this command.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

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.

• The first parameter is the ship Id whose mission you want to change.
• The second parameter is the mission number. Mission numbers are those listed in the mission.ini file and documented in the Extended Missions section. This command can not be used to set standard missions, use the normal mission setting functions for that. This command can, however, be used to set add-on missions.
• The third and fourth parameter are Parameter 1 (I) and Parameter 2 (T) for the mission, respectively. It depends on the mission whether you need these and what values they can take.

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:

Conflict Resolution: This command affects the mission of the ship, and therefore conflicts with other commands that do the same. The effective ship mission will be defined, in decreasing order of precedence, by: refit command, beamup command, extmission command, and mission set at the ship's control screen. For example, if a ship has both a refit and beamup order, it will do refit only.

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.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

With this command, you can give one of your ships or planets to any other race. You 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 by mutually transferring ownership.

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

Examples:

Preconditions:

• The receiving race must have ship or planet at the same location (type, cloak, cargo etc. does not matter).
• Ship must not be ungiveable
• The ship does not need fuel for the trade.

Consequences:

• mission is reset, (v4.0j:) cloak is canceled (ships only);
• waypoint is reset, ship will not move this turn (ships only);
• primary enemy is reset (ships only);
• friendly code is randomized (ships and planets);
• hulls in storage are recycled (base);
• ship build order is cancelled (base). If the base is cloning a ship, that build order will be removed from the queue, and added to the end again if it is still valid;
• (v4.0k:) shipyard order (fix/recycle) is cancelled (base).

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

Relevant Configuration Options: CPEnableGive (if set to Allies, you can only give ships/planets to allies)

Relevant PControl Stages: TransferOwner.

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. The number of available languages depends on the language file (plang4.hst) installed on the host system. The default language file contains the following languages:

For backward compatibility, PHost allows you to abbreviate all these language names up to the minimum shown in column two. Other languages which might be installed in addition to those listed here cannot be abbreviated this way.

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, which doesn't have to be compatible with message-parsing programs, and thus contains updated wording and formatting.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

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 Configuration Options: AllowPlayerMessages, AllowAnonymousMessages.

This command changes the player's RST password. It is perfectly identical to the respective client function (e.g. "P" in planets.exe's main menu). A password can be up to 10 characters. It can contain all US-ASCII characters, including spaces. Passwords are case-sensitive. To prevent clients from requiring a password, set the password to "NOPASSWORD".

The main purpose of this command is to allow hosts to reset the password of a player who dropped out. The traditional solution is to use a tool such as crack to find out the password and tell that the replacement player. This is problematic from a security standpoint. Hosts can now reset the password through the auxcmds.txt interface by giving a command such as 3: password NOPASSWORD

If multiple such commands are given by a player, the last one will be effective. A password change through the client function overrides a command message (because it is processed after the messages).

Remember that this password provides only weak security. It does not prevent others from unpacking your result file and looking around with a hex editor or a patched client.

Unlike the other commands which are enabled by a config option, this one can be disabled by setting a config option. Setting DisablePasswords=Yes will also disable the command for hosts.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

Relevant Configuration Option: DisablePasswords

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

• The get sub-command takes no further arguments, and returns a message listing your three race names (long, short, adjective).
• The long sub-command modifies your long race name ("The Lizard Alliance"). The long name can be up to 30 characters. It is used mainly for headings (in client programs, and in sub-space messages).
• The short sub-command modifies your short race name ("The Lizards"). This name can be up to 20 characters. It is used in the score table, and in client programs ("This ship is owned by The Lizards").
• The adjective sub-command modifies your adjective ("Lizard"). The adjective is limited to 12 characters. It is used in messages elsewhere ("We have captured a Lizard ship").

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

This command can be used to specify the parts you want added to your ship with the Super Refit mission.

You can not downgrade your ship, that is, you can not reduce any part's type or count. If you try to do that, that part of the order is silently ignored (that is, if you try to "upgrade" a ship with two Mark 4 launchers to one Mark 6, PHost will attempt to upgrade the ship to two Mark 6 instead). Therefore, if you do not wish to change a particular component, give the respective parameter as 0. You can omit parameters at the end. If you specify more weapons than allowed on the ship, PHost silently corrects the command.

The required parts must be available at the starbase.

This command will implicitly set the ship's mission to Super Refit. It can only be used for ships owned by the Federation.

Examples:

Conflict Resolution: This command affects the mission of the ship, and therefore conflicts with other commands that do the same. The effective ship mission will be defined, in decreasing order of precedence, by: refit command, beamup command, extmission command, and mission set at the ship's control screen. For example, if a ship has both a refit and beamup order, it will do refit only.

When multiple refit commands are given for a ship, the last one takes effect.

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

The command has four purposes:

• The control sub-command is used to gain control of an ally's ship, the drop command gives it back. The ally must have offered you a ship-level alliance, and must have allowed the specified ship to be remote-controlled.
• (v4.0e:) The give sub-command can be used to place a ship under remote control by an ally. It is perfectly identical to remote allow with the ally immediately doing remote control, with the difference that only the ship owner needs to send a command, saving some coordination overhead. All other restrictions remain; in particular, you must be allied.
• When used with a ship Id, the forbid sub-command prevents your allies from taking remote control over that ship, the allow sub-command allows it again. When you forbid remote control of a ship which is under allied control, you'll get the ship back.
• When used with the keyword default, forbid and allow select the allow/forbid state for ships built after this command is processed. When a game starts, PHost assumes allow for all players.

Examples:

(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 maneuver can fail when the control request is processed before the allow.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

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 Configuration Options: AllowPlayerMessages, AllowAnonymousMessages.

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:

This command can be used to send information about an object to another player. It is very similar to establishing a mine level, planet level or ship level alliance, respectively, but it allows you to give out information selectively.

The commands can only be given by the real owner of the object. If you remote-control a ship, you can not use this command for that ship, only the real ship owner can do that.

The information will be sent at the end of the turn, and contain the new state of the object; if you lose the object during the turn, the command will be silently ignored. If you wish to send now-current information (i.e. information which is outdated when it reaches the receiver), you can do that without PHost's intervention, for example by using the data transfer feature of some clients.

You can not intercept a ship in the same turn your friend does show ship - you have to wait until you see the ship in your result file. This is the same with alliances.

Ships can transfer cargo to up to one foreign ship per turn. This command can be used to supplement or replace the corresponding client function to overcome limits imposed by clients.

This command will order the specified ship to transfer the specified cargo to the target ship.

The cargo amount can be specified as follows:

Detailed Operation: This command supplements the client-side ship-to-foreign-ship transfer function ("T" in planets.exe). Like this function, it has two parts:

• During turn processing, cargo is moved from the main cargo room to the cargo transporters.
• During the CargoTransfer stage, cargo is actually transferred to the receiver ship. If the receiver ship cannot take this cargo type or has no room, you get it back.

As a consequence, you cannot transfer cargo which you do not have at the time you give the command (such as money made by gambling ships), and the transferred goods are subject to potential robbing.

If you already used your client's transfer-to-foreign-ship function, and you give a transfer command, the transfer command must target the same ship. Both orders will be added together; you cannot transfer cargo to multiple ships in one turn. In this case, however, you can omit the to <target> part of the command.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

Preconditions: (must be fulfilled for the command to be accepted)

• ship must be at same position as target
• ships must be controlled by different players (otherwise, use the direct client-side transfer to achieve the same result)
• giving ship must have enough cargo (otherwise, amount is silently reduced)

Preconditions: (must be fulfilled for the transfer to take place)

• ship must have fuel
• ships must have same secondary weapon system if fighters or torps are to be transferred
• target ship must have enough free cargo capacity (otherwise, excess cargo is given back to original ship)

Relevant PControl Stage: Host Phase I (cargo moved to transporters), CargoTransfer (cargo transferred to target)

Ships can unload cargo to the planet they're orbiting, or dump it into space (jettison). This command can be used to supplement or replace the corresponding client function to overcome limits imposed by clients.

This command will order the specified ship to unload the specified cargo to the planet it is orbiting, or to dump it into free space if it is not orbiting a planet.

The cargo amount can be specified as follows:

Detailed Operation: This command supplements the client-side ship-to-planet transfer resp. jettison function ("C" in planets.exe). Like this function, it has two parts:

• During turn processing, cargo is moved from the main cargo room to the cargo transporters.
• During the CargoTransfer stage, cargo is actually transferred to the receiver planet or dumped into space.

As a consequence, you cannot unload cargo which you do not have at the time you give the command (such as money made by gambling ships), and the unloaded goods are subject to potential robbing.

If you already used your client's unload function, both orders will be added together.

Conflict Resolution: Commands are executed in order received, therefore the last one takes effect.

Preconditions: (must be fulfilled for the command to be accepted)

• if orbiting a planet, the planet must be owned by a different player as the ship (otherwise, use the direct client-side transfer to achieve the same result)
• giving ship must have enough cargo (otherwise, amount is silently reduced)

Preconditions: (must be fulfilled for the transfer to take place)

• ship must have fuel
• when transferring fighters or torpedoes, the planet must have a starbase to receive them
• when transferring fighters, the starbase must have enough room (otherwise, excess fighters are given back to the ship)

Relevant PControl Stage: Host Phase I (cargo moved to transporters), CargoTransfer (cargo transferred to target)

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

Host-Only Commands

The following commands are only accessible to the host through the auxcmds.txt interface. To execute one of these commands, write a line control: command to auxcmds.txt.

These commands are not available to players.

function is a hull function number or name, id is a ship Id. This command permanently adds the specified function to the ship.

For example, addfunc 39 cloak will allow ship 39 to cloak from now on.

function is a hull function number or name, id is a ship Id. This command prevents the ship from using the specified function this turn. It will behave as if it does not have this function. inhibitfunction overrides all other reasons why the ship could have the function. If you give this command together with addfunction, PHost will remember that the ship now has the new function, but will not allow it to use it this turn.

Examples:

This command is only valid for one turn. Unless you give it again next turn, the ship will again be able to cloak next turn, and it will again be unclonable.

function is a hull function number or name, id is a ship Id. This command permanently removes the specified function from the ship. This command only removes a function directly assigned to the ship (through addfunction or a AssignTo=Ship statement); if you gave the ship this function through a AssignTo=Hull statement, this command cannot remove it.

If the ship does not have the specified function, this command does nothing.

For example, remove 39 unclonable will make ship 39 clonable again (unless its ship type was made unclonable by making its hull type unclonable in hullfunc.txt).

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

• blank. Blank lines are ignored.
• a comment. Lines whose first non-blank character is a # are ignored.
• a command. These are sent to the host as command messages, unchanged.
• a special command. These are commands which start with a $, which do something special.

The following special commands are defined so far:

• $timestamp MM-DD-YYYYhh:mm:ss
  Timestamp marker. The file is stale and should be ignored if the parameter is not equal to the timestamp of the current turn. This command must be the first in the file if it is used. It can be abbreviated to "$time". Supported by PCC 1.0.17, VPA 3.61 and Portable Maketurn.
• $send-file NAME
  Generates a SendBack command containing a File Transfer record for the specified file. Supported by PCC 1.1.2 and VPA 3.61.
• $thost-allies ee1ff2
  Generates a sequence of alliance commands for HOST. Supported by PCC 1.0.17 and Portable Maketurn.
• $include NAME
  Include specified file. So far not supported by any implementation.

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

Last updated 31 May 2015.