Global Commands

Global commands are valid virtually anywhere. They affect the game or your turn at whole, not only one particular object.

  AddCommand command

This creates a command to be sent to the host. The commands are mainly for PHost's command processor. Note that there currently is no way to examine or delete such commands from a script.

The following PHost commands are supported by PCC; for a detailed description, see the PHost docs. PCC should accept all abbreviations also accepted by PHost (i.e. `re c 7' instead of `remote control 7'). PCC will expand the command when sending it, expanding at least the command verb.

The following commands are also accepted, these are handled by PCC:

PCC knows when two commands affect the same thing, and lets the new command override the previous one. For example, "allies add 5" will override a previous "allies drop 5".

  AddConfig line

line is a configuration assignment as it could appear in PCONFIG.SRC. This command will process the line, and update the configuration accordingly.

For example,

  AddConfig "EngineShieldBonusRate = 0"

will disable the engine-shield bonus. After that command,

  Cfg("EngineShieldBonusRate")

will return 0.

When you're using Host, you can only assign to Host options; PHost settings will be rejected. When you modify a Host setting, PCC will write out the modified HCONFIG.HST file when it exits (and you allowed that in the setup). PCC will not update PCONFIG.SRC.

You can only modify complete options, there's no way to modify just one slot of an array option.

With PHost, some host settings can be modified by players by sending a command message (for example, the language). Use `AddCommand' to send these messages.

This function is for people who know what they're doing. Changing the configuration will not immediately update the screen. Some settings known to cause trouble, in increasing order of severity:

• ColonistTaxRate and friends: you may have to hit [Ctrl-G] (or call `UI.Update') to update the predictions on control screens;
• CPEnableRemote, CPEnableGive: you may have to exit and re-enter the control screen to add/remove the respective buttons;
• PlayerRace, StarbaseCost, etc.: don't even think about modifying that in mid-game;

  AddFCode line

line is a text line as it could appear in fcodes.usr (not empty, and not a comment of course). This function will add that line to the list of special friendly codes.

For example,

  AddFCode "cln,s-57,Clone this ship"

will define the "cln" friendly code (this definition already appears in the default fcodes.cc).

Note: in PCC 1.x, this function currently always adds the new code at the end, and it does not reject duplicates.

  AddNotify string

Adds a notification message, to inform the player of an event. These messages are displayed in the notification message window. The text will be word-wrapped to fit in the window; it can also contain carriage returns (Chr(13)) to force line breaks.

The message window will automatically include the name of the object the auto task belongs to, so the message need not repeat that. For example,

  AddNotify "out of fuel"

will generate the following message:

  (-s0124)<<< Notify >>>
  FROM: Auto Task Ship #124

  out of fuel

Messages sent using `AddNotify' will only be visible for the PCC session in which the command was used. Unlike `Notify', execution of the script will automatically continue after the command, the message needs not be confirmed by the user.

  AuthPlayer player, password

Authenticate a player to PCC (sounds cool, eh?). When a player has been correctly authenticated, PCC will not ask you for his password. Normally, PCC will ask you for the password when you load his data for the first time. It is not an error when the password is wrong; in this case, the command will simply not do anything.

For example, when you're playing the Feds, and also have the Lizard RST, you could put the following in your gameinit.q:

 On BeforeLoad Do AuthPlayer 1, "kirk"     % the Fed password
 On BeforeLoad Do AuthPlayer 2, "gorn"     % the Lizard password

This will let you open the Fed/Lizard RSTs without being prompted for passwords. Authentication information is forgotten whenever you leave the race screen, so you should regenerate it in the BeforeLoad hook.

In contrast to the "/p" command line option, this command allows you to specify passwords for multiple players.

 ChangeFleetLeader fleet-id, ship-id

Makes the ship ship-id the leader of the specified fleet. The ship should already be a member of the fleet.

This is a library routine.

  With Listbox(title, current, wi, he, help) Do
    AddItem id, text
    Run
  EndWith

This command sequence creates a standard list box. It consists of three parts:

• the "With Listbox()" part creates a blank, still invisible list box template;
• the "AddItem" part adds items to the list box. You can use any number of these. Items are identified by their id value which is an integer between 0 and 2^31-1 (PCC 1.1.6 and below accept only values up to 32767);
• the "Run" part finally displays the list box and lets the user choose from it. You can repeat "Run" as often as you wish.

The parameters are as follows:

• title: a string that is displayed in the title bar of the list box. This is the only mandatory parameter for "Listbox()";
• current: the id value of the entry which will be selected by default when the list box opens. When there's no item with that identifier, the first one will be selected;
• wi: the width of the list box in pixels. Must be between 200 and 640, default is 300;
• he: the height of the list box in lines. Must be between 3 and 20, default is number of items in list box. Pass -1 here to choose that default;
• help: the help page number associated with this list box. See `UI.Help'.

The "Run" command actually displays the list box and lets the user choose from it. It sets the `UI.Result' variable to the identifier of the item chosen by the user, or to EMPTY if she canceled.

Example: this is a simplified version of the "Set Primary Enemy" command:

  Local i, UI.Result
  With Listbox("Primary Enemy", Enemy$, 260, 12, 10026) Do
    AddItem 0, "0 - none"
    For i:=1 To 11 Do AddItem i, Player(i).Race.Short
    Run
    SetEnemy UI.Result
  EndWith

Note: scripts can not suspend while a "With Listbox" block is active.

  LoadResource filename

Loads the resource file filename, as if it were listed in cc-res.cfg. The file name should be absolute: to do the equivalent of listing `cc256.res' in cc-res.cfg, you can do

  LoadResource System.RootDirectory & "cc256.res"

Use this command with care: it does not prevent you from loading a file twice. It does not fail when there is a problem with that file, in that case, it only adds a failure notice to the system information.

Because PCC caches resource contents, do the `LoadResource' command as early as possible. Otherwise, the value from the original resource file may stay around. One possible application is to load pictures special to a particular ship list from the `gameinit.q' of a game that uses that ship list:

  % plistgame/gameinit.q:
  LoadResource System.RootDirectory & "plist.res"

  MessageBox text
  MessageBox text, heading

Displays a standard message box containing the specified text, with the specified heading (or "Message" if not specified). Unlike most PCC message boxes (with red frames), messages from scripts will have a blue frame.

In text mode, this command has the same result as `Print heading, ": ", text'. Compare `UI.Message'.

  NewCircle x, y, radius, color, tag, expire
  NewLine x1, y1, x2, y2, color, tag, expire
  NewLineRaw x1, y1, x2, y2, color, tag, expire
  NewMarker x, y, type, color, text, tag, expire
  NewRectangle x1, y1, x2, y2, color, tag, expire
  NewRectangleRaw x1, y1, x2, y2, color, tag, expire

Creates a new paint object in the starcharts. The arguments have the following meanings:

• x, y etc.: coordinates;
• radius: radius in light years;
• type: marker type (shape). Ranges from 0 to 7, corresponding to the marker types shown on the type selection window, from left to right;
• color: color, 1 to 30, like in the color selection dialog from top-left to bottom-right. The color can also be 0 which makes the drawing invisible and inaccessible to the user (you'll likely want to make it visible again by giving it a different color later);
• tag: a value your program can later use to find this marker. Negative values are reserved for use by PCC, you can use any positive value (0..32767) of your choice;
• expire: date of expiration. Either -1 (never expires, this is what is used for user drawings), or a turn number. PCC expires drawings when it *loads* a game. So if you draw something with expire=0, it will be visible for the current session, once the game is loaded next time, it will be discarded. If you specify a turn number, the drawing expires after that turn.

The `NewRectangle' and `NewLine' commands also have a `Raw' counterpart. In a wrapped map, the normal commands draw the shortest possible line. For example, on a standard wrapped map (borders at 1000 and 3000),

 NewLine 1100,2000,2900,2000

will adjust the coordinates so that it draws only a 200 ly line just across the map seam. If you simply want to connect two objects at these places the most sensible way, this is what you want. The `Raw' forms will not modify the coordinates, and an appropriate `NewLineRaw' command would draw a line across the whole map (in PCC up to version 1.1.14, the non-raw commands do the same as the current raw commands; the latter were previously not supported.)

The color argument and all which follow are optional, they default to:

• color = 9 (Yellow)
• tag = 0
• expire = -1 (never)
• text = ""

If you're making markers which you need to find again later, I suggest setting tag to an atom, like in

  NewCircle x, y, 10, 9, Atom("My Circle")

This way, tag values will not collide with the tag values of others' scripts. In addition, users can see meaningful values for the tags on the Painting Tags window. Unlike other atoms, atoms attached to markers this way will survive exit and reload. That is, after exiting PCC, you'll have a circle with tag `Atom("My Circle")' attached, although the actual numeric value of the tag may differ. This only applies to PCC 1.1.6 and later; previous versions will lose all atoms on exit so the numeric values will become meaningless.

When you call these commands from inside a `ForEach Marker' loop, that loop will only iterate through the markers that were present when the loop started, not the new ones created with this command.

  Notify string, turn

Stop execution of an auto task script, and inform the player of an event. These messages are displayed in the notification message window, from which users can resume execution of an auto task, or stop it. The text will be word-wrapped to fit in the window; it can also contain carriage returns (Chr(13)) to force line breaks.

The message window will automatically include the name of the object the auto task belongs to, so the message need not repeat that. For example,

  Notify "out of fuel"

will generate the following message:

  (-s0124)<<< Notify >>>
  FROM: Auto Task Ship #124

  out of fuel

This is a library routine.

When the turn number is specified, the message will pop up in the specified turn (and execution of the calling script will suspend that long), otherwise it will be sent immediately.

A message sent using `Notify' will remain active until it is confirmed. If the player does not confirm a message during this PCC session, it will pop up again in the next session. Compare `AddNotify'.

  SaveGame

This command saves the current game to disk. For details, see the PCC help, page 10179. This command mainly exists to be bound to keys.

  SelectionExec expr
  SelectionExec layer := expr

expr is a set expression. This command does the same as the [C] command in the selection manager: it evaluates the set expression, and stores the result in the specified selection layer (or the current layer, if this part is left out).

For example,

  SelectionExec B := S(A)

marks all ships from layer A (and only those) in layer B.

  SelectionExec 0

unmarks all objects in the current layer (the set expression `0' denotes the empty set). This is identical to

  SelectionExec Current := 0

  SelectionLayer layer

Change to the specified selection layer. layer may be either a number (0..7) or a letter ('A'..'H').

This command is a wrapper for assignments to the global `Selection.Layer' property (note the dot); directly assigning to the variable is faster when possible.

This is a library routine.

  SelectionLoad #fd
  SelectionLoad #fd, flags

Load selections from the file opened on file number #fd. The flags can contain the following:

• "t": ignore timestamp in file. Normally, `SelectionLoad' refuses to load files with a wrong timestamp;
• "a": also accept files containing all selection layers. Normally, `SelectionLoad' only accepts files containing one layer, which is loaded into the current layer;
• "m": merge selections. By default, `SelectionLoad' replaces the current selection;
• "u": user interface mode. When this flag is set, `SelectionLoad' will behave exactly as the respective command on the selection manager. The "t" and "a" flags will be ignored; the user will decide whether to load the file or not;
• a number between 0 and 7: if the file contains only one selection layer, it will be loaded into that position.

When this command fails, it will leave the read pointer of the file untouched.

Example:

  Open System.GameDirectory & "tmp.sel" For Input As 1
  Try SelectionLoad 1, 7
  Close 1

loads the file "tmp.sel" which must contain one selection layer into slot 7 (layer H). It fails silently (due to the `Try') when the file contains multiple layers or is from an older turn.

This command will stop reading when it finds a line starting with a close brace ("}"). This allows it to embed selections inside other files.

  SelectionSave #fd
  SelectionSave #fd, flags

Saves the current selection into the file opened on file number #fd. The flags can contain the following:

• a number between 0 and 7: to save only the specified selection layer (see `Selection.Layer'). By default, saves all layers.
• "t": to create a "timeless" file. Normally, selection files will contain a timestamp, and you'll get a warning when you attempt to load a file from a different turn (because, for example, ownership of certain units may have changed). Timeless files can always be loaded without warning.

Example:

  Open System.GameDirectory & "tmp.sel" For Output As 1
  SelectionSave 1, Selection.Layer & "t"
  Close 1

Saves the current selection layer into a file "tmp.sel", as a timeless file.

See also: `Open', `SelectionLoad'

  UI.ChooseObject screen-id

Choose an object for the specified screen. Screen Ids are the same as for `UI.GotoScreen':

For example, `UI.ChooseObject 1' does the same as the [F1] key in most screens. When there is just one ship, no dialog is displayed.

The chosen object Id is returned in `UI.Result'; the result is EMPTY if the user canceled. This command does not work in text mode.

  UI.FileWindow title, wildcard, help-id

Opens the "select a file" dialog and lets the user choose a file. The title argument specifies what to show in the window title, the wildcard is a DOS wildcard which specifies the default filter. For example, to choose a log file, do

  UI.FileWindow "Choose Log File", "*.log"

The optional third argument specifies a help page to use, it defaults to the help page for the file window. See `UI.Help' for more information.

When the user hits "OK", this command returns the chosen file in `UI.Result'; when the user cancels, UI.Result is set to EMPTY. See also the introduction on the User Interface for details.

The file dialog uses the variable `UI.Directory' to store the current directory.

In text mode, this command gives a simple, no-frills input line (`UI.Input').

This command also accepts a fourth argument that deals with predefined file names; details are still undocumented at this place.

  UI.GotoChart x, y

Switches to the specified position in the starchart. If the coordinates are out of range, they are corrected. To switch to a the starcharts without affecting the current position, use `UI.GotoScreen 4'.

See also `UI.GotoScreen' for more information on switching screens.

  UI.GotoScreen screen-id
  UI.GotoScreen screen-id, object-id

Switches to the specified screen. If the <object-id> is present, also switches to the specified object in that screen. If that is not possible, does nothing.

Note that this command will have immediate effect. It will suspend your script temporarily, switch to the new screen, and resume.

See also: `UI.GotoChart'

  UI.Help help-id

Opens a help window and displays the specified page. Help page numbers are integers in the range 10000 to 19999. This command returns when the user exits the help window.

Example:

  UI.Help 11111

opens the help index. You can find out the <help-id>s by opening the desired page and hitting [G].

This command fails with an error when the help id is invalid, or when it is called in text mode.

  UI.Input prompt, title, length, flags, default

Displays a standard text input dialog. All but the first parameter are optional, and have the following meaning:

• prompt: the prompt to show in the dialog. Up to 31 characters;
• title: the window title. Defaults to the value of prompt. Up to 31 characters;
• length: maximum number of characters to accept. Integer between 1 and 255, defaults to 255;
• flags: some additional flags that affect the behaviour of this dialog (see below);
• default: initial contents of text input field.

The flags parameter is a string that can contain the following:

• "n": only accept numeric input (digits);
• "h": do not accept high-ASCII characters (umlauts, accents, etc.);
• "p": password input: display stars instead of actual input;
• "f": draw a frame around the input line;
• "g": ignored in PCC 1.x. In PCC 2, input lines with this option only accept characters from the game character set;
• a number: width of input line in pixels.

For example, "h450" gives an input line which is 450 pixels wide and does not accept high-ASCII input. If you only want to set the width, you can also pass an integer instead of a string.

The result is returned in `UI.Result': if the user hits [Enter], `UI.Result' contains the input. If the user hits [ESC], `UI.Result' will be EMPTY.

Example: this is the "rename ship" function [N] on the ship screen:

  UI.Input "Enter new name:", "Rename Starship #" & Id, 20, 320, Name
  SetName UI.Result

(SetName will not do anything when passed an EMPTY parameter).

In text mode, this command makes a simple input line using the prompt only. The text mode input line only accepts the most basic editing keys ([Backspace], [Ctrl-Y], [Enter], [ESC]).

  UI.InputFCode flags, default

This command prompts for a friendly code, using the standard friendly code input window.

The flags parameter is a string that can contain the following:

• "p": offer planet friendly codes for selection;
• "b": offer starbase friendly codes for selection;
• "s": offer ship friendly codes;
• "a": offer alchemy ship friendly codes;
• "c": offer capital ship friendly codes;
• a number: offer friendly codes available to the specified player. Defaults to the currently loaded player if omitted or zero.

You should specify at least one of "s", "b" and "p".

The optional default parameter specifies the current value of the friendly code. The code starts as empty if this argument is omitted.

The result will be stored in `UI.Result', as usual for user interface commands.

In text mode, this command yields a simple input line, approximately like this:

 UI.Input "Friendly Code", "", 3, "h", default

  UI.InputNumber title, min, max, current, help

This command prompts for a number, using the standard number input window.

The parameters are

• title: the title/prompt shown in the dialog;
• min,max: the acceptable range of numbers (defaults to 0..10000);
• current: the current value (defaults to 0);
• help: help page to associate with dialog.

Only the first parameter is mandatory.

The result will be returned in `UI.Result'. It will be an integer within the requested range, or EMPTY if the user canceled the dialog.

For example, to change a ship's warp factor, you could use

 UI.InputNumber "Warp", 0, 9, Speed$
 SetSpeed UI.Result

(Note that `SetSpeed' is implicitly ignored if its parameter is empty).

This command currently does not work in text mode.

  UI.ListShips x, y, flags, ok, heading

List all ships at position (x,y), using the visual scan window. The last three parameters are optional.

The flags parameter contains a list of flag letters:

• "f": allow the user to choose foreign ships. If this is not specified, the "OK" button will be disabled for foreign ships. This flag implies "A";
• "a": list all ships at the specified location. By default, only your ships are listed;
• "e": when there is only one matching ship, return it and do not display the dialog at all;
• "s": only show ships that we "safely" see, i.e. no guessed ships;
• a ship Id. That ship will not be listed.

The ok string specifies the name of the "OK" button, it defaults to "Go to". Likewise, the heading specifies the window title, it defaults to "Select Ship".

The chosen ship Id (or EMPTY if the user canceled) is returned in `UI.Result'. If no ship matches, a dialog is displayed and EMPTY is returned. This command can't be used in text mode.

For example, this command sequence sets a "Tow" mission:

  UI.ListShips Loc.X, Loc.Y, "fae" & Id, "Choose", "Tow Ship"
  If UI.Result Then SetMission 7, 0, UI.Result

This command is equivalent to the Ctrl-F1 key command (switch to ship):

  UI.ListShips UI.X, UI.Y, "e" & Id
  If UI.Result Then UI.GotoScreen 1, UI.Result

Note: due to PCC's simple-minded user-interface kernel, you might see display glitches when you call this from somewhere else then a control screen or the starmap.

  UI.Message text, heading, buttons

Displays a standard message box with the specified text and heading. The buttons parameter contains a list of buttons to display in the message box, a space-separated list of words. For example,

  UI.Message "Choose a color", "Question", "Red Green Blue"

will show three buttons labelled "Red", "Green" and "Blue". The buttons can be activated by hitting their first letter. In addition, the [Enter] key activates the first button, [ESC] activates the last one. There can be at most 10 buttons in a message box. Use short button names to prevent that text runs out of the buttons.

This command returns the index of the pressed button in `UI.Result'. For example, if the user chose `Red' above, `UI.Result' will have the value 1 afterwards.

In text mode, displays text and heading, and a list of first letters of the buttons, and waits for a matching keystroke.

The last two parameters are optional and default to "Message" and "OK". Unlike most PCC message boxes (with red frames), messages from scripts will have a blue frame.

This command differs from `MessageBox' in that it modifies `UI.Result', and waits for a keystroke in text mode.

  UI.PopupConsole

Opens the console. The script continues running there. If your script is doing interesting output to the console, you can call this function to ensure the user sees it, even if he bound it to a key.

  UI.Search query, flags

Temporarily suspends your script and opens the search function.

query is the search query. When this parameter is left out or an empty string, this just opens the search window as if the user had pressed [F7]. Normally, it will start by evaluating the query.

The optional flags parameter defines the type and scope of the query:

• "P": include planets in search;
• "S": include ships in search;
• "B": include starbases in search;
• "U": include UFOs in search;
• "O": include the other objects in search;
• "1": search for name or Id;
• "2": search for expression which is true (default);
• "3": search for expression which is false;
• "4": search for location.

Briefly, letters correspond to the checklist in the top-left of the search window, digits correspond to the selection list in the top-right. You can specify any number of letters but only one digit. By default, all objects are searched for an expression which is true.

The user can access the full flexibility of the search function. In particular, he can manipulate all of the universe using the global actions. In addition, if the user leaves the search function with "OK", PCC will switch to that control screen before your script resumes.

Examples:

  UI.Search Loc.X & "," & Loc.Y, "psbuo4"

is the same as [Ctrl-H]. Actually, that's how [Ctrl-H] is defined in PCC 1.1.2 and later.

  UI.Update
  UI.Update flag

Updates the user interface. That is, refreshes all the items that have changed so far. Normally, this only happens when your script terminates or a window is opened or closed.

For example, when you do

  For i:=1 To 9
    SetSpeed i
    UI.Update
  Next

you will see the warp factor going from one to nine. If you'd leave out the `UI.Update', you'll only see it jump from whatever-it-was-before to nine when this script terminates.

If the flag parameter is specified and True (non-zero), the whole screen is repainted, as if the user had hit [Ctrl-G].

In text mode, this command does nothing.

  WaitOneTurn

Suspends the script until the turn number changed, i.e., until we are in the next turn.

See `Stop' for restrictions on the use of `WaitOneTurn'. This is a library routine.