PCC2 Help

This is the PCC2 help in one big HTML file. This help is also available within the program, using Alt-H.

[Top]Introduction

[Top]Introduction

PCC includes a scripting language. The script interpreter understands a simple programming language remotely based upon newer BASIC dialects, and extended to be useful in a VGAP context.

The scripting language is used for...

The scripting language started out as a search/query language, and evolved into a simple interpreted language in PCC 1.x. In PCC2, the underlying technology changes a lot, but the language remains largely the same. However, some dirty corners have been cleaned up, making the language a little more logical and consistent.

This manual documents the PCC2 version of the language. However, I attempted to document where PCC2 and PCC 1.x differ; a version index is available.

Structure of this Manual

Everyone should read the Basic Concepts part. If you wish to use Search and Labels, you need to read just the Expressions part. If you wish to write scripts, you should also read the Statements part. The Reference parts contains many indexes for reference.

[Top]Basic Concepts

[Top]Names and Context

Names identify things. Many programming languages therefore call them identifiers. A name can contain letters, digits, and the special characters "." (dot), "$" (dollar), and "_" (underscore); it may not start with a digit or dot, and may not end with a dot, though. PCC predefines many names you can use in various ways. Those are called properties (properties of objects, such as the name of a ship) and functions. You can also define your own names: variables and subroutines.

The meaning of a name depends on the current context. For example, the word Mission can stand for the mission of a ship or for the mission of a starbase, which are governed by completely different rules. However, names have been chosen in such a way that similar things are represented by similar names. For example, you can use Name="Ares" to search for ships and planets having that name, and Owner$=7 searches for everything owned by player 7.

The current context is determined by the place you're invoking a script from. For example, a planet label expression is always evaluated in the context of the planet. A search expression is evaluated in all possible contexts, as defined by your selection in the search dialog.

Contexts stack. You can temporarily open another context to look at another object's properties. For example, using the Find function to find a ship, as in Find(Ship, Name="Ares", Id), will evaluate the test and return expressions (second and third parameter) in ship context. Likewise, the With command will execute commands in a specified context.

Contexts are not only established by objects. The "outermost" context always contains all global variables. Each executing function, subroutine or script will establish a context for its local variables. Every name is looked up in the innermost context first. If it is not found there, the outer contexts are considered until one provides a definition.

There are important exceptions to these rules. For example, in Sin(30), Sin always means the sine function, no matter what context is active. Those exceptions are:

Those always mean the same thing, regardless of the current context, and cannot be redefined.

Namespaces

In PCC2, all functions, subroutines, structures, and variables share a single namespace. That is, if you have a global variable A, you cannot have a function named A at the same time. (You can, however, have a local variable A, and that will "shadow" the global one due to the context stack.)

In contrast, in PCC 1.x, subroutines and variables had separate namespaces, so you could have a subroutines named the same as a variable. However, this is confusing and hard to use, so it should be avoided.

In both versions, the following have namespaces separate from variables and subroutines:

That is, defining a keymap ShipScreen will not interfere with a command, variable or hook named ShipScreen.

[Top]Naming Conventions

Property names follow some simple guidelines that aim to help you memorize properties.

The shortest name always gives a nice human-readable summary of an item. For example, Mission yields a ship's mission in text form ("Tow a ship"). By adding more words, you can ask for details. For example, Mission.Tow yields the "Tow" parameter of the mission. Alternatively, adding a dollar sign gives the internal representation. For example, Mission$ yields the mission number (7).

For programming, writing search queries, etc., you will probably use the "$" forms most often. For formatting text, you will most likely use the short standard form.

When you define your own names, it makes sense to give them a unique prefix to avoid clashes with others' names (in case you're using scripts developed by others).

Internally, PCC uses some names starting with CC$. Those names are undocumented and subject to change without notice. You should not use them. Currently, many keybindings are implemented using a CC$ name. If you want to modify such a keybinding, it's best to copy the existing one. For example, as of beta 9, the "change primary enemy" function (E on ship screen) is implemented as CC$ChangePE. To assign this function to the P key, you should write

 Bind Ship "p" := Key(Ship, "e")

instead of Bind Ship "p" := "CC$ChangePE". This is guaranteed to keep working in future versions.

[Top]Types

All names, values and expressions have a type. The type defines what you can do with the thing. PCC internally tracks these types. If you use a value in a way its type does not allow, PCC will show you an appropriate error message. Here are the most important data types:

Numbers
PCC supports fractional and whole numbers (integers). PCC internally tracks for each value whether it's fractional or integer. In general, operations between integers yield integers, whereas operations involving a fractional number yield a fractional number. Some operations require their operands to be integers, many accept either kind. For details, see Integers and Numbers.
Boolean (Truth Values)
Boolean values can be True or False and are used to represent yes/no answers, for example, the results of comparisons. Whenever PCC needs a boolean value, it also accepts numbers (0 means False (everything below 0.000001, actually), other values mean True) or strings (the empty string "" means False, other values mean True). Likewise, PCC also accepts booleans when it needs a number, False converts into zero, True converts into 1. For details, see Booleans.
Strings
Strings can contain arbitrary text, such as the name of a starship. For details, see Strings.
Arrays and Hashes
These contain other objects. For example, Ship is an array containing all ships. Arrays are indexed with numbers, hashes are indexed with strings. For details, see Arrays.
Functions
Functions compute values from other values. For example, Sqrt is a function, and Sqrt(9) computes square-root-of-9. You can also define your own functions using the Function command. For details, see Elementary Functions and Functions.
Objects
The result of an array reference like Ship(17) is the object, ship #17. You can access that object's properties by adding a dot followed by a property name, as in Ship(17).Name, or by using it with the With command.

For more details, see the Data Type index, which describes these types in all their variants along with cross-references.

A very special value is EMPTY. This value is used for unknown values. For example, when you don't own a ship, it will yield EMPTY for its Cargo.N (fuel amount). As a general rule, an operation will yield EMPTY if one of their operands are EMPTY, and a command will not do anything if a mandatory argument is EMPTY, but exceptions exist. In a boolean context (If), EMPTY counts as False.

Technically, subroutines and regular (=not elementary) commands are also represented as values. The only thing you can do with those, however, is invoke them in a command. You cannot use them meaningfully in expressions.

Note: Unlike PCC 1.x, PCC2 currently permits all sorts of interesting (and dangerous) things. For example, you can "assign" arrays, functions, and commands, as in Ship := Planet or NewLine := NewRectangle. This will, of course, break a lot of things. For example, when you do Ship := Planet, ships will no longer be accessible, and the expression Ship(3) will refer to planet #3. On the other hand, this can also be used for good, for example to pass a function name to another function ("function pointer" or "closure" as known from other programming languages). PCC2 doesn't yet block those things. See Experimental Features for details.

[Top]Accessing Files

Scripts can access files. File access works almost identical between PCC 1.x and PCC2, but many limits have been raised in PCC2.

Files must be opened using the Open command before you can work with them. When opening, you associate a file number with the file. The file number is an integer between 1 and 100 (1 and 20 in PCC 1.x). You can assign your own file number, or use the FreeFile() function to get an unused one (recommended!). When you're done with the file, you close it using the Close command. This makes the file number available for future re-use.

In all commands, the file number is, by convention, written with a leading #. This is optional for all file-related commands except for Print (which needs the # sign to know that this is a file number, not a value to print).

Text files can be accessed using the Input and Print commands. PCC2 will automatically convert them from the game character set. As an exception, if they start with a UTF-8 byte order mark, they will be read as UTF-8. PCC 1.x will access all files with the game character set.

Binary files can be accessed using the Get and Put commands. Those transfer data to and from a special data block object stored in a variable. You can dissect this data block using the GetWord() function and its relatives, and modify it using SetWord and relatives.

For example, a xyplan.dat file consists of records of 6 byte each. You could read those using a script like this:

 % Open the file
 Dim fd = FreeFile()
 Open "xyplan.dat" For Input As #fd

 % Read coordinates
 Dim i, block, x, y
 For i:=1 To 500 Do
   Get #fd, block, 6
   x := GetWord(block, 0)
   y := GetWord(block, 2)
   Print "Planet ", i, " is at ", x, ",", y
 Next

See Data Type Blob for details.

On File Names

PCC2 runs on operating systems that have different conventions how a file name looks like. If you wish to build a file name, you should therefore use the MakeFileName function; to split a file name into components, use GetFileName and GetDirectoryName.

In PCC 1.x, you could just concatenate a directory name such as System.GameDirectory and a file name. This does no longer work in PCC2!

Pitfalls

In PCC 1.x, a data block was just a string. In PCC2, it is a whole new data type which cannot be used with string manipulation functions (which was possible but deprecated in PCC 1.x).

File I/O is buffered. When you write something to a file, the change may not immediately show up on the disk. If you open the same file on another file number, that other file number will also not immediately see the changes. Changes will be written out when you call Close.

[Top]Expressions

[Top]Expressions

Expressions compute values. They do so by combining elementary values (literals, properties, variables) using operators and functions. The following sections describe expressions.

[Top]Expressions: Literals

You can directly specify numbers, strings, and boolean values. Values of other types must be created using functions.

Integers and Fractional Numbers can be specified as decimal numbers. The "." is used as the decimal point. A number is integer if it fits into a 32-bit integer number, otherwise it's treated as real. The number π=3.141592 (circumference/diameter ratio of a circle) can be specified as PI.

Strings can be specified in two ways:

Boolean values can be specified directly as True and False.

See also: Types, Type Index

[Top]Expressions: General Rules

Expressions combine values to compute new values using operators or functions.

Most of these operators and functions return EMPTY when one of their arguments is EMPTY. In PCC2, operations taking more than one argument usually evaluate them all (although not necessarily from left to right), even if the result would be known after evaluating only some. Exceptions are explicitly specified. This is a difference to PCC 1.x, which would sometimes stop evaluating early.

String operations are case-insensitive by default. That is, "A" compares equal to "a". To get case-sensitive operations, use the StrCase() function. Note that only the basic latin letters are treated case-insensitively; special characters such as "ä" or "д" are always handled case-sensitive.

Some operations taking numerical operands only work with integers. When doing arithmetic, PCC keeps track of which values are integers and which are fractions. Arithmetic operators and "+", "-", "*" yield integers when their operands are integers, others like "/" may generate fractions even when used on integers.

If you violate the rules, for example, by comparing a number and a string, or by using a fractional number where an integer is required, you will get an error. The Search function will treat these cases as a mismatch. Scripts will be aborted unless they catch the error with a Try statement.

[Top]Expressions: Operators

The following table shows all operators supported by PCC2. Operators have a certain precedence or binding strength, which determines which parts of the expression belong to that operator. For example, in 2 + 3 * 4, the precedence of * is higher than the precedence of +, so the multiplication is performed first. The addition then adds 2 and the result of 3 * 4. The table shows operators in increasing order of precedence, i.e. later operators are evaluated before those shown first.

(1) a; b Sequence: evaluate a, discard its result, then evaluate b. This is needed very rarely, but can be useful to perform an assignment before producing the actual value in a search expression, for example.
(2) a := b Assignment: evaluate b, and assign it to a. Returns b.
(3) Or b Logical Or: return True if either operand is True. If the result is known after evaluating a (i.e. a is True), does not evaluate b (short-circuit evaluation).
Xor b Logical Exclusive-Or: return True if one operand is True and one is False. If the result is known after evaluating a (i.e. a is EMPTY), does not evaluate b (short-circuit evaluation).
(4) And b Logical And: return False if either operand is False. If the result is known after evaluating a (i.e. a is False), does not evaluate b (short-circuit evaluation).
(5) Not a Logical Not: return True if operand is False, False if operand is True.
(6) a = b Comparison: return True if a is identical to b. Values must have comparable types; when you attempt to compare a number and a string, this will generate an error.
a <> b Comparison: return True if a is different from b. Note that values still must have comparable types.
a < b Comparison: return True if a is less than b.
a > b Comparison: return True if a is greater than b.
a <= b Comparison: return True if a less or equal to b.
a >= b Comparison: return True if a is greater or equal to b.
(7) a # b Concatenation: convert a and b to strings and concatenate them.
a & b Concatenation: convert a and b to strings and concatenate them. If either is EMPTY but the other is not, treat the EMPTY one as empty string.
(8) a + b Addition: add a and b, which may be numbers or strings.
a - b Subtraction: subtract b from a, which must both be numbers.
(9) a * b Multiplication: multiply a and b, which must both be numbers.
a / b Division: divide a by b, which must both be numbers.
a \ b Integer division: divide a by b, which must both be integers, and discard the remainder.
Mod b Integer remainder: divide a by b and return the remainder. Both operands must be integers.
(10) -a Negation: change sign of a, which must be a number.
+a Unary plus: do not change sign of a, which must be a number. Exists for symmetry with "-".
(11) a ^ b Power: compute a-to-the-bth. Both operands must be numbers.

Operands

Operands to operators are shown as "a" and "b" above. The following things are possible operands:

[Top]Expressions: Functions

A function invocation has the general form

 NameOfFunction(FirstParameter, SecondParameter, ...)

There are two kinds of functions, elementary functions and regular functions.

Elementary Functions

Elementary functions are built into the interpreter core. They perform elementary computations, much like built-in operators. An elementary function is recognized whenever its name appears followed by a "(" in an expression, even if there is a variable or property of the same name.

You cannot define own elementary functions. Some of these functions have a special syntax, that is, parameters that don't follow regular rules, are evaluated in a different order than for regular functions, or not at all.

See Elementary Functions for a list of elementary functions.

Regular Functions

Regular functions behave regularily: first, their parameters are evaluated, then, the function is invoked to produce a result.

PCC comes with many regular functions predefined. Those perform computations, or access object contexts. In PCC2, you can also define your own functions using the Function command (PCC 1.x does not allow user-defined functions). Those functions are available globally unless a local variable or property "shadows" them.

Some contexts provide object-specific functions which are documented as properties of the object, for example, the HasFunction ship property.

See Functions for a list of regular global functions, Contexts for a list of context functions.

[Top]Expressions: Formal Grammar

This formal grammar describes expressions. Terminal symbols are in quotes, or described in text. Nonterminals are underlined.

Whenever an expression is required, PCC accepts a sequence. The only exception is the Bind elementary command, which takes or-exprs (because it has assignments := as part of its syntax).

sequence:
    assignment
    sequence ";" assignment

assignment:
    or-expr
    assignment ":=" or-expr

or-expr:
    and-expr
    or-expr "Or" and-expr
    or-expr "Xor" and-expr

and-expr:
    not-expr
    and-expr "And" not-expr

not-expr:
    comparison
    "Not" not-expr

comparison:
    concat-expr
    comparison "=" concat-expr
    comparison "<" concat-expr
    comparison ">" concat-expr
    comparison "<=" concat-expr
    comparison ">=" concat-expr
    comparison "<>" concat-expr

concat-expr:
    add-expr
    concat-expr "#" add-expr
    concat-expr "&" add-expr

add-expr:
    mult-expr
    add-expr "+" mult-expr
    add-expr "-" mult-expr

mult-expr:
    neg-expr
    mult-expr "*" neg-expr
    mult-expr "/" neg-expr
    mult-expr "\" neg-expr
    mult-expr "Mod" neg-expr

neg-expr:
    pow-expr
    "-" neg-expr
    "+" neg-expr
    "Not" neg-expr          % Note 1

pow-expr:
    primary-expr
    primary-expr "^" neg-expr

primary-expr:
    "(" sequence ")"
    string-literal
    integer-literal
    float-literal
    "True"                  % Note 2
    "False"                 % Note 2
    "Pi"                    % Note 3
    identifier invocation*

invocation:
    "(" arguments ")"
    "." identifier          % Note 4
    "->" identifier         % Note 4

arguments:
    nothing
    sequence ("," sequence)*

identifier:
    sequence of letters, "$", "_", digits, ".",
      not starting with a digit or period
      not ending with a period

string-literal:
    "'" (any character except for "'")* "'"
    """ (any character except for """ and "\",
         or "\" followed by any character) """

integer-literal:
    digit digit*
      A value is an integer if it fits into 32 bits.
      Otherwise, it's float.

float-literal:
    integer-literal
    digit digit* "."
    digit* "." digit digit*

Notes:

[Top]Scripts

[Top]Scripts

A script or auto task is a list of Statements (also called Commands). Statements perform actions, or control execution of other statements.

[Top]Scripts: Statement Types

Elementary vs. Expression vs. Normal

Elementary Commands

PCC supports a number of Elementary Commands. Those statements often control execution of other statements, like the If conditional statements, or cause them to be executed repeatedly, like the For loop. Elementary Commands often have a special syntax, and special rules how to evaluate their parameters.

See Elementary Commands for a list of all Elementary Commands.

Expression Statement

An expression statement consists of an expression on a line by itself. The expression is evaluated and its result discarded. The expression therefore normally is an assignment operation, such as

 a := Ship(10).Loc.X

which is evaluated for its side-effect of changing the value of the variable a.

If the outermost operator is an equality comparison, as in

 a = Ship(10).Loc.X

PCC automatically converts that into an assignment, because treating it as a comparison and discarding the result would be pointless.

If the expression starts with a keyword that also is an Elementary Command, it is interpreted as that Elementary Command (this applies to Dim and If, which can be commands or function calls). If you really want it as an expression, wrap it into parentheses.

Regular Commands

A regular command has the form

 NameOfCommand FirstParameter, SecondParameter, ...

The parameters are evaluated and then passed to the command.

There are a number of Global Commands. You can add your own global commands by defining subroutines using the Sub command. Many contexts provide object-specific commands that manipulate that object.

Multi-line vs. Single-line

Most commands are single-line commands, i.e. occupy just one line. Such commands can be entered on the Console, for example.

Some Elementary Command are complex enough to need multiple lines. For example, an If/Then/Else statement might look like this:

 If Owner$=My.Race$ Then
   NewCircle Loc.X, Loc.Y, 10
 Else
   NewRectangle Loc.X-10, Loc.Y-10, Loc.X+10, Loc.Y+10
 EndIf

As a general rule, a command that starts as a single-line command cannot continue as a multi-line command. This is invalid:

 ForEach Ship Do If Owner$=My.Race$ Then
   Print Name
 EndIf

It must be written as

 ForEach Ship Do
   If Owner$=My.Race$ Then
     Print Name
   EndIf
 Next

Multi-line commands can only be used within scripts. You cannot define your own multi-line commands.

[Top]Scripts: Script Files

Scripts are files that contain commands. By convention, these scripts have the file extension .q. They are normal text files which you can create using any text editor, such as Notepad, Emacs, etc.

Scripts can contain single-line and multi-line commands.

Scripts can contain comments: everything after a percent sign is ignored by the interpreter (actually, the % sign can be used to terminate every statement or expression, but it only makes sense in scripts). Use comments to document your scripts, for example:

 % Suspend script for one turn.
 % Execution proceeds next turn (or later, when a turn is missed).
 Sub WaitOneTurn ()
   Local t = Turn          % Save turn number
   Do While t = Turn       % Wait until turn number changes
     Stop
   Loop
 EndSub

Script files must contain complete commands. A multi-line command that started in a file must end within the same file.

[Top]Scripts: Auto Tasks

Auto-tasks are a special kind of script which you can edit within PCC2 on the Task Screens.

An auto-task is a list of commands. Commands that can change control flow, such as If or ForEach, are not allowed. You can, however, define a subroutine and call that.

A special command is Restart. This command is supported in auto-tasks only, and cannot be used in normal scripts. It will cause the auto-task to restart from the beginning.

Note: Internally, an auto-task is a little more than just a script containing a list of commands. Auto-tasks provide automatic error handling. If an auto-task contains an error, it will be stopped with a notification, and you will be given the opportunity to fix it. A regular script will be terminated when it encounters an error.

[Top]Scripts: Processes

Normally, a script is started (with a keystroke or a command on the console), executes, and terminates. However, you can also define scripts that run for a longer time, Auto Tasks being the most prominent example. Such scripts will normally do something, wait for the next turn, the continue their operation, and so on.

Such an executing script or auto-task is called a process. If you execute the same script twice, that will be two processes.

Every process has its own set of static and local variables. Shared variables will be shared between all processes. Whereas there is no way that one process can access another process' static and local variables, shared variables can be changed while the process waits.

A process waits by executing the Stop command. When you exit PCC, all active processes will be saved to a file (vmX.cc in PCC 1.x, scriptX.cc in PCC2). When you start PCC again, that file will be loaded and all processes continued. They must now check whether they can continue, and execute another Stop if not.

PCC comes with a number of commands predefined that wait for certain conditions to happen, e.g. WaitOneTurn, MoveTo.

Limitations

Processes cannot suspend at every place. For example, if a process currently examining a drawing property calls WaitOneTurn, it will be terminated because PCC cannot uniquely identify a drawing and find it again next turn. In general, everything from your Result file that has an Id can be found again, everything else can not.

Suspending will save the processes' static and local variables. Shared variables will not be saved. You must make sure that the woken-up processes finds them in the state they expect. This also applies to subroutine and function definitions. If the script tries to call a subroutine next turn, you must make sure it is available (e.g. by defining it through your startup script.

Tips

Do not suspend from within functions. Functions can be executed, for example, from search queries, and you wouldn't want your search query to be delayed to next turn.

You can examine and manipulate running processes using the Process Manager.

[Top]Scripts: Startup

There are a few ways to have PCC2 execute your scripts automatically.

These scripts can contain your code. In particular, it makes sense to put the following things into your startup scripts:

If you have written a useful script, it may make sense to wrap it as a plugin.

In addition, you can load script files from the console by typing a command such as Load "/path/to/script.q", and you can execute subroutines by simply calling them from the console.

One big difference between PCC 1.x and PCC2 is that PCC2 has a game chooser that allows you to load multiple games in one session. This means that it is possible that PCC2 loads your autoexec.q file multiple times in one session, whereas PCC 1.x will only load it once.

[Top]Scripts: Plugins

Since 1.99.25, PCC2 supports plugins. Plugins are a standardized way to get scripts (and resources) into PCC2 without having to manually edit files as if it were 1992.

A plugin is defined by a *.c2p file. This file contains information about the plugin and links to the actual files that make up the plugin. It is a regular ".ini" file that supports the following keywords:

Order of Script/Resource/Exec is significant, i.e. an Exec command can rely on a previous Script to be loaded.

For installation, files from File/Script/Resource must reside in the same directory as the *.c2p file. When a file myplugin.c2p file is installed, it is copied into the directory ~/.pcc2/plugins/, and the referenced files are copied to ~/.pcc2/plugins/myplugin/ (different paths on Windows).

The name of the plugin definition file serves as the plugin identifier in technical contexts (scripts, command line) see System.Plugin.

The Script and Exec commands will be executed within the plugin's context, and have access to the plugin properties.

PlayVCR will only load Resource files.

When uninstalling or updating a plugin, PCC2 will unload resource files provided by the plugin, but it will not unload scripts.

Dependencies

PCC2 has a rudimentary dependency management system. Plugins can provide and require features. You cannot install a plugin if a dependency is missing, and you cannot remove a plugin if another one relies on it.

Each feature is a word optionally followed by a version number, for example, "Coyote" or "Acme 1.0". Case is not significant. A plugin that requires a particular version number will also accept higher version numbers.

Default features:

Zipped Plugins

For simplicity, PCC2 also allows compressing all files of a plugin (including the *.c2p file) into a single zip file. To identify these files as plugins, we use the file extension .c2z (but normal .zip is accepted as well). This is the standard way of distributing plugins over the web.

Unpackaged Plugins

The plugin installer and the c2plugin tool will also accept regular script (*.q) and resource (*.res) files for installation. They will then internally generate a plugin description. This is useful for testing.

When you're giving away a plugin, it is strongly recommended to add a *.c2p file, and ideally package it up as a *.c2z.

[Top]Index

[Top]Index

[Top]Appendix

[Top]Appendix

[Top]Changes between PCC 1.x and PCC2

This section contains known and intentional differences between the PCC 1.x and the PCC2 version of the scripting language. Often, new versions of PCC 1.x or PCC2 introduce new commands, functions or properties. Those are referenced in the Version Index.

Implementation Differences

The basic principle of the script interpreter differs completely between PCC 1.x and PCC2. Whereas PCC2 compiles a script into an internal representation before executing it (like most script interpreters do today), PCC 1.x interprets the script line-by-line. This allows PCC 1.x to execute scripts with much less memory than PCC2, which is an issue for a DOS application, but is no longer relevant today.

Other differences:

Unimplemented Features

[Top]Experimental Features

This section describes experimental features of the interpreter in PCC2. They may still change their behaviour or be removed completely. They are not generally intended for the casual user.

This section does not apply to PCC 1.x.

In this section, "subroutine" refers to a subroutine defined with Sub, or to a function defined with Function.

Subroutine and Object References

Normally, a subroutine or structure type is global: executing a Sub/Function/Struct statement makes the subroutine or type available to all other scripts in the system. Subroutines and types are defined in the same context as global variables (Dim Shared).

Because these things are normal objects, they can be assigned as usual:

 Sub Foo (x)
   Print x
 EndSub
 Dim Bar := Foo

This defines a subroutine Foo. A variable Bar is defined and set to Foo, making it an alternative way to refer to this subroutine. To call the subroutine, you could therefore use

 Foo "this"
 Bar "or this"

The same goes for arrays, objects, types, context references, etc.

 Dim a := Ship
 Dim b := a(1)
 Dim c := b->Name   % same as c := Ship(1).Name

This feature isn't widely advertised because it can easily lead to problems if used wrong:

Note that this only applies to regular subroutines and builtin commands. It does not apply to elementary commands. It is not possible to make a variable with an alternative name for, say, If, and it is not possible to make If mean anything else than the default meaning.

Local Subroutines

It is possible to define subroutines in local (subroutine scope) or static (script scope) context.

To enable the feature, use Option LocalSubs(1). Then, define subroutines using Local Sub.... For example,

 Option LocalSubs(1)
 Sub PrintSquare(n)
   Local Function MakeRow(n)
     Return String(n, "X")
   EndFunction
   Local i
   For i:=1 To n Do Print MakeRow(n)
 EndSub

In this example, the MakeRow function is only defined during the execution of the PrintSquare function. It is not available to any other function.

Be careful that some code will be executed outside the current function. For example,

 Sub Initialize
   Local Sub Callback    % wrong!
     Print "something"
   EndSub
   On Load Do Callback   % wrong!
 EndSub

will not work. When the On Load hook runs, Initialize will have finished executing, and Callback is no longer defined.

Local Types

Like subroutines, you can also define types locally.

To enable the feature, use Option LocalTypes(1). Then, define types using Local Struct....

For example:

 Option LocalTypes(1)
 Function MakePair(x,y)
   Local Struct Pair
     X, Y
   EndStruct
   Dim a As Pair
   a->X := x
   a->Y := y
   Return a
 EndFunction

Types are Functions

The documented way to define an instance of a type is Dim...As.

 Struct Coord
   X, Y
 EndStruct
 Dim pos As Coord

Defining such a structure actually just defines a constructor function named the same as the type. Thus, you can also create instances of a type by using a function call:

 Dim pos2 := Coord()
 pos := Coord()

The advantage of this notation is that you can use it everywhere, not just in Dim statements.

[Top]Rationale

This section explains the ideas behind the scripting language, and why things are as they are.

BASICoid syntax

The language syntax vaguely resembles BASIC.

In the beginning, there was the report and query language. Essentially, we have three major language families to choose from, and BASIC turns out to be the easiest one for a report and query language. Here's a sample expression:

 Owner=My.Race And Orbit.Enemy

In Pascal style, we'd need additional parentheses, and in C style, we'd have to use "strange" operators (remember our audience is not just programmers):

 (Owner=My.Race) And Orbit.Enemy
 Owner==My.Race && Owner.Enemy

All this completely neglects the underlying language's type system and naming rules. Here, BASIC wins again by being so un-standardized in that area that it doesn't hurt when we add a new dialect :-) Besides, I never claimed this to be BASIC.

However, since PCC2 does byte-compilation, it's now possible to add different front-ends with little effort.

Untypedness

The language is untyped, i.e. it does not require programmers to declare what types of values they want to store in variables.

Besides this being the de-facto standard in scripting languages, a 100% requirement for the language was to have the notion of an unknown value (EMPTY). So, even if we'd allow variables that always contain numbers, they'd have to be able to accept numbers-or-EMPTY. Allowing it to accept numbers-or-EMPTY-or-anything-else just makes not much of a difference.

Dynamic Scope

Dynamic scope means a name is looked up in its current execution context, and needn't be declared in the function it's used in.

This allows many useful features, such as searching for units owned by player 2 by using the expression Owner$=2, and have PCC automatically select ship, planet, or other context.

In PCC 1.x, dynamic scope is the only way to pass values back from a function, without completely reverting to global variables. This is required by things like UI.Input. Although PCC2 allows functions, it keeps this model of user-interface interaction.

[Top]Data Types

[Top]Index of Data Types

[Top]Data Type Any

Functions documented to accept or return Any accept more than one data type.

Commands and Functions taking Any as Parameter

Functions returning Any

Properties of type Any

[Top]Data Type Array

Arrays are created using the Dim command. When you call a Sub/Function taking a variable number of arguments, those are passed in as an array as well.

Version Differences: Arrays are supported since PCC2 1.99.12. They are not supported in PCC 1.x.

Built-in object collections such as Ship or Planet are technically not arrays, but mostly behave like arrays.

Commands and Functions taking Array as Parameter

[Top]Data Type Blob

Data blocks (blobs for short) are used for binary file I/O.

To read a file, you use Get to read a block of data, and then disassemble that block using functions GetByte, GetWord, GetLong and GetStr. To write into a binary file, you build the block using SetByte, SetWord, SetLong and SetStr, and then write it into the file using Put.

Version Differences: In PCC 1.x, blobs are actually strings and are limited to 255 bytes. PCC2 implements blobs as a separate data type, and has no size limit.

Commands and Functions taking Blob as Parameter

[Top]Data Type Bool

Boolean values are truth values that can be either True or False. To get a boolean value, you can use the keywords True and False. More often, you will create boolean values using comparisons or logical operations.

Whenever a boolean value is required, you can also use

Whenever a number is required, you can also use a boolean value. True converts into 1, False converts into 0.

Commands and Functions taking Bool as Parameter

Functions returning Bool

Properties of type Bool

[Top]Data Type Cargo

You often need to compute the total cost of something in minerals. Doing this mineral-by-mineral is cumbersome, that's why there are some functions to manipulate cargo sets. Cargo sets are nothing more than specially formatted strings.

For example, the price of a Mark 8 torpedo is 1 kt of Tritanium, Molybdenum and Duranium, and 54 megacredits. In PCC, this cost can be represented as "1tdm 54$". The price of 13 torpedoes is then easily computed using

 CMul("1tdm 54$", 13)

A cargo set consists of a sequence of numbers followed by units (cargo types). The following cargo types are defined:

n t d m The four standard minerals
$ Money (megacredits)
s Supplies
c Colonist clans
f Fighters
w Torpedoes

Like you see in the above example, you can attach multiple units to each number ("1tdm" is one kt Tritanium, one kt Duranium, and one kt Molybdenum). And, you can write multiple such blocks. Note that there must not be a space between the number and the units.

For compatibility with PHost, PCC also accepts PHost's notation where a single cargo type precedes the number. For example, the cost of a Mark 8 torpedo would be "T1 D1 M1 $54" in PHost format.

Commands and Functions taking Cargo as Parameter

Functions returning Cargo

Properties of type Cargo

[Top]Data Type Expr

Functions documented to accept a parameter of type Expr are special. They usually evaluate these expressions in a non-standard sequence. For example, If() will only evaluate the second or third argument, but never both. These special properties are only available for elementary functions and commands. You cannot write functions or subroutines that take Expr parameters.

Commands and Functions taking Expr as Parameter

[Top]Data Type File

Files are referenced by numbers in PCC. You normally use the FreeFile() function to obtain a currently-unused file number. (Alternatively, you can hard-code file numbers, but this is not recommended.)

By convention, file numbers are written with a leading hash sign:

 Dim fd = FreeFile()
 Open "test.txt" For Input As #fd

In most cases, however, it is clear from context that you mean a file number, so you can omit the hash sign. The only case where the hash sign is required is the Print function.

Version Differences: The number of allowed files differs between PCC versions. PCC2 allows file numbers from 1 to 100, PCC 1.x only allows 1..20. (If you use FreeFile to obtain file numbers, you will not notice this difference, except for being able to open more files.)

Commands and Functions taking File as Parameter

[Top]Data Type Hash

Hashes are unordered data stores indexed by a string. Normally, a hash is created using Dim:

 Dim h As Hash

It can then be used like this:

 h("key") := "value"
 Print h("key")

The key must always be a string. It is interpreted case-sensitively. Reading keys that have never been written returns EMPTY.

You can iterate through the content of a hash using ForEach:

 ForEach h Do Print Key, "=", Value

See Hash Element Properties for details.

Version Differences: Hashes are supported since PCC2 1.99.15. They are not supported in PCC 1.x.

Functions returning Hash

[Top]Data Type Hook

Commands documented to take a parameter of type Hook are special. In place of the hook parameter, you specify the name of a hook (not as a string!), for example,

 On Load Do MyAddon.Initialize

This special behaviour is only available for elementary functions and commands. You cannot write functions or subroutines that take Hook parameters.

PCC offers a set of predefined hooks that run when a particular event happens. These are documented in the group Hooks (and also listed below as "properties").

Commands and Functions taking Hook as Parameter

Properties of type Hook

[Top]Data Type Int

Most functions in PCC that operate on numbers do not care whether the numbers are integral or fractional; those are documented as taking a Num. However, some operations are only sensible on integers. Those are documented as taking type Int, and will refuse to work with fractional numbers. Bools automatically convert to integers, where True converts to 1, False to 0.

If you have a fractional number, you can use Int or Round to convert it to an integer.

In general, the result of an operation involving fractional numbers is again a fractional number, whereas the result of an operation involving integers can be an integer if possible.

PCC 1.x and PCC2 track a value's type very closely, thus 2.5*2 is a fractional number because it started out with one. PCC2 Web relaxes these rules a little, and looks at the actual values. In PCC2 Web, 2.5*2 is a valid integer.

Commands and Functions taking Int as Parameter

Functions returning Int

Properties of type Int

[Top]Data Type Keymap

Functions documented to take a parameter of type Keymap are special. In place of the keymap parameter, you specify the name of the keymap, as a symbol (not as a string!), for example,

 Key(Global, "Alt-X")

This special behaviour is only available for elementary functions and commands. You cannot write functions or subroutines that take Keymap parameters.

Keymaps have a separate namespace from variables, i.e. a keymap MyStuff and a variable MyStuff are not related in any way.

A keymap contains a set of keystrokes and commands active in a particular context. A keymap can have one or more parent keymaps that "extend" the keymap. A key is looked up first in the keymap itself. If it is not found there, it is searched for in the parents.

PCC predefines a set of keymaps. Those are listed below as "properties". You can define your own keymaps using CreateKeymap, manipulate them using Bind, and use them using UseKeymap.

Predefined keymaps are defined a little different between PCC 1.x and PCC2. The following overview applies to PCC2 and, where appropriate, also for 1.x.

Global (Base for all predefined keymaps)
Ship Whenever a ship is active.
Planet Whenever a planet is active.
Base Whenever a base is active.
Fleet Whenever a fleet is active.
ControlScreen(Global) Active on all control screens.
ShipScreen(Ship, ControlScreen) Active on ship screen.
PlanetScreen(Planet, ControlScreen) Active on planet screen.
BaseScreen(Base, ControlScreen) Active on base screen.
FleetScreen(Fleet, ControlScreen) Active on fleet screen.
HistoryScreen(ControlScreen) Active on ship history screen.
AutoTaskScreen(ControlScreen) Active on auto task screen.
Starchart(Global) Active on starchart.
ShipLock(Ship, Starchart) Active when a ship is selected in the starchart.
PlanetLock(Planet, Starchart) Active when a planet is selected in the starchart.
UnknownPlanetLock(PlanetLock) Active when an unknown planet is selected in the starchart.
BaseLock(Base, Starchart) Active when a base is selected in the starchart.
RaceScreen(Global) Active on race screen.

Commands and Functions taking Keymap as Parameter

Properties of type Keymap

[Top]Data Type Num

PCC supports integral and fractional numbers. They are entered like usual, for example

 1
 42
 17.4
 .99

Integral numbers have 32 bits, and a range of +/-2147483647.

Fractional numbers have 48 bits, with about 10 significant digits and a range of about +/- 10^39. This is the precision used in data files; internally, PCC2 uses 64 bit precision.

Most operations do not care whether their numeric parameters are integral or fractional. Bools automatically convert to numbers, where True converts to 1, False to 0.

Some operations require integer numbers; those are documented as taking parameter type Int.

Commands and Functions taking Num as Parameter

Functions returning Num

Properties of type Num

[Top]Data Type Obj

An object is something that has properties. PCC offers all game data in the form of objects. For example, there is an object for each ship, whose properties describe that ship's type, name, mission, and so on.

Accessing Objects

To access the built-in objects, you use the Context functions. For example,

 Ship(13)
 Beam(Ship(13).Beam$)

You can also create your own objects using the Struct and Dim commands.

 Struct Pair
   First, Second
 EndStruct
 Dim p As Pair        % p now is an object

Accessing Object Properties

There are several ways to access object properties.

Directly: write the object name, followed by a dot, and the property name.

 Print Ship(13).Name
 Print Beam(Ship(13).Beam$).Name

Because the dot can also be part of a name, this does not work when the object is just a name. p.First would be interpreted as a single variable, not as a property of p. Therefore, you can also use -> instead of the dot:

 Print p->First
 Print p->Second

Using With: You can use the With statement to temporarily bring object properties into scope:

 With Ship(13) Do
   Print Name        % prints the ship's name
 EndWith
 With p Do
   Print First       % prints p->First
 EndWith

Using ForEach: For context functions, you can use ForEach to iterate over all objects of that type.

 ForEach Ship Do
   Print Name        % print the names of all ships
 Next

Functions returning Obj

Properties of type Obj

[Top]Data Type RichText

Rich text is text with attributes, such as colors, font styles, etc. PCC2 uses rich text to build parts of the graphical interface.

Rich text is created and operated upon using functions. You cannot use standard operators such as "+" or "=" to work with rich text.

All functions that expect rich text also accept regular strings instead.

Version Differences: Rich Text is supported since PCC 1.99.21. It is not supported by PCC 1.x.

Commands and Functions taking RichText as Parameter

Functions returning RichText

[Top]Data Type Str

A string is a piece of text, a sequence of characters. Strings are specified by using single or double quotes:

 "one string"
 'another one'

Double-quoted strings allow using the "\" to insert special characters, single-quoted strings do not.

In PCC 1.x, strings are limited to 255 characters. PCC2 has no such limit.

In PCC2 since 1.1.12, strings store Unicode characters. In previous versions, strings hold the extended ASCII set used as the game character set. For external data, this restriction still holds; characters not in the game character set are removed because they cannot be stored.

Commands and Functions taking Str as Parameter

Functions returning Str

Properties of type Str

[Top]Version History

[Top]Index of Versions

This lists all versions where the interpreter or a related function changed. The PCC 1.x version notes have been copied from the PCC 1.x scripting manual. Note that not all PCC2 1.99.x versions implicitly support all features of the lower-numbered 1.x versions, i.e. there can be things an 1.x version can do that a 1.99.x version can not.

If a version is not listed here, it has no script-related changes to its predecessor.

[Top]Version PCC 0.98.3

First version with Search function.

Items introduced in this version:

[Top]Version PCC 0.98.5

Items introduced in this version:

[Top]Version PCC 0.99

First version with Print function.

Items introduced in this version:

[Top]Version PCC 0.99.2

Items introduced in this version:

[Top]Version PCC 0.99.6

Items introduced in this version:

[Top]Version PCC 0.99.7

Items introduced in this version:

[Top]Version PCC 1.0.4

Items introduced in this version:

[Top]Version PCC 1.0.5

First version that supports scripting, as one-line commands entered at the console.

Items introduced in this version:

[Top]Version PCC 1.0.6

Items introduced in this version:

[Top]Version PCC 1.0.7

Items introduced in this version:

[Top]Version PCC 1.0.8

Items introduced in this version:

[Top]Version PCC 1.0.9

Items introduced in this version:

[Top]Version PCC 1.0.10

Items introduced in this version:

[Top]Version PCC 1.0.11

Items introduced in this version:

[Top]Version PCC 1.0.12

Items introduced in this version:

[Top]Version PCC 1.0.13

Items introduced in this version:

[Top]Version PCC 1.0.14

Items introduced in this version:

[Top]Version PCC 1.0.15

Items introduced in this version:

[Top]Version PCC 1.0.16

Items introduced in this version:

[Top]Version PCC 1.0.17

Items introduced in this version:

[Top]Version PCC 1.0.18

Items introduced in this version:

[Top]Version PCC 1.0.19

Items introduced in this version:

[Top]Version PCC 1.1

Items introduced in this version:

[Top]Version PCC 1.1.1

Items introduced in this version:

[Top]Version PCC 1.1.2

Items introduced in this version:

[Top]Version PCC 1.1.3

Items introduced in this version:

[Top]Version PCC 1.1.4

Items introduced in this version:

[Top]Version PCC 1.1.5

Items introduced in this version:

[Top]Version PCC 1.1.10

Items introduced in this version:

[Top]Version PCC 1.1.11

Items introduced in this version:

[Top]Version PCC 1.1.13

Items introduced in this version:

[Top]Version PCC 1.1.15

Items introduced in this version:

[Top]Version PCC 1.1.16

Items introduced in this version:

[Top]Version PCC 1.1.17

Items introduced in this version:

[Top]Version PCC 1.1.19

Items introduced in this version:

[Top]Version PCC 1.1.20

Items introduced in this version:

[Top]Version PCC2 1.99.8

First version of PCC2 that can evaluate expressions, with Search, object labels, and console.

Items introduced in this version:

[Top]Version PCC2 1.99.9

First version of PCC2 that can execute commands.

Items introduced in this version:

[Top]Version PCC2 1.99.10

Items introduced in this version:

[Top]Version PCC2 1.99.12

Items introduced in this version:

[Top]Version PCC2 1.99.13

Items introduced in this version:

[Top]Version PCC2 1.99.15

Items introduced in this version:

[Top]Version PCC2 1.99.16

Items introduced in this version:

[Top]Version PCC2 1.99.17

Items introduced in this version:

[Top]Version PCC2 1.99.19

Items introduced in this version:

[Top]Version PCC2 1.99.20

Items introduced in this version:

[Top]Version PCC2 1.99.21

Items introduced in this version:

[Top]Version PCC2 1.99.22

Items introduced in this version:

[Top]Version PCC2 1.99.23

Items introduced in this version:

[Top]Version PCC2 1.99.25

This version introduces plugins and closes some gaps still remaining between PCC 1.x and PCC2.

Items introduced in this version:

[Top]Version PCC2 1.99.26

Items introduced in this version:

[Top]Version PCC2 2.0.2

Items introduced in this version:

[Top]Version PCC2 2.0.3

Items introduced in this version:

[Top]Version PCC2 2.0.4

Items introduced in this version:

[Top]Version PCC2 2.0.5

Items introduced in this version:

[Top]Groups

[Top]Index of Groups

[Top]Beam Property

This section describes all beam weapon properties. These can be accessed using Beam(id).FIELD, where the Id number is an integer between 1 and 10. The beam number is the position of the beam in the selection list. Beam$ in ship context yields a beam Id.

[Top]Combat Participant Property

This section describes all combat participant properties. Each unit taking part in a fight is described by one such object. It can be accessed using Unit(n) as a combat property.

For example, this code iterates through all fights, then through all units, and prints their names:

 ForEach Vcr Do ForEach Unit Do Print Name

Properties of the first and second combat participants are also accessible as Left.Xxx and Right.Xxx combat properties.

[Top]Combat Property

This section describes all combat (VCR) properties. These can be accessed using Vcr(n).FIELD, where the index n goes from 1 to My.VCRs. Alternatively, use ForEach to iterate through the array.

Classic combat in VGA Planets resolves combat in 1:1 pairs. Each combat recording therefore contains a fight between two units. Their properties are provided as Left.XXX and Right.XXX.

PCC2 also supports fleet combat, namely FLAK, which allows many more units in a single fight. Therefore, each fight also has a Unit property which is an array of individual combat participants. The total number of units in the fight is in the NumUnits property. For classic combat, this property is 2, allowing for Units(1) (corresponding to Left.XXX), and Units(2) (corresponding to Right.XXX). For fleet combat, there are more elements.

[Top]Context

Each expression is evaluated in a particular context which defines which properties are available. Using the context references, you can temporarily switch to a different context to access another object's properties. For example, Ship(2).Name yields the name of ship 2, regardless where you are.

If the argument to a context reference is out of range or EMPTY, the return value is EMPTY. Use this to your advantage.

In addition, context references are used with the With statement. There it is an error for a context reference to return EMPTY. Context references are also used with the ForEach statement. There, you do not specify an Id. Instead, the command iterates through all objects of that type. See Objects for details.

Version Differences: Since PCC 1.0.18, context references use singular words. The older plural words (Ships(id)) continue to be available in PCC 1.x, but are not available in PCC2. Use only the singular words. ForEach always used the singular words.

[Top]Drawing Command

The following commands can be used for drawings. To execute a drawing command, use the ForEach Marker statement.

See also NewMarker, NewLine etc. for commands to create drawings.

[Top]Drawing Property

You can iterate through markers and other drawings using the ForEach Marker statement. You can read their properties; certain properties can also be assigned-to.

Markers/drawings can be created using the PCC starchart, or with the NewMarker command and its relatives. If some property can't be changed the way you wish, simply delete the drawing and create it anew.

Scripts inside drawing context can't suspend (using Stop). Markers do not have a unique handle, so PCC would not know where to wake them up again.

[Top]Elementary Command

These commands are the core of the scripting system. They allow you structuring your programs, and interacting with the interpreter. Many of them have a special syntax.

Most of these commands have little or no knowledge of the Planet game, for commands to interact with your game, see Global Commands, Ship Commands, Planet Commands, and other sections.

The names of these commands are reserved. You cannot define own subroutines or variables named identical to elementary commands. A line starting with the name of an elementary command is always interpreted as that elementary command, even if there is an Elementary Function of the same name.

[Top]Elementary Function

These functions are the core of the scripting system. They perform elementary computations, much like built-in operators. Some of them have a special syntax.

Most of these functions have little or no knowledge of the Planet game, for commands to interact with your game, see Functions, Contexts, and other sections.

An elementary function is recognized whenever its name appears followed by a "(" in an expression, even if that name has been defined with a different meaning. Z(0) will always refer to the Z() function, even if there is a local variable Z.

[Top]Engine Property

This section describes all engine properties. These can be accessed using Engine(id).FIELD, where the Id number is an integer between 1 and 9. The engine number is the position of the engine in the selection list. Engine$ in ship context yields an engine Id.

[Top]File Property

File properties are accessible using the ForEach DirectoryEntry(dir) command.

[Top]Function

These functions are available globally.

Unlike Elementary Functions, they have a regular syntax:

 NameOfFunction(FirstParameter, SecondParameter, ...)

They will always evaluate all parameters, and then execute the function.

You can define your own functions using Function.

[Top]Global Command

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

Unlike Elementary Commands, they have a regular syntax:

 NameOfCommand FirstParameter, SecondParameter, ...

They will always evaluate all parameters, and then execute the command.

You can define your own commands using Sub.

[Top]Global Property

Global properties are available everywhere. They give information on the game as whole. Basically, there are four groups:

Many things are derived from your score, and will be wrong if the host uses a score blanker (a program which prevents that you see your enemy's score).

Global properties can optionally be prefixed with Global. when their name would otherwise be shadowed by another variable.

Also see Global Variables.

[Top]Global Variable

Global variables are available everywhere. Unlike Global Properties, these are true variables that behave nicely: you can change their values, and you can "localize" them (using Dim Local) so that commands or subroutines you call use the local version instead of the global one.

Global variables can optionally be prefixed with Global. when their name would otherwise be shadowed by another variable.

[Top]Hash Element Property

You can iterate through the elements of a Hash using ForEach:

 Dim hh As Hash
 % ...
 ForEach hh Do
   Print Key, " = ", Value
 Next

[Top]Hook

This section describes all predefined hooks. A hook is run when a specific event happens. You can register commands to be executed at that event using the On command.

Also see hook cross-reference.

[Top]Hull Property

This section describes all hull properties. These can be accessed using Hull(id).FIELD, where the hull Id is an integer between 1 and 105. Such hull Ids can be found in a ship's Hull$ property, or on the ship specification page (S on ship screen).

Some of these properties are also accessible in ship context.

[Top]Incoming Message Command

The following commands can be used for messages.

[Top]Incoming Message Property

You can iterate through your incoming messages using the ForEach InMsg statement, and read out their text.

Scripts inside message context can't suspend (using Stop). This interface is intended for reading out message texts only.

[Top]Internal

These are internal properties and commands. They are used by the interpreter, or for the implementation of various PCC functions. They are listed here for completeness; you should not use these in your own scripts.

[Top]Keymap

This section describes all predefined keymaps. A keymap is defined using CreateKeymap and can be manipulated using Bind.

Also see keymap cross-reference.

[Top]Listbox Command

These commands are used when building list boxes. See Listbox() for details.

[Top]Minefield Command

The following commands can be used for minefields.

[Top]Minefield Property

The following properties are available for searching and printing, and in scripts using the Minefield() function and the ForEach Minefield command.

PCC records minefield information, and keeps it during turns. Minefields you scanned once are managed by PCC even if you don't currently see them. The information you get here is approximated by PCC, by assuming the minefield was left there undisturbed, subject only to natural decay. The LastScan property can tell you how old the minefield is, decide for yourself if you want to trust it or not.

[Top]Planet Command

These commands are valid at planets and starbases, and can be used to manipulate these objects.

To execute a planet command, either call the script from an appropriate place (e.g., console called on planet screen), or use the With Planet(id) Do command.

[Top]Planet Property

This section describes all planet properties. These can be accessed using Planet(id).FIELD, using a ForEach loop, and with the search and print functions.

Many planet properties are only known for own planets. If not, they yield EMPTY, even if not explicitly stated here. Some properties are also known and remembered for planets you visit, scan or otherwise get information about.

Starbase properties are also accessible from planets and all yield EMPTY if there is no base.

Planet properties can be prefixed with Planet.. This makes it possible to refer to a planet property which is currently shadowed by an equally-named property of another object.

[Top]Player Property

The following properties are available during printing, when printing a "Scores" section. They describe the score record for each player.

They are also accessible using the Player() function. When no game is loaded, only the race names are known, all other properties yield EMPTY then.

[Top]Plugin Property

This section describes plugin properties. These can be accessed using System.Plugin(id).FIELD.

[Top]Ship Command

These commands are valid on starships, and can be used to give orders to them.

To execute a ship command, either call the script from an appropriate place (e.g., console called on ship screen), or use the With Ship(id) Do command.

[Top]Ship Property

This section describes all ship properties. These can be accessed using Ship(id).FIELD, using a ForEach loop, and with the search and print functions.

Many ship properties are only known for own ships. Some are also known for visual contacts, and only a few for non-visual contacts (you may get non-visual contacts if you receive DOS-style RST files). Ships whose position was guessed by PCC also count as non-visual contacts. Unknown values are EMPTY, even if not explicitly stated here.

Ship properties can be prefixed with Ship.. This makes it possible to refer to a ship property which is currently shadowed by an equally-named property of another object. For example, the following is a more complicated way to say CargoUpload "300n":

 With Planet(Orbit$) Do CargoTransfer Ship.Id, "300n"

Without the explicit Ship., this would pass a planet Id where CargoTransfer expects a ship Id, which makes no sense.

Some of the ship properties can be assigned. If that would violate any constraint of a fleet (i.e. you try to change the speed of an ordinary member), the assignment is silently ignored.

[Top]Storm Command

These commands are valid at ion storms.

To execute an ion storm command, use the With Storm(id) Do command.

[Top]Storm Property

Ion storm properties are available for searching and printing, using the ForEach Storm command, and the Storm(id).FIELD context.

If you're using the Windows TRN format, you usually see all current ion storms, otherwise you only see storms which are new or in your normal scanner range.

[Top]Torpedo Property

This section describes all torpedo system properties. These can be accessed using Torpedo(id).FIELD and Launcher(id).FIELD, where the Id number is an integer between 1 and 10. The torpedo number is the position of the beam in the selection list. Torp$ in ship context yields a torpedo Id.

Properties provided by Torpedo and Launcher are mostly identical and differ only in that the former gives mass and cost of a torpedo, whereas the latter gives mass and cost of a launcher.

[Top]Ufo Command

These commands are valid at Ufos.

To execute an Ufo command, use the With Ufo(id) Do command.

[Top]Ufo Property

Ufo properties are available for searching and printing, using the ForEach Ufo command, and the Ufo(id).FIELD context.

Ufos are provided by add-on programs and represent objects in space other than ships, planets, minefields, and ion storms. PCC collects and merges Ufo information from Winplan-style result files, and PHost's "General Object" and wormholes.

[Top]Alphabetical Index

[Top]Alphabetical Index

[Top]ATan (Elementary Function)

ATan(x:Num, [y:Num]):Num

Returns the arc-tangent of x resp. x/y. The angle is returned in degrees (not radians as many other programming languages), and is in the range [0,360).

A heading angle is computed as

   angle := ATan(Waypoint.DX, Waypoint.DY)

This form is better than

   angle := ATan(Waypoint.DX / Waypoint.DY)

because it gets the quadrant right, and does not divide by zero if Waypoint.DX is 0.

If any parameter is EMPTY, or if both parameters are 0, returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Elementary Functions

[Top]Abort (Elementary Command)

Abort [what:Str]

Abort script with an error. The result is the same as if you had an error in your script, e.g. a division by zero or use of an undefined variable.

If there is a surrounding Try block, execution will resume in its Else part (or after its EndTry if there is no Else). Otherwise, the script will stop, with the error message printed on the console.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]Abs (Elementary Function)

Abs(x:Num):Num

Returns the absolute value of its argument. If the argument is EMPTY, returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Elementary Functions

[Top]AddCommand (Global Command)

AddCommand cmd:Str

Add a command message. These commands are mostly for the PHost command processor. PCC knows how commands amend or replace each other, e.g.

 AddCommand "allies add 3"

will replace a previous "allies drop 3" command. TODO: document the commands

Since: PCC 1.1.4, PCC2 1.99.9

See also: Global Commands

[Top]AddConfig (Global Command)

AddConfig line:Str

Modify the game configuration (PConfig/HConfig). line is a configuration assignment as it could appear in pconfig.src. This command will process the line, and update the in-memory configuration accordingly (it will not update the configuration file!).

For example,

 AddConfig "EngineShieldBonusRate = 0"

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

 Cfg("EngineShieldBonusRate")

will return 0.

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

Since: PCC 1.1.4, PCC2 1.99.25

See also: Global Commands

[Top]AddFCode (Global Command)

AddFCode line:Str

Add a friendly code to the selection list. line is a text line as it could appear in fcodes.cc.

For example,

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

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

Version Differences: In PCC 1.x, this command always adds the new code at the end. In PCC2, the friendly code list is always sorted alphabetically.

Since: PCC 1.1.4, PCC2 1.99.25

See also: Global Commands

[Top]AddItem (Listbox Command)

AddItem id:Int, text:Str

Add an item to the list box. The item will be added at the end. The text is displayed on the listbox. The id will be used to select an item and report the user selection.

If the text contains a single tab character ("\t", Chr(9)), the list will use a two-column layout.

Since: PCC 1.1.1, PCC2 1.99.25

See also: Listbox(), Listbox Commands

[Top]AddNotify (Global Command)

AddNotify s:Str

Notify message. This command informs the player of an event using the message text s. 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 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.

Since: PCC 1.1.16, PCC2 1.99.16

See also: Notify, Global Commands

[Top]AfterExit (Hook)

 On AfterExit Do command

Commands registered for the AfterExit hook are run immediately after a the user has left a game and returned to the game/race selection screen.

Since: PCC 1.0.10, PCC2 1.99.25

See also: Hooks

[Top]Algorithm (Combat Property)

Algorithm:Str                              (read-only)

Name of VCR algorithm.

See also: Combat Properties

[Top]Asc (Elementary Function)

Asc(s:Str):Int

Returns the character code of the first character of the string given as parameter. If s is not a string, it is converted into one before being examined. If s is EMPTY or an empty string, returns EMPTY.

In PCC2 since 1.99.12, this function returns the Unicode value of the character, which can be an (almost) arbitrary non-negative integer. In previous versions, it returns the code in the extended ASCII set used as the game character set, which is in the range 0..255.

Since: PCC 0.98.5, PCC2 1.99.8

See also: Elementary Functions

[Top]Atom (Elementary Function)

Atom(s:Str):Int

Creates an atom from a string. An atom is a number that can be mapped back to the string using AtomStr(). Calling Atom() again with the same string will return the same value. However, the mapping is not necessarily identical in different sessions.

The empty string "" always maps to the atom 0. If the parameter is EMPTY, returns EMPTY.

Since: PCC 1.0.12, PCC2 1.99.8

See also: Elementary Functions

[Top]AtomStr (Elementary Function)

AtomStr(n:Int):Str

Returns the string associated with an atom. This is the same string that was passed to Atom() when it returned n.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 1.0.12, PCC2 1.99.8

See also: Elementary Functions

[Top]AuthPlayer (Global Command)

AuthPlayer player:Int, password:Str

Defines a player password. When you load the specified player's data, and the password matches, PCC2 will not ask for the password. It is not an error to specify the wrong password with this command.

This command can be placed in your autoexec.q file in your game directory. For example, when you're playing the Feds, you could put the following in the game's autoexec.q file:

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

This will let you open the Fed RST without being prompted for passwords on your computer (but everyone else on other computers without this script will still have to know it).

Passwords are forgotten whenever you leave the race screen, so you should regenerate it in the BeforeLoad hook.

Since: PCC 1.1.1, PCC2 1.99.25

See also: Global Commands

[Top]AutoBuild (Planet Command)

AutoBuild

Perform a standard auto-build operation.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Planet Commands

[Top]AutoTaskScreen (Keymap)

 Bind AutoTaskScreen key := command

Keys on this keymap are active on the auto task screens.

This keymap includes (derives from) ControlScreen.

Since: PCC 1.0.16, PCC2 1.99.9

See also: Keymaps

[Top]AutoTaxColonists (Planet Command)

AutoTaxColonists

Auto-tax for colonists.

Since: PCC2 1.99.15

See also: Planet Commands

[Top]AutoTaxNatives (Planet Command)

AutoTaxNatives

Auto-tax for natives.

Since: PCC2 1.99.15

See also: Planet Commands

[Top]Aux (Combat Participant Property, Ship Property)

Aux:Str                                    (read-only)

Secondary weapon type, full name. Either a torpedo system name, "Fighters", or EMPTY.

See also: Combat Participant Properties, Ship Properties

[Top]Aux$ (Combat Participant Property, Ship Property)

Aux$:Int                                   (read-only)

Type of secondary weapon.

See also: Combat Participant Properties, Ship Properties

[Top]Aux.Ammo (Combat Participant Property, Ship Property)

Aux.Ammo:Int                               (read-only)

Number of fighters/torpedoes.

See also: Combat Participant Properties, Ship Properties

[Top]Aux.Count (Combat Participant Property, Ship Property)

Aux.Count:Int                              (read-only)

Number of fighter bays/torpedo launchers.

See also: Combat Participant Properties, Ship Properties

[Top]Aux.Short (Combat Participant Property, Ship Property)

Aux.Short:Str                              (read-only)

Secondary weapon type, short name.

See also: Aux (Ship Property), Combat Participant Properties, Ship Properties

[Top]Base - Disambiguation

There are multiple items with this name:

[Top]Base (Keymap)

 Bind Base key := command

Keys on this keymap are active whenever focus is on a starbase.

Since: PCC2 1.99.9

See also: Keymaps

[Top]Base (Planet Property)

Base:Str                                   (read-only)

Starbase status, human-readable. One of

See also: Planet Properties

[Top]Base.Building (Planet Property)

Base.Building:Bool                         (read-only)

True if this planet is building a base.

See also: Planet Properties

[Top]Base.YesNo (Planet Property)

Base.YesNo:Bool                            (read-only)

True if this planet has a base.

See also: Planet Properties

[Top]BaseLock (Keymap)

 Bind BaseLock key := command

Keys on this keymap are active when a starbase is locked on the starchart. A starbase can be locked at using B from a planet.

This keymap includes (derives from) Starchart and Base.

Since: PCC2 1.99.9

See also: Keymaps

[Top]BaseScreen (Keymap)

 Bind BaseScreen key := command

Keys on this keymap are active on the base screen.

This keymap includes (derives from) ControlScreen and Base.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Keymaps

[Top]BaseTaskScreen (Keymap)

 Bind BaseTaskScreen key := command

Keys on this keymap are active on the starbase auto task screens.

This keymap includes (derives from) AutoTaskScreen.

Since: PCC2 1.99.16

See also: Keymaps

[Top]Bases (Player Property)

Bases:Int                                  (read-only)

Number of bases this player has, according to score.

See also: Player Properties

[Top]Beam - Disambiguation

There are multiple items with this name:

[Top]Beam (Combat Participant Property, Ship Property)

Beam:Str                                   (read-only)

Beam type, full name.

See also: Combat Participant Properties, Ship Properties

[Top]Beam (Context, Function)

Beam(id:Int):Obj

Access beam weapon properties. Use as

 ForEach Beam Do ...

or

 With Beam(n) Do ...

Version Differences: This function was available for use in With under the name Beams() since PCC 1.0.6. Do not use the name Beams in new code, it is not supported by PCC2; use Beam instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Beam Properties, Contexts, Functions

[Top]Beam$ (Combat Participant Property, Ship Property)

Beam$:Int                                  (read-only)

Beam type. 0 if none, EMPTY if not known.

See also: Combat Participant Properties, Ship Properties

[Top]Beam.Count (Combat Participant Property, Ship Property)

Beam.Count:Int                             (read-only)

Number of beams.

See also: Combat Participant Properties, Ship Properties

[Top]Beam.Max (Hull Property, Ship Property)

Beam.Max:Int                               (read-only)

Maximum number of beams on this ship.

See also: Hull Properties, Ship Properties

[Top]Beam.Short (Combat Participant Property, Ship Property)

Beam.Short:Str                             (read-only)

Beam type, short name.

See also: Combat Participant Properties, Ship Properties

[Top]BeforeLoad (Hook)

 On BeforeLoad Do command

Commands registered for the BeforeLoad hook are run just before game data is loaded.

Since: PCC 1.0.10, PCC2 1.99.25

See also: Hooks

[Top]Bind (Elementary Command)

Bind keymap:Keymap key:Str := action:Any...

Assign keys. This command arranges that action is invoked when the key is pressed while keymap is active. The key is a string specifying the key, the action is either a string containing a command, or a numeric atom (see Atom, Key).

For example,

  Bind PlanetScreen "a" := "AutoBuild"

makes the A key on the planet screen run the AutoBuild command. New key definitions override old definitions.

You can define multiple keys in the same keymap in one line, by simply writing multiple assignments separated by commas.

Keystrokes consist of zero or more modifiers (Ctrl-, Alt-, Shift-, Meta-, possibly abbreviated to C-, A-, etc.), followed by a key name. A key name is either an ASCII character, or a special key name: F1 to F15, Backspace/BS, Pause, Del, Down, End, ESC, Home, Ins, Left, Num5, PgDn, PgUp, Print, Ret/Enter, Right, Space/Spc, Tab, Up, or WheelUp/WheelDown for mouse wheel events. In addition, Quit means the "close-me" button on the window frame ([X]). The available combinations differ between PCC versions and operating systems.

To undefine a key, bind it to the empty string. Unlike object properties, keymaps do not survive PCC exiting and re-loading.

The commands you bind to keys can examine the UI.Prefix variable to find out the current prefix argument.

Unlike PCC 1.x, PCC2 is case-sensitive. When you bind Shift-A, you must actually type an upper-case A to trigger this function (i.e. press Shift-A). PCC 1.x didn't distinguish between upper and lower case for (latin) alphabetic keys. Otherwise, PCC2 ignores the Shift modifier for printable keys. Shift-4 generates a "$" sign, so you have to bind $, not Shift-4, if you want something to happen on Shift-4. When in doubt, use the keymap debugger.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Elementary Commands

[Top]BitAnd (Elementary Function)

BitAnd(n:Int...):Int

Returns the bitwise AND of all its parameters. All parameters must be integers; if one parameter is EMPTY, the result is EMPTY.

Version Differences: Whereas PCC2 allows any number of parameters, PCC 1.x has a limit of 6.

Since: PCC 1.1.17, PCC2 1.99.8

See also: Elementary Functions

[Top]BitNot (Elementary Function)

BitNot(n:Int):Int

Returns the bitwise negation of its parameter. If the parameter is EMPTY, the result is EMPTY.

Since: PCC 1.1.17, PCC2 1.99.8

See also: Elementary Functions

[Top]BitOr (Elementary Function)

BitOr(n:Int...):Int

Returns the bitwise OR of all its parameters. All parameters must be integers; if one parameter is EMPTY, the result is EMPTY.

Version Differences: Whereas PCC2 allows any number of parameters, PCC 1.x has a limit of 6.

Since: PCC 1.1.17, PCC2 1.99.8

See also: Elementary Functions

[Top]BitXor (Elementary Function)

BitXor(n:Int...):Int

Returns the bitwise XOR of all its parameters. All parameters must be integers; if one parameter is EMPTY, the result is EMPTY.

Version Differences: Whereas PCC2 allows any number of parameters, PCC 1.x has a limit of 6.

Since: PCC 1.1.17, PCC2 1.99.8

See also: Elementary Functions

[Top]Break (Elementary Command)

Break

Exit a loop. This command is valid within a Do, For, or ForEach loop. It cancels the current iteration and all iterations that would follow, and continues execution immediately after the Loop or Next keyword.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]Build (Planet Property)

Build:Str                                  (read-only)

Type of ship (hull name) to build on starbase. EMPTY if no base, or no ship being built.

See also: Name (Hull Property), Planet Properties

[Top]Build.Beam$ (Planet Property)

Build.Beam$:Int                            (read-only)

Beam type for ship to build on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Build.Beam.Count (Planet Property)

Build.Beam.Count:Int                       (read-only)

Number of beams for ship to build on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Build.Engine$ (Planet Property)

Build.Engine$:Int                          (read-only)

Number of engines for ship to build on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Build.Hull$ (Planet Property)

Build.Hull$:Int                            (read-only)

Type of ship (hull Id) to build on starbase. EMPTY if no base, or no ship being built.

See also: Planet Properties

[Top]Build.QPos (Planet Property)

Build.QPos:Int                             (read-only)

Position of starbase in build queue. EMPTY if no base, or position not known.

See also: Planet Properties

[Top]Build.Remainder (Global Variable)

Build.Remainder:Int                        (read/write)

Remaining amount after partial build. If an operation like BuildFactories cannot finish completely, because of lacking resources or room, it can be told to build as much as possible instead of failing using the "n" flag. In this case, it stores the amount of structures not built in this variable.

If a local variable Build.Remainder is visible, the result is stored in that instead of the global one. It is therefore a good idea to define a local variable to capture results without disturbing or being disturbed by other scripts.

See also: Global Variables

[Top]Build.Short (Planet Property)

Build.Short:Str                            (read-only)

Type of ship (short hull name) to build on starbase. EMPTY if no base, or no ship being built.

See also: Name.Short (Hull Property), Planet Properties

[Top]Build.Torp$ (Planet Property)

Build.Torp$:Int                            (read-only)

Torpedo type for ship to build on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Build.Torp.Count (Planet Property)

Build.Torp.Count:Int                       (read-only)

Number of torpedo tubes for ship to build on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Build.YesNo (Planet Property)

Build.YesNo:Bool                           (read-only)

Ship build flag. True if this base is building a ship. EMPTY if no base.

See also: Planet Properties

[Top]BuildBase (Planet Command)

BuildBase [flag:Bool]

Build a starbase. If the parameter is specified as True or not at all, builds the base. If the parameter is specified as False, cancels a previous build order.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Planet Commands

[Top]BuildBaseDefense (Planet Command)

BuildBaseDefense amount:Int, [flag:Str]

Build starbase defense. Build the the specified number of structures, or scraps them if amount is negative. Fails if you don't own the planet, don't have the required resources, or if the new amount of structures is not allowed by the rules.

If the flag is specified as "n", the command will not fail due to lacking resources. Instead, it will build as many structures as possible, and set the variable Build.Remainder to the amount not built.

Since: PCC 1.0.5, PCC2 1.99.9

See also: BuildBaseDefenseWait, Planet Commands

[Top]BuildBaseDefenseWait (Planet Command)

BuildBaseDefenseWait amount:Int

Build starbase defense, wait as necessary. If amount defense posts cannot be built immediately due to lacking resources or colonists, this command waits until they have been built.

Since: PCC 1.0.17, PCC2 1.99.10

See also: BuildBaseDefense, Stop, Planet Commands

[Top]BuildBeams (Planet Command)

BuildBeams type:Int, amount:Int, [flag:Str]

Build beam weapons.

Attempts to build amount beams of the given type. The amount can be negative to scrap beams. The tech levels is automatically raised as necessary. The flag can be "N" to permit partial builds. If not all of the requested amount can be built, the command will report the amount not built in the variable Build.Remainder instead of failing.

Since: PCC 1.1.16, PCC2 1.99.9

See also: Planet Commands

[Top]BuildDefense (Planet Command)

BuildDefense amount:Int, [flag:Str]

Build defense posts. Build the the specified number of structures, or scraps them if amount is negative. Fails if you don't own the planet, don't have the required resources, or if the new amount of structures is not allowed by the rules.

If the flag is specified as "n", the command will not fail due to lacking resources. Instead, it will build as many structures as possible, and set the variable Build.Remainder to the amount not built.

Since: PCC 1.0.5, PCC2 1.99.9

See also: BuildDefenseWait, Planet Commands

[Top]BuildDefenseWait (Planet Command)

BuildDefenseWait amount:Int

Build defense posts, wait as necessary. If amount defense posts cannot be built immediately due to lacking resources or colonists, this command waits until they have been built.

Since: PCC 1.0.17, PCC2 1.99.10

See also: BuildDefense, Stop, Planet Commands

[Top]BuildEngines (Planet Command)

BuildEngines type:Int, amount:Int, [flag:Str]

Build engines.

Attempts to build amount engines of the given type. The amount can be negative to scrap engines. The tech levels is automatically raised as necessary. The flag can be "N" to permit partial builds. If not all of the requested amount can be built, the command will report the amount not built in the variable Build.Remainder instead of failing.

Since: PCC 1.1.16, PCC2 1.99.9

See also: Planet Commands

[Top]BuildFactories (Planet Command)

BuildFactories amount:Int, [flag:Str]

Build factories. Build the the specified number of structures, or scraps them if amount is negative. Fails if you don't own the planet, don't have the required resources, or if the new amount of structures is not allowed by the rules.

If the flag is specified as "n", the command will not fail due to lacking resources. Instead, it will build as many structures as possible, and set the variable Build.Remainder to the amount not built.

Since: PCC 1.0.5, PCC2 1.99.9

See also: BuildFactoriesWait, Planet Commands

[Top]BuildFactoriesWait (Planet Command)

BuildFactoriesWait amount:Int

Build factories, wait as necessary. If amount factories cannot be built immediately due to lacking resources or colonists, this command waits until they have been built.

Since: PCC 1.0.17, PCC2 1.99.10

See also: BuildFactories, Stop, Planet Commands

[Top]BuildFighters (Planet Command)

BuildFighters amount:Int, [flagAndShipId:Any]

Build fighters.

Attempts to build amount fighters. The amount can be negative to scrap fighters. The flagAndShipId can be "N" to permit partial builds. If not all of the requested amount can be built, the command will report the amount not built in the variable Build.Remainder instead of failing.

flagAndShipId can also contain a ship Id, to place the newly-built fighters on that ship.

Since: PCC 1.1.5, PCC2 1.99.9

See also: Planet Commands

[Top]BuildHulls (Planet Command)

BuildHulls type:Int, amount:Int, [flag:Str]

Build starship hulls.

Attempts to build amount hulls of the given type. The amount can be negative to scrap hulls. The tech levels is automatically raised as necessary. The flag can be "N" to permit partial builds. If not all of the requested amount can be built, the command will report the amount not built in the variable Build.Remainder instead of failing.

The type is a hull Id. You can not build all hulls; the command will fail if you try to build one you cannot build.

Since: PCC 1.1.16, PCC2 1.99.9

See also: Planet Commands

[Top]BuildLaunchers (Planet Command)

BuildLaunchers type:Int, amount:Int, [flag:Str]

Build torpedo launchers.

Attempts to build amount torpedo launchers of the given type. The amount can be negative to scrap launchers. The tech levels is automatically raised as necessary. The flag can be "N" to permit partial builds. If not all of the requested amount can be built, the command will report the amount not built in the variable Build.Remainder instead of failing.

Since: PCC 1.1.16, PCC2 1.99.9

See also: Planet Commands

[Top]BuildMines (Planet Command)

BuildMines amount:Int, [flag:Str]

Build mineral mines. Build the the specified number of structures, or scraps them if amount is negative. Fails if you don't own the planet, don't have the required resources, or if the new amount of structures is not allowed by the rules.

If the flag is specified as "n", the command will not fail due to lacking resources. Instead, it will build as many structures as possible, and set the variable Build.Remainder to the amount not built.

Since: PCC 1.0.5, PCC2 1.99.9

See also: BuildMinesWait, Planet Commands

[Top]BuildMinesWait (Planet Command)

BuildMinesWait amount:Int

Build mines, wait as necessary. If amount mines cannot be built immediately due to lacking resources or colonists, this command waits until they have been built.

Since: PCC 1.0.17, PCC2 1.99.10

See also: BuildMines, Stop, Planet Commands

[Top]BuildShip (Planet Command)

BuildShip hull:Int, [engine:Int, beamtype:Int,
  beamcount:Int, torptype:Int, torpcount:Int]

Submit a starship build order. If hull is zero, cancels a pending order. Otherwise, builds a ship. In this case, engine must be specified, and the others should better be specified as well to avoid building a ship without weapons.

Required tech levels and parts are bought automatically.

Since: PCC 1.0.6, PCC2 1.99.16

See also: Planet Commands

[Top]BuildTorps (Planet Command)

BuildTorps type:Int, amount:Int, [flagAndShipId:Any]

Build torpedoes.

Attempts to build amount torpedoes of the given type. The amount can be negative to scrap torpedoes. The flagAndShipId can be "N" to permit partial builds. If not all of the requested amount can be built, the command will report the amount not built in the variable Build.Remainder instead of failing.

flagAndShipId can also contain a ship Id, to place the newly-built torpedoes on that ship.

Since: PCC 1.1.5, PCC2 1.99.9

See also: Planet Commands

[Top]CAdd (Function)

CAdd(a:Cargo...):Cargo

Add cargo sets. Returns a new cargo set containing the sum of all cargo sets given as parameter. Version Differences: PCC 1.x supports two to six arguments for this function, PCC2 supports any number from one up.

Since: PCC 1.0.10, PCC2 1.99.9

See also: CSub, Functions

[Top]CC$AutoExec (Internal)

CC$AutoExec cmd:Str

Execute auto task command. An auto task command foo is actually coded as CC$AutoExec "foo". This implements error handling.

See also: Internal

[Top]CC$AutoReCheck (Internal)

CC$AutoReCheck:void

Part of the implementation of Restart. A call of this routine is generated before the loop jump. This routine makes sure we do not enter infinite loops.

See also: Internal

[Top]CC$Get (Internal)

CC$Get(old:Blob, fd:File, length:Int):Blob

Backend to Get.

See also: Internal

[Top]CC$Input (Internal)

CC$Input(old:Str, fd:File, [flag:Bool]):Str

Backend to Input.

See also: Internal

[Top]CC$LibraryVersion (Internal)

CC$LibraryVersion:Str                      (read-only)

Version of the standard library (core.q).

See also: Internal

[Top]CC$Notify (Internal)

CC$Notify msg:Str, associateWithProcess:Bool

Back-end to Notify and AddNotify.

See also: Internal

[Top]CC$NotifyConfirmed (Internal)

CC$NotifyConfirmed():Bool

Part of the implementation of Notify. Returns true if there is a confirmed notification message for this process.

See also: Internal

[Top]CC$Open (Internal)

CC$Open(fd:File, name:Str, mode:Int):Any

Backend to Open.

See also: Internal

[Top]CC$Print (Internal)

CC$Print(fd:File, text:Str):Any

Backend to Print to a file.

See also: Internal

[Top]CC$Reset (Internal)

CC$Reset x:Int, y:Int

Reset location dialog.

See also: Internal

[Top]CC$SelectionExec (Internal)

CC$SelectionExec layer:Int, code:Str

Back-end to SelectionExec.

See also: Internal

[Top]CC$SetInt (Internal)

CC$SetInt(v:Blob, size:Int, pos:Int,
  value:Int...):Blob

Backend to SetByte, SetWord, SetLong.

See also: Internal

[Top]CC$SetStr (Internal)

CC$SetStr(v:Blob, pos:Int, size:Int, value:Str):Blob

Backend to SetStr.

See also: Internal

[Top]CC$UseKeymap (Internal)

CC$UseKeymap keymap:Str, prefix:Int

This is the backend to UseKeymap. It causes the next keystroke to be processed using the keymap, and gives it prefix as the prefix argument (UI.Prefix).

Since: PCC2 1.99.22

See also: Internal

[Top]CCompare (Function)

CCompare(a:Cargo, b:Cargo):Bool

Compare cargo sets. Returns true if a contains enough cargo to remove b. Supply sale is taken into account.

Since: PCC 1.0.10, PCC2 1.99.9

See also: CSub, Functions

[Top]CDiv (Function)

 CDiv(a:Cargo, n:Int):Cargo
 CDiv(a:Cargo, b:Cargo):Int

Divide cargo sets.

In the first form, tries to divide the cargo set a into n equal parts, and returns the size of one part, as a cargo set.

In the second form, tries to determine how many times b can be removed from a. Supply sale is taken into account.

Since: PCC 1.1.17, PCC2 1.99.9

See also: Functions

[Top]CExtract (Function)

CExtract(a:Cargo, ele:Str):Int

Extract cargo. a is a cargo set, ele is a cargo type (e.g. "n" for Neutronium). This function returns the amount of that cargo type in the cargo set. If multiple cargo types are given, their amounts are summed up, e.g.

 CExtract(e, "s$")

will report the total number of supplies and money in cargo set e.

Since: PCC 1.0.10, PCC2 1.99.9

See also: Functions

[Top]CMul (Function)

CMul(a:Cargo, n:Int):Cargo

Multiply cargo set. Returns a new cargo set containing n times a.

Since: PCC 1.0.10, PCC2 1.99.9

See also: Functions

[Top]CRemove (Function)

CRemove(a:Cargo, ele:Str):Cargo

Remove cargo. a is a cargo set, ele is a cargo type (e.g. "n" for Neutronium). This function returns a cargo set with all cargo of the specified type removed. ele can also contain multiple cargo types to remove.

Since: PCC 1.0.10, PCC2 1.99.9

See also: Functions

[Top]CSub (Function)

CSub(a:Cargo, b:Cargo...):Cargo

Subtract cargo sets. Removes b and all following sets from a, and returns the result. Supply sale is taken into account.

Since: PCC 1.0.10, PCC2 1.99.9

See also: CCompare, CAdd, Functions

[Top]Call (Elementary Command)

Call command args, ...

Invoke a command.

Normally, commands are invoked by listing their name and arguments, as in

  SetWaypoint 1000, 1020

However, this only works if the command is a single word. Invoking a command on another object requires With.

Using Call, you can invoke commands using an expression. This allows commands that are hard to express using With, for example

  % set towee's fcode to the same as ours
  Call Ship(Mission.Tow).SetFCode FCode

In addition, it can be a tiny bit more efficient in some cases.

Caveat Emptor: when interpreting the "command" expression, Call will consume the longest possible expression (greedy parsing). This means, Call Foo -1 will be interpreted as the call of a subtraction expression, which is meaningless, instead of as a call of Foo with parameter -1. In this case, add an additional comma to indicate where the "command" expression ends:

  Call Foo, -1

Since: PCC2 2.0.2

See also: Elementary Commands

[Top]Capabilities (Combat Property)

Capabilities:Int                           (read-only)

VCR feature identification value. Valid only for classic combat, EMPTY for others.

See also: Combat Properties

[Top]Cargo.Colonists (Ship Property)

Cargo.Colonists:Int                        (read-only)

Number of colonists aboard this ship.

See also: Ship Properties

[Top]Cargo.D (Ship Property)

Cargo.D:Int                                (read-only)

Duranium aboard this ship, kilotons.

See also: Ship Properties

[Top]Cargo.Free (Ship Property)

Cargo.Free:Int                             (read-only)

Free cargo room.

See also: Ship Properties

[Top]Cargo.M (Ship Property)

Cargo.M:Int                                (read-only)

Molybdenum aboard this ship, kilotons.

See also: Ship Properties

[Top]Cargo.Max (Hull Property, Ship Property)

Cargo.Max:Int                              (read-only)

Maximum cargo on this ship.

See also: Hull Properties, Ship Properties

[Top]Cargo.MaxFuel (Hull Property, Ship Property)

Cargo.MaxFuel:Int                          (read-only)

Maximum fuel on this ship.

See also: Hull Properties, Ship Properties

[Top]Cargo.Money (Ship Property)

Cargo.Money:Int                            (read-only)

Money aboard this ship.

See also: Ship Properties

[Top]Cargo.N (Ship Property)

Cargo.N:Int                                (read-only)

Neutronium aboard this ship, kilotons.

See also: Ship Properties

[Top]Cargo.Remainder (Global Variable)

Cargo.Remainder:Cargo                      (read/write)

Remaining cargo after partial operation. If an operations like CargoUnload cannot finish completely, because of lacking cargo or cargo room, it can be told to do as much as possible instead of failing using the "n" flag. In this case, it stores the amount of unprocessed cargo in this variable.

If a local variable Cargo.Remainder is visible, the result is stored in that instead of the global one. It is therefore a good idea to define a local variable to capture results without disturbing or being disturbed by other scripts.

See also: Global Variables

[Top]Cargo.Str (Ship Property)

Cargo.Str:Cargo                            (read-only)

Cargo aboard this ship. String containing amounts of minerals, supplies, colonists, cash, and torpedoes/fighters.

See also: Ship Properties

[Top]Cargo.Supplies (Ship Property)

Cargo.Supplies:Int                         (read-only)

Supplies aboard this ship, kilotons.

See also: Ship Properties

[Top]Cargo.T (Ship Property)

Cargo.T:Int                                (read-only)

Tritanium aboard this ship, kilotons.

See also: Ship Properties

[Top]CargoTransfer (Planet Command, Ship Command)

CargoTransfer amount:Cargo, target:Int, [flags:Any]

Transfers cargo to a ship. target specifies the target ship Id, cargo is the amount and type to transfer, as a cargo set. It may contain negative values to beam cargo back from the target if rules allow.

The optional third parameter, options, is a string containing some options:

For example,

 CargoTransfer 10, "300n"

transfers 300 kt Neutronium to ship 10. It will fail with an error if the current ship doesn't have that much, or there is not enough space in ship 10's fuel tank. If you use

 CargoTransfer 10, "300n", "n"

PCC will transfer as much as possible. Assuming that the current ship only has 20 kt fuel (and ship 10 has enough space), this will set Cargo.Remainder to "280N", because that's the amount that was not transferred. To test for a successful transfer, you can then use

 If Not Cargo.Remainder Then Print "Successful."

Though you seem to be able to call this command beam cargo off foreign ships, this can only be used to cancel pending transfer orders. That is, if ship 355 is a foreign one and ship 10 is yours: for

 With Ship(355) Do CargoTransfer 10, "10n"

to succeed, you must have transferred 10 kt Neutronium there using the ship/enemy-ship transporter, e.g. with the command

 With Ship(10) Do CargoTransfer 355, "10n"

The game rules do not allow asking foreign ships for stuff; the other ship must explicitly send it.

Since: PCC 1.0.10, PCC2 1.99.12

See also: CargoUnload, CargoUpload, CargoTransferWait, Planet Commands, Ship Commands

[Top]CargoTransferWait (Planet Command, Ship Command)

CargoTransferWait amount:Cargo, target:Int,
  [flags:Any]

Transfers cargo to a ship, wait until amount transferred. This command is similar to CargoTransfer, see there for details about its parameters. It will try to transfer cargo from this unit to ship sid. It will continue execution when all cargo has been transferred.

For example,

 CargoTransfer "200n", 42

will load 200 kt Neutronium onto ship 42. If the unit this command is invoked from has enough cargo, and the receiving ship has enough free room, the command will succeed immediately. Otherwise, the script will wait until cargo or free room becomes available, and continue until all cargo has been transferred.

Since: PCC 1.0.11, PCC2 1.99.21

See also: CargoUpload, CargoUploadWait, Planet Commands, Ship Commands

[Top]CargoUnload (Ship Command)

CargoUnload amount:Cargo, [flags:Str]

Unload cargo to planet (or jettison). cargo is the amount and type to transfer, as a cargo set.

The optional second parameter, options, is a string containing some options:

This command is equivalent to

 CargoUpload CMul(amount, -1), flags

Since: PCC 1.0.10, PCC2 1.99.12

See also: CargoUpload, CargoTransfer, Ship Commands

[Top]CargoUnloadAllShips (Planet Command, Ship Command)

CargoUnloadAllShips

Unload all ships at this location. Can be called from ship or planet.

Since: PCC2 1.99.16

See also: Planet Commands, Ship Commands

[Top]CargoUpload (Ship Command)

CargoUpload amount:Cargo, [flags:Str]

Load cargo from planet. amount is the amount and type to transfer, as a cargo set.

The optional second parameter, options, is a string containing some options:

Since: PCC 1.0.10, PCC2 1.99.12

See also: CargoUnload, CargoTransfer, CargoUploadWait, Ship Commands

[Top]CargoUploadWait (Ship Command)

CargoUploadWait amount:Cargo, [flags:Str]

Load cargo from planet, wait until amount loaded. This command is similar to CargoUpload, see there for details about its parameters. It will try to load cargo from the planet this ship is orbiting. It will continue execution when enough cargo has been loaded.

For example,

 CargoUpload "200n"

will load 200 kt Neutronium on this ship. If the planet has more than 200 kt Neutronium, they will be loaded immediately; if the planet has less, the ship will wait for newly-mined Neutronium, or Neutronium unloaded by ships, until 200 kt have been loaded. If this ship has not enough free cargo room, it will also wait until some becomes available.

Note that when you unload cargo from this ship while CargoUploadWait is active, that cargo will be uploaded again and count towards the limit. If the planet has 100 kt fuel while you try to load 200, everything will be uploaded. If you now unload these 100 kt again, CargoUploadWait will load them up again and finish successfully, as it now has loaded 200 kt total.

Since: PCC 1.0.11, PCC2 1.99.21

See also: CargoUpload, CargoTransferWait, Ship Commands

[Top]Case, EndSelect (Elementary Command)

This keyword is part of the Select command, see there.

See also: Elementary Commands

[Top]Cfg (Function)

Cfg(key:Str, [player:Int]):Any

Access host configuration. The first parameter is the name of a configuration option as used in pconfig.src, such as "AllowHiss" or "UnitsPerTorpRate". The function returns the value of this option, an integer or string.

If the option is an array option, the second parameter can be specified to determine which player's value to get. When the second parameter is not specified for an array option, the return value is the value for your race.

Version Differences: This function was available with a different, more complicated definition in PCC 0.98.5 up to 1.0.8, under the names Cfg and CfgL.

Version Differences: The detail behaviour for array options differs between versions. Since 2.0.7, the behaviour is as follows:

PCC 1.x behaves subtly different, which is often considered a bug.

Since: PCC 1.0.9, PCC2 1.99.8

See also: Functions

[Top]ChangeFleetLeader (Global Command)

ChangeFleetLeader fid:Int, sid:Int

Change fleet leader. fid is the fleet Id (and thus the Id of the fleet's leader). sid is the Id of the ship that will become the new leader of the fleet. That ship should already be a member of the fleet.

Since: PCC 1.0.14, PCC2 1.99.17

See also: Global Commands

[Top]Chart.SetView (Global Command)

Chart.SetView name:Str

Set current view in starchart. This determines the visible panels and active keymaps.

Since: PCC2 1.99.10

See also: Global Commands

[Top]Chart.X, Chart.Y (Global Property)

Chart.X:Int                                (read/write)
Chart.Y:Int                                (read/write)

Current position in the starchart.

Version Differences: PCC 1.x always used the "on the starchart" interpretation, i.e. these values give a starchart position that may not have anything to do with the current unit's position the user actually sees.

Since: PCC 1.0.16, PCC2 1.99.10

See also: UI.GotoChart, Global Properties

[Top]Chr, Chr$ (Elementary Function)

Chr(n:Int):Str
Chr$(n:Int):Str

Returns a character, given the character code. For example, Chr(65) returns "A", and Chr(8745) returns "∩".

In PCC2 since 1.99.12, this returns the string containing Unicode character n. In versions before 1.99.12, and in PCC 1.x, this function returns a character from the extended ASCII set used as game character set.

PCC2 supports the WGL4 character set for display and thus supports most European languages including Greek and Russian. You can place other characters in strings, but PCC2 will not be able to display them.

PCC 1.x's character repertoire depends on the font used; the default is codepage 437, but fonts in codepage 866 (cyrillic) exist in the CCFonts package.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.98.5, PCC2 1.99.8

See also: Elementary Functions

[Top]Class (Storm Property)

Class:Int                                  (read-only)

Ion storm's class.

See also: Storm Properties

[Top]Close (Global Command)

Close #fd:File

Close a file. If some data is still in the write buffer, it will be written to disk now. The file number will become available for re-use.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]Colonists (Planet Property)

Colonists:Int                              (read-only)

Colonist population, number of clans.

See also: Planet Properties

[Top]Colonists.Change (Planet Property)

Colonists.Change:Str                       (read-only)

Colonist happiness change, text.

See also: Planet Properties

[Top]Colonists.Change$ (Planet Property)

Colonists.Change$:Int                      (read-only)

Colonist happiness change, numeric value.

See also: Planet Properties

[Top]Colonists.Happy (Planet Property)

Colonists.Happy:Str                        (read-only)

Colonist happiness, text.

See also: Planet Properties

[Top]Colonists.Happy$ (Planet Property)

Colonists.Happy$:Int                       (read-only)

Colonist happiness, numeric value.

See also: Planet Properties

[Top]Colonists.Supported (Planet Property)

Colonists.Supported:Int                    (read-only)

Maximum colonist clans supported by planet's climate.

Since: PCC 1.1.16, PCC2 1.99.8

See also: Planet Properties

[Top]Colonists.Tax (Planet Property)

Colonists.Tax:Int                          (read/write)

Colonist tax.

See also: SetColonistTax (Planet Command), Planet Properties

[Top]Colonists.Tax.Income (Planet Property)

Colonists.Tax.Income:Int                   (read-only)

Tax income from colonists, megacredits.

Since: PCC2 1.99.15

See also: Planet Properties

[Top]Color - Disambiguation

There are multiple items with this name:

[Top]Color (Drawing Property)

Color:Int                                  (read/write)

Color of this drawing.

See also: SetColor (Drawing Command), NewLine, NewCircle, NewRectangle, NewMarker, Drawing Properties

[Top]Color (Ufo Property)

Color:Int                                  (read-only)

Ufo color. This color is compatible to the NewLine, NewMarker etc. commands.

See also: Color (Ufo Property), Ufo Properties

[Top]Color.EGA (Ufo Property)

Color.EGA:Int                              (read-only)

Ufo color code. This is the value reported by the host, as a value from the standard MS-DOS EGA palette.

See also: Color (Ufo Property), Ufo Properties

[Top]Comment - Disambiguation

There are multiple items with this name:

[Top]Comment (Planet Property, Ship Property)

Comment:Str                                (read/write)

User comment. This is the comment that can be edited with F9.

See also: Planet Properties, Ship Properties

[Top]Comment (Drawing Property)

Comment:Str                                (read/write)

Comment of this drawing. Displayed for markers.

See also: SetComment (Drawing Command), Drawing Properties

[Top]Config.BeamChargeRate (Combat Participant Property)

Config.BeamChargeRate:Int                  (read-only)

Beam charge rate boost. This value is generated only by NuHost. In particular, it is not used by PHost. It can be used for PHost in PCC2's simulator, where it scales up the effective BeamRechargeRate computed from PConfig.

Since: PCC2 1.99.23

See also: Combat Participant Properties

[Top]Config.BeamKillRate (Combat Participant Property)

Config.BeamKillRate:Int                    (read-only)

Beam kill rate for this unit (3 for Privateers, otherwise 1).

Since: PCC2 1.99.23

See also: Combat Participant Properties

[Top]Config.CrewDefenseRate (Combat Participant Property)

Config.CrewDefenseRate:Int                 (read-only)

Crew defense rate. This value is generated only by NuHost. In particular, it is not used by PHost. It can be used for PHost in PCC2's simulator, where it scales down the effective CrewKillScaling computed from PConfig (a CrewDefenseRate of 100 reduces the CrewKillScaling to 0).

Since: PCC2 1.99.23

See also: Combat Participant Properties

[Top]Config.TorpChargeRate (Combat Participant Property)

Config.TorpChargeRate:Int                  (read-only)

Torpedo charge rate boost. This value is generated only by NuHost. In particular, it is not used by PHost. It can be used for PHost in PCC2's simulator, where it scales up the effective TubeRechargeRate computed from PConfig.

Since: PCC2 1.99.23

See also: Combat Participant Properties

[Top]Config.TorpMissRate (Combat Participant Property)

Config.TorpMissRate:Int                    (read-only)

Torpedo miss rate. This value is generated only by NuHost. In particular, it is not used by PHost and has no relation to the TorpHitOdds PConfig option.

Since: PCC2 1.99.23

See also: Combat Participant Properties

[Top]Continue (Elementary Command)

Continue

Continue a loop. This command is valid within a Do, For, or ForEach loop. It cancels the current iteration and proceeds with the next one, if any.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]ControlScreen (Keymap)

 Bind ControlScreen key := command

Keys on this keymap are active on all control screens.

This keymap includes (derives from) Global.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Keymaps

[Top]Cos (Elementary Function)

Cos(x:Num):Num

Compute the cosine of an angle. The angle x is specified in degrees (not radians as many other programming languages). The result is a value between -1 and +1.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Sin, Tan, Elementary Functions

[Top]Cost.D (Beam Property, Engine Property, Hull Property, Torpedo Property)

Cost.D:Int                                 (read-only)

Duranium cost of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Cost.M (Beam Property, Engine Property, Hull Property, Torpedo Property)

Cost.M:Int                                 (read-only)

Molybdenum cost of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Cost.MC (Beam Property, Engine Property, Hull Property, Torpedo Property)

Cost.MC:Int                                (read-only)

Money cost of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Cost.Str (Beam Property, Engine Property, Hull Property, Torpedo Property)

Cost.Str:Cargo                             (read-only)

Cost of this component, as a string.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Cost.T (Beam Property, Engine Property, Hull Property, Torpedo Property)

Cost.T:Int                                 (read-only)

Tritanium cost of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Count (Elementary Function)

Count(a:Array, [q:Expr]):Int

Count number of objects in an array. a must be an array of objects (such as a builtin object array like Ship or Planet). The expression q is evaluated for each object, as if within a ForEach loop, and the object is counted if it returns true. If q is not specified, all objects are counted.

Since: PCC2 1.99.9

See also: Elementary Functions

[Top]CountPlanets (Elementary Function)

CountPlanets(q:Expr):Int

Count number of planets satisfying a condition. The expression q is evaluated for each planet, and the planet is counted if it returns true.

This function is (almost) equivalent to Count(Planet, q).

Since: PCC 1.0.11, PCC2 1.99.9

See also: Elementary Functions

[Top]CountShips (Elementary Function)

CountShips(q:Expr):Int

Count number of ships satisfying a condition. The expression q is evaluated for each ship, and the ship is counted if it returns true.

This function is (almost) equivalent to Count(Ship, q).

Since: PCC 1.0.11, PCC2 1.99.9

See also: Elementary Functions

[Top]CreateKeymap (Elementary Command)

CreateKeymap name(parent:Keymap...),...

Create a keymap. A keymap contains a set of keystrokes and commands active in a particular context. The name is an identifier that names the new keymap; this keymap must not yet exist. If desired, one or more parent keymaps can be specified in parentheses; if the keymap should not have a parent keymap, the parentheses can be omitted.

The keymap can later be filled with keys using the Bind command.

A key is looked up first in the keymap itself. If it is not found there, it is searched for in the parents.

Keymaps have a separate namespace from variables, i.e. a keymap MyStuff and a variable MyStuff are not related in any way.

See Keymaps for a list of all predefined keymaps and related information.

Version Differences: PCC 1.x allows at most one parent keymap; PCC2 allows multiple parents.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Bind, UseKeymap, Key, Elementary Commands

[Top]CreatePlanetProperty, CreateShipProperty (Elementary Command)

CreatePlanetProperty name,...
CreateShipProperty name,...

Create new property. Parameter to this command is a list of names for the new ship/planet properties.

The properties will start out EMPTY. For example, after

  CreatePlanetProperty happy.goal

all planets will have an empty property happy.goal. You can assign to it with

  Planet(19).happy.goal := 94
  % ... or ...
  With Planet(19) Do happy.goal := 94

If a property you create with either of these commands was already created, nothing happens.

Properties created with these commands "shadow" the normal built-in properties. That is, if you create a property with the same name as a built-in property, the built-in property will become inaccessible. Be careful.

Properties are saved in the starcharts file (chartX.cc). If the starcharts file contains an undeclared property with an interesting value (non-EMPTY), the property is automatically declared to avoid data loss. To get rid of a property forever, set all its values to EMPTY and do no longer declare it.

Since: PCC 1.0.8, PCC2 1.99.9

See also: Elementary Commands

[Top]Crew - Disambiguation

There are multiple items with this name:

[Top]Crew (Ship Property)

Crew:Int                                   (read-only)

Current crew size.

See also: Ship Properties

[Top]Crew (Combat Participant Property)

Crew:Int                                   (read-only)

Crew on this ship. EMPTY if this is a planet.

See also: Combat Participant Properties

[Top]Crew$ (Combat Participant Property)

Crew$:Int                                  (read-only)

Crew. This returns the raw, unfiltered value of the Crew field within the VCR data structure. This field normally has a meaning only for ships.

See also: Crew (Combat Participant Property), Combat Participant Properties

[Top]Crew.Normal (Hull Property, Ship Property)

Crew.Normal:Int                            (read-only)

Maximum crew on this ship.

See also: Hull Properties, Ship Properties

[Top]Damage - Disambiguation

There are multiple items with this name:

[Top]Damage (Planet Property)

Damage:Int                                 (read-only)

Starbase damage. EMPTY if no base.

See also: Planet Properties

[Top]Damage (Combat Participant Property, Ship Property)

Damage:Int                                 (read-only)

Damage level in percent.

See also: Combat Participant Properties, Ship Properties

[Top]Damage (Beam Property, Torpedo Property)

Damage:Int                                 (read-only)

Explosive power of this weapon.

See also: Beam Properties, Torpedo Properties

[Top]Defense (Planet Property)

Defense:Int                                (read-only)

Number of planetary defense posts.

See also: Planet Properties

[Top]Defense.Base (Planet Property)

Defense.Base:Int                           (read-only)

Starbase defense. EMPTY if no base.

See also: Planet Properties

[Top]Defense.Base.Max (Planet Property)

Defense.Base.Max:Int                       (read-only)

Maximum starbase defense allowed. EMPTY if no base.

Since: PCC 1.1.16, PCC2 1.99.8

See also: Planet Properties

[Top]Defense.Base.Want (Planet Property)

Defense.Base.Want:Int                      (read/write)

Auto-build goal for starbase defense.

See also: Planet Properties

[Top]Defense.Max (Planet Property)

Defense.Max:Int                            (read-only)

Maximum number of planetary defense posts.

See also: Planet Properties

[Top]Defense.Want (Planet Property)

Defense.Want:Int                           (read/write)

Auto-build goal for defense posts.

See also: Planet Properties

[Top]Delete - Disambiguation

There are multiple items with this name:

[Top]Delete (Drawing Command)

Delete

Delete this drawing.

Since: PCC 1.0.14, PCC2 1.99.20

See also: Drawing Commands

[Top]Delete (Minefield Command)

Delete

Deletes the current minefield. Like Del in the minefield window, this can be used to delete minefields which are known to be out-of-date:

 ForEach Minefield Do
   If Owner$=My.Race$ And Scanned<>3 Then Delete
 Next

deletes all your minefields which were not scanned this turn. If you're getting Winplan RSTs, you scan all your minefields each turn, so those you do not scan do no longer exist and will be deleted by the above command.

After this command, all properties of the current minefield will yield EMPTY.

Since: PCC 1.0.12, PCC2 1.99.17

See also: Minefield Commands

[Top]Density.D (Planet Property)

Density.D:Int                              (read-only)

Density of Duranium in planet core.

See also: Planet Properties

[Top]Density.M (Planet Property)

Density.M:Int                              (read-only)

Density of Molybdenum in planet core.

See also: Planet Properties

[Top]Density.N (Planet Property)

Density.N:Int                              (read-only)

Density of Neutronium in planet core.

See also: Planet Properties

[Top]Density.T (Planet Property)

Density.T:Int                              (read-only)

Density of Tritanium in planet core.

See also: Planet Properties

[Top]Description (Plugin Property)

Description:Str                            (read-only)

Description of the plugin. This can possibly be multiple paragraphs of text.

Since: PCC2 1.99.25

See also: Plugin Properties

[Top]Dim - Disambiguation

There are multiple items with this name:

[Top]Dim (Elementary Function)

Dim(a:Array, [d:Int]):Int

Get size of an array. Returns the number of elements in the d'th dimension of array a. d starts from 1, that is, for a two-dimensional array, you can pass 1 or 2 here.

The return value is the number of elements in the array's dimension. The highest possible index into the array is one less than the value returned.

For example,

  Dim a(10)
  Print Dim(a)                  % returns 10
  Print Dim(a,1)                % also returns 10
  For i:=0 To Dim(a)-1 Do ...   % iterates

If any parameter is EMPTY, returns EMPTY.

Since 1.99.22, this function also works for builtin arrays such as Ship(). Note that builtin arrays often don't have a zero element (i.e. there is no Ship(0)). For iteration through ships, you would therefore use

 For i:=1 To Dim(Ships) Do ...

Better, however, is to use ForEach.

Since: PCC2 1.99.12

See also: IsArray (Elementary Function), Dim (Elementary Command), Elementary Functions

[Top]Dim (Elementary Command)

Dim [Local|Static|Shared] name [initializer],...

Create a variable.

You can create variables of different kind:

If you do specify a variable kind, you can omit the Dim keyword, i.e. Dim Static a is equivalent to Static a.

If the variable you create is indeed new, it will be initialized with the initializer (if no initializer is specified, it will start EMPTY). If the variable already exists, the initializer will be evaluated, but the variable keeps its original value.

The initializer can have the following forms:

name(expr, ...) An array of the specified dimensions, all values EMPTY.
name(expr, ...) As type An array of the specified dimensions, all values initialized with the specified type (see below).
name := expression Initialized with the specified expression.
name As type Initialized with the default value for the specified type.

The type can be a structure name defined with Struct to initialize the variable (or the array elements) with fresh instances of that structure, or one of the following:

Any Allow any type, initialize with EMPTY.
Double Fractional, initialize to 0.0.
Float Fractional, initialize to 0.0.
Hash Hash, initialize to a blank hash.
Integer Integer, initialize to 0.
Long Integer, initialize to 0.
Single Fractional, initialize to 0.0.
String String, initialize to "".

Examples:

  Dim a, b, c              % Three local variables
  Dim four = 4             % Local variable with value 4
  Dim i As Integer         % Local variable, integer
  Dim mat(10,10)           % 10x10 matrix (2-D array)
  Dim ps As MyStruct       % Structure
  Dim Shared gv            % Shared variable

Version Differences: PCC 1.x supports only simple value initialisations, and does not support arrays, hashes, or As initialisation.

Since: PCC 1.0.6, PCC2 1.99.8

See also: Dim (Elementary Function), Elementary Commands

[Top]Directory (Plugin Property)

Directory:Str                              (read-only)

Base directory of the plugin. This directory contains files installed with the plugin.

Since: PCC2 1.99.25

See also: Plugin Properties

[Top]DirectoryEntry (Function)

DirectoryEntry(n:Str):Obj

Access directory content. Use as

 ForEach DirectoryEntry(Name) Do ...

passing a directory name as Name.

This call will return all files and directories contained in the given directory, one per loop iteration, where you can access its properties. The files and directories are returned in an arbitrary order. The "." and ".." entries are not returned.

Since: PCC2 2.0.4

See also: File Properties, Functions

[Top]Distance (Function)

 Distance(x1:Int, y1:Int, x2:Int, y2:Int):Num
 Distance(x1:Int, y1:Int, obj2:Any):Num
 Distance(obj1:Any, x2:Int, y2:Int):Num
 Distance(obj1:Any, obj2:Any):Num

Compute distance between two points. Points can be specified as two integers for an X/Y coordinate pair, or an object which must have Loc.X and Loc.Y properties. Examples:

 Distance(1000, 1000, 1200, 1200)
 Distance(Ship(10), Planet(30))

If a wrapped map is being used, the map seam is also considered and the shortest possible distance is reported.

Since: PCC 1.0.11, PCC2 1.99.8

See also: Functions

[Top]Do (Elementary Command)

 Do [While c|Until c]
   statements
 Loop [While c|Until c]

Executes the statements in a loop. Loop conditions can be put at the top of the loop, or at the bottom, or even both. The top (Do) condition is checked before each iteration and determines whether the iteration begins. The bottom (Loop) condition is checked after each iteration and determines whether another iteration is tried.

The conditions (c) evaluate to bool. A While condition expects a True result to enter/continue the loop, a Until condition expects a False result.

If no condition is specified, the loop runs infinitely and can only be stopped with Break.

Since: PCC 1.0.6, PCC2 1.99.8

See also: Break, Continue, For, Elementary Commands

[Top]Else (Elementary Command)

This keyword is part of the If, and Try statements, see there.

See also: Elementary Commands

[Top]End (Elementary Command)

End

Terminate this script. This command normally makes no sense in regular code such as keybindings, but it may be useful in scripts intended to run stand-alone. To exit from a subroutine, use Return.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]End.X (Drawing Property)

End.X:Int                                  (read-only)

X location of endpoint. Valid for lines and rectangles, EMPTY for others.

See also: Drawing Properties

[Top]End.Y (Drawing Property)

End.Y:Int                                  (read-only)

Y location of endpoint. Valid for lines and rectangles, EMPTY for others.

See also: Drawing Properties

[Top]EndFunction (Elementary Command)

This keyword is part of the Function command, see there.

See also: Elementary Commands

[Top]EndIf (Elementary Command)

This keyword is part of the If statement, see there.

See also: Elementary Commands

[Top]EndStruct (Elementary Command)

This keyword is part of the Struct command, see there.

See also: Elementary Commands

[Top]EndSub (Elementary Command)

This keyword is part of the Sub command, see there.

See also: Elementary Commands

[Top]EndTry (Elementary Command)

This keyword is part of the Try command, see there.

See also: Elementary Commands

[Top]EndWith (Elementary Command)

This keyword is part of the With command, see there.

See also: Elementary Commands

[Top]Enemy (Ship Property)

Enemy:Str                                  (read-only)

Short name of this player.

See also: Ship Properties

[Top]Enemy$ (Ship Property)

Enemy$:Int                                 (read/write)

Primary Enemy. 0=none, or a player number.

See also: SetEnemy (Ship Command), Ship Properties

[Top]Enemy.Adj (Ship Property)

Enemy.Adj:Str                              (read-only)

Adjective name of this player.

See also: Ship Properties

[Top]Engine - Disambiguation

There are multiple items with this name:

[Top]Engine (Ship Property)

Engine:Str                                 (read-only)

Type of engine, full name.

See also: Ship Properties

[Top]Engine (Context, Function)

Engine(id:Int):Obj

Access engine properties. Use as

 ForEach Engine Do ...

or

 With Engine(n) Do ...

Version Differences: This function was available for use in With under the name Engines() since PCC 1.0.6. Do not use the name Engines in new code, it is not supported by PCC2; use Engine instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Engine Properties, Contexts, Functions

[Top]Engine$ (Ship Property)

Engine$:Int                                (read-only)

Type of engine.

See also: Ship Properties

[Top]Engine.Count (Hull Property, Ship Property)

Engine.Count:Int                           (read-only)

Number of engines.

See also: Hull Properties, Ship Properties

[Top]EnqueueShip (Planet Command)

EnqueueShip h:Int, e:Int, [bt:Int, bc:Int, tt:Int,
  tc:Int]

Build a ship. Parameters are the same as for BuildShip. Whereas BuildShip immediately replaces the build order, this command waits until the starbase is done building its current order. This command also waits until sufficient resources are available to place the order.

This command is intended to be used in auto tasks.

Since: PCC 1.0.6, PCC2 1.99.10

See also: BuildShip, Stop, Planet Commands

[Top]EnterDirectory (Hook)

 On EnterDirectory Do command

Commands registered for the EnterDirectory hook are run when a directory is entered, before game data is loaded, just before BeforeLoad.

Since: PCC2 1.99.9

See also: Hooks

[Top]Eval - Disambiguation

There are multiple items with this name:

[Top]Eval (Elementary Function)

Eval(s:Str):Any

Evaluate an expression given as string. For example, Eval("2+2") returns 4.

If the parameter is EMPTY, returns EMPTY.

Since: PCC2 1.99.9

See also: Eval (Elementary Command), Elementary Functions

[Top]Eval (Elementary Command)

Eval stmt:Str...

Evaluate a statement given as string. If multiple parameters are given, they are evaluated as a statement list or multiline command. A single line is evaluated as a single-line command.

Since: PCC 1.0.16, PCC2 1.99.9

See also: Elementary Commands

[Top]Exit (Hook)

 On Exit Do command

Commands registered for the Exit hook are run just before exiting a game. This is the right place to save state.

Since: PCC 1.0.9, PCC2 1.99.25

See also: Hooks

[Top]Exp (Elementary Function)

Exp(n:Num):Num

Exponential function. Computes e^n, where e is Euler's number. This is the inverse to the Log function.

If the parameter is EMPTY, returns EMPTY.

Since: PCC2 1.99.8

See also: Elementary Functions

[Top]Expire (Drawing Property)

Expire:Int                                 (read/write)

Expiration time.

See also: NewLine, NewCircle, NewMarker, NewRectangle, Drawing Properties

[Top]FCode - Disambiguation

There are multiple items with this name:

[Top]FCode (Planet Property)

FCode:Str                                  (read/write)

Friendly code.

See also: SetFCode (Planet Command), Planet Properties

[Top]FCode (Ship Property)

FCode:Str                                  (read/write)

Friendly code.

See also: SetFCode (Ship Command), Ship Properties

[Top]FPos (Function)

FPos(#fd:File):Int

Get current position within a file.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Seek, Functions

[Top]FSize (Function)

FSize(#fd:File):Int

Get size of the file, in bytes.

Since: PCC 1.0.13, PCC2 1.99.12

See also: FPos, Functions

[Top]Factories (Planet Property)

Factories:Int                              (read-only)

Number of factories on planet.

See also: Planet Properties

[Top]Factories.Max (Planet Property)

Factories.Max:Int                          (read-only)

Maximum number of factories on planet.

See also: Planet Properties

[Top]Factories.Want (Planet Property)

Factories.Want:Int                         (read/write)

Auto-build goal for factories.

See also: Planet Properties

[Top]Fighter.Bays - Disambiguation

There are multiple items with this name:

[Top]Fighter.Bays (Hull Property)

Fighter.Bays:Int                           (read-only)

Number of fighter bays on this ship.

See also: Hull Properties

[Top]Fighter.Bays (Combat Participant Property, Ship Property)

Fighter.Bays:Int                           (read-only)

Number of fighter bays.

See also: Combat Participant Properties, Ship Properties

[Top]Fighter.Count (Combat Participant Property, Ship Property)

Fighter.Count:Int                          (read-only)

Number of fighters.

See also: Combat Participant Properties, Ship Properties

[Top]Fighters (Planet Property)

Fighters:Int                               (read-only)

Number of fighters on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Fighters.Max (Planet Property)

Fighters.Max:Int                           (read-only)

Maximum number of fighters allowed on starbase. EMPTY if no base.

Since: PCC 1.1.16, PCC2 1.99.8

See also: Planet Properties

[Top]Find (Elementary Function)

Find(a:Array, q:Expr, v:Expr):Any

Find element in an array. a must be an array of objects (such as a builtin object array like Ship or Planet). The expression q is evaluated for each object, as if within a ForEach loop. If it returns true, the function returns v evaluated in that object's context. If no object matches, the return value is EMPTY.

Since: PCC2 1.99.9

See also: FindShip, FindPlanet, Elementary Functions

[Top]FindPlanet (Elementary Function)

FindPlanet(q:Expr):Int

Find planet. The expression q is evaluated for each planet, as if within a ForEach loop. If it returns true, the function returns that planet's Id. If no planet matches, the return value is EMPTY.

This function is (almost) equivalent to Find(Planet, q, Id).

Since: PCC 1.0.11, PCC2 1.99.9

See also: Find, Elementary Functions

[Top]FindShip (Elementary Function)

FindShip(q:Expr):Int

Find ship. The expression q is evaluated for each ship, as if within a ForEach loop. If it returns true, the function returns that ship's Id. If no ship matches, the return value is EMPTY.

This function is (almost) equivalent to Find(Ship, q, Id).

Since: PCC 1.0.11, PCC2 1.99.9

See also: Find, Elementary Functions

[Top]FindShipCloningAt (Function)

FindShipCloningAt(pid:Int):Int

Find ship cloning at a planet. Returns the Id of the ship that is cloning at planet pid. If no ship is trying to clone, or cloning is forbidden, returns EMPTY.

Since: PCC2 1.99.10

See also: Functions

[Top]First (Elementary Function)

First(delim:Str, list:Str):Str

Split string, return first part.

Assuming that list is a string containing multiple fields, separated by delim, this function returns the first field. For example,

   First(",", "cln,-57,Clone a ship")

returns "cln". If the string does not contain the delimiter, it is returned as-is:

   First(",", "huh?")

returns "huh?".

Note that, by default, substring search is case-insensitive. Use StrCase to search case-sensitive.

If any parameter is EMPTY, this function returns EMPTY.

Since: PCC 1.0.17, PCC2 1.99.8

See also: Elementary Functions

[Top]FixShip - Disambiguation

There are multiple items with this name:

[Top]FixShip (Planet Command)

FixShip sid:Int

Fix (repair) a ship. The sid is a ship Id, or 0 to cancel a pending shipyard order.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Planet Commands

[Top]FixShip (Ship Command)

FixShip

Repair this ship at the starbase. Changes the base's order to repair this ship.

Since: PCC 1.0.5, PCC2 1.99.9

See also: FixShip (Planet Command), Ship Commands

[Top]FixShipWait - Disambiguation

There are multiple items with this name:

[Top]FixShipWait (Ship Command)

FixShipWait

Fix ship at starbase when possible. Waits until the order can be submitted (i.e. the starbase's shipyard is idle), then gives the order.

Although documented as a Ship and Planet command, this actually is a global command. When calling it from a ship, do not specify a parameter. When calling it from a planet, specify a ship Id.

Since: PCC 1.0.16, PCC2 1.99.21

See also: FixShip (Ship Command), FixShip (Planet Command), Ship Commands

[Top]FixShipWait (Planet Command)

FixShipWait id:Int

Fix ship at starbase when possible. Waits until the order can be submitted (i.e. the starbase's shipyard is idle), then gives the order.

Although documented as a Ship and Planet command, this actually is a global command. When calling it from a ship, do not specify a parameter. When calling it from a planet, specify a ship Id.

Since: PCC 1.0.16, PCC2 1.99.21

See also: FixShip (Ship Command), FixShip (Planet Command), Planet Commands

[Top]Fleet - Disambiguation

There are multiple items with this name:

[Top]Fleet (Keymap)

 Bind Fleet key := command

Keys on this keymap are active whenever focus is on a fleet.

Since: PCC2 1.99.9

See also: Keymaps

[Top]Fleet (Ship Property)

Fleet:Str                                  (read-only)

Name of fleet this ship is in. If this ship is leader of a fleet, and the fleet has a name (Fleet.Name), returns that. Otherwise, returns the name (Name) of the leader. If the ship is not member of a fleet, this property is EMPTY.

See also: Ship Properties

[Top]Fleet$ (Ship Property)

Fleet$:Int                                 (read/write)

Id of fleet this ship is in.

See also: SetFleet (Ship Command), Ship Properties

[Top]Fleet.Name (Ship Property)

Fleet.Name:Str                             (read/write)

Name of fleet this ship is leader of. Has a value, and is assignable, only for ships that actually are fleet leaders (i.e. Fleet$ = Id$).

See also: Ship Properties

[Top]Fleet.Status (Ship Property)

Fleet.Status:Str                           (read-only)

Fleet status. One of

See also: Ship Properties

[Top]FleetScreen (Keymap)

 Bind FleetScreen key := command

Keys on this keymap are active on the fleet screen.

This keymap includes (derives from) ControlScreen and Fleet.

Since: PCC 1.0.14, PCC2 1.99.9

See also: Keymaps

[Top]For (Elementary Command)

 For var := start To end Do command

 For var := start To end [Do]
   commands
 Next

Counting loop. The variable var, which must have been declared before, starts at start and counts up in steps of 1 until it reaches end. For each value, the command (or command list) is executed.

For example,

 For i:=1 To 5 Do Print i

prints the numbers 1, 2, 3, 4 and 5.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Break, Continue, ForEach, Elementary Commands

[Top]ForEach (Elementary Command)

 ForEach set Do command

 ForEach set [Do]
   commands
 Next

Iteration over object array. The set is an array of objects, such as Ship or Planet. The loop will iterate through all objects in that set, and execute the command or command list for each of them.

For example,

 ForEach Minefield Do
   If LastScan < Turn-10 Then Delete
 Next

will delete all minefields not seen within the last 10 turns.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Break, Continue, For, Do, Count(), Find(), Elementary Commands

[Top]Format (Function)

Format(fmt:Str, args:Any...):Str

Format a string. The format string can contain placeholders, each of which is replaced by one of the arguments, similar to the sprintf function found in many programming languages.

Some placeholders:

You can specify a decimal number between the percent sign and the letter to format the result with at least that many places.

This function supports up to 10 arguments (plus the format string) in one call.

Since: PCC2 1.99.9

See also: RXml, Functions

[Top]FreeFile (Function)

FreeFile():Int

Get an unused file number. If there is no unused file number, fails with an error. Note that this function will always return the same value until you Open it (or Close another file). It is therefore normally used in the form

 Dim fd = FreeFile()
 Open "file" For Input As #fd
 Dim fd2 = FreeFile()
 Open "anotherfile" For Input As #fd2

Since: PCC 1.0.13, PCC2 1.99.12

See also: Functions

[Top]FuelFactor (Engine Property)

FuelFactor:Int()                           (read-only)

Array of fuel factors for warp factors from 0 to 9. This value is used in the computation of fuel usage.

See also: Engine Properties

[Top]FullText (Incoming Message Property)

FullText:Str                               (read-only)

Message text, in one big string.

See also: Incoming Message Properties

[Top]Function (Elementary Command)

 Function name(param, param, Optional param, rest())
   commands
 EndFunction

Define a function. The function can take parameters. The names of these parameters are specified in parentheses after the function name.

If one parameter is preceded by Optional, all parameters following it are optional and can be omitted by the caller. They will report EMPTY when read.

The last parameter can be followed by (). This allows the caller to specify any number of values (including none at all) for this parameter, which will be packed into an array (making this a "varargs function", for C programmers).

A function can be called from expressions, by writing its name followed by parameters in parentheses. It will be called when the expression is evaluated, and its Return value be inserted into the expression.

 Function twice(a)
   Return 2*a
 EndSub
 Print twice(17)      % prints 34

Note that if a function takes no parameters, an empty pair of parentheses must still be specified (func()) to call the function.

If there already is a subroutine or function with the same name as this function, it will be replaced by the new definition.

Since: PCC2 1.99.9

See also: Sub, Elementary Commands

[Top]Get (Global Command)

Get #f:File, var:Blob, length:Int

Read binary data. This command will read length bytes from the file, and place them in the data block var.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]GetByte (Function)

GetByte(v:Blob, pos:Int):Int

Extract byte. Returns the byte stored at position pos in the given data block.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Functions

[Top]GetDirectoryName (Function)

GetDirectoryName(n:Str):Str

Get directory name. The parameter is a full file name, possibly including a directory path. This function removes the final file name component and returns just the directories.

Since: PCC 1.1.20, PCC2 1.99.12

See also: Functions

[Top]GetFileName (Function)

GetFileName(n:Str):Str

Get file name. The parameter is a full file name, possibly including a directory path. This function removes all directory names, and returns just the file name.

Since: PCC 1.1.20, PCC2 1.99.12

See also: Functions

[Top]GetLockInfo (Function)

GetLockInfo(name:Str, [type:Int]):Any

Get lock information. Checks whether there is an active lock named name, and return information about it.

Since: PCC2 1.99.17

See also: Lock(), Functions

[Top]GetLong (Function)

GetLong(v:Blob, pos:Int):Int

Extract long. Returns the long (4 bytes, 32 bits) stored at position pos in the given data block.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Functions

[Top]GetStr (Function)

GetStr(v:Blob, pos:Int, length:Int):Str

Extract string. Returns the string that is stored at position pos in the data block in a field of size length. The string is converted from the game character set, and trailing space is removed.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Functions

[Top]GetWord (Function)

GetWord(v:Blob, pos:Int):Int

Extract word. Returns the word (2 bytes, 16 bits) stored at position pos in the given data block.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Functions

[Top]Global (Keymap)

 Bind Global key := command

Keys on this keymap are active at every place where PCC consults a keymap.

Since: PCC 1.0.19, PCC2 1.99.9

See also: Keymaps

[Top]Ground.D (Planet Property)

Ground.D:Int                               (read-only)

Amount of Duranium in ground, kilotons.

See also: Planet Properties

[Top]Ground.M (Planet Property)

Ground.M:Int                               (read-only)

Amount of Molybdenum in ground, kilotons.

See also: Planet Properties

[Top]Ground.N (Planet Property)

Ground.N:Int                               (read-only)

Amount of Neutronium in ground, kilotons.

See also: Planet Properties

[Top]Ground.T (Planet Property)

Ground.T:Int                               (read-only)

Amount of Tritanium in ground, kilotons.

See also: Planet Properties

[Top]Group (Incoming Message Property)

Group:Str                                  (read-only)

Group of this message. Similar messages are grouped using this string for the message list. The message filter also operates based on this string.

See also: Incoming Message Properties

[Top]HasFunction (Ship Property)

HasFunction:Bool()                         (read-only)

True if the ship has the specified hull function used as index. The index is either the name ("Gravitonic") or number (7) of the function, as it can be used in SHIPLIST.TXT.

This property considers all functions assigned to this ship type as well as to this individual ship, and honors level restrictions.

Since: PCC 1.1.15, PCC2 1.99.21

See also: Ship Properties

[Top]Heading - Disambiguation

There are multiple items with this name:

[Top]Heading (Storm Property)

Heading:Str                                (read-only)

Ion storm's heading, as compass point. For example, "NE" for north-east.

See also: Storm Properties

[Top]Heading (Ship Property)

Heading:Str                                (read-only)

Current angle of movement, as compass direction.

See also: Ship Properties

[Top]Heading (Ufo Property)

Heading:Str                                (read-only)

Heading, as compass direction.

See also: Ufo Properties

[Top]Heading$ - Disambiguation

There are multiple items with this name:

[Top]Heading$ (Storm Property)

Heading$:Int                               (read-only)

Ion storm's heading, in degrees.

See also: Storm Properties

[Top]Heading$ (Ship Property)

Heading$:Int                               (read-only)

Current angle of movement, in degrees. EMPTY if the ship is not moving, or the angle is not known.

See also: Ship Properties

[Top]Heading$ (Ufo Property)

Heading$:Int                               (read-only)

Heading, in degrees. EMPTY if Ufo does not move or heading is not known.

See also: Ufo Properties

[Top]HistoryScreen (Keymap)

 Bind HistoryScreen key := command

Keys on this keymap are active on the starship history screen.

This keymap includes (derives from) ControlScreen and Ship.

Since: PCC 1.0.15, PCC2 1.99.9

See also: Keymaps

[Top]Hull - Disambiguation

There are multiple items with this name:

[Top]Hull (Context, Function)

Hull(id:Int):Obj

Access hull properties. Use as

 ForEach Hull Do ...

or

 With Hull(n) Do ...

Version Differences: This function was available for use in With under the name Hulls() since PCC 1.0.6. Do not use the name Hulls in new code, it is not supported by PCC2; use Hull instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Hull Properties, Contexts, Functions

[Top]Hull (Ship Property)

Hull:Str                                   (read-only)

Name of the ship's hull.

See also: Ship Properties

[Top]Hull (Combat Participant Property)

Hull:Str                                   (read-only)

Hull name. EMPTY if the hull cannot be determined, or this is a planet.

See also: Combat Participant Properties

[Top]Hull$ - Disambiguation

There are multiple items with this name:

[Top]Hull$ (Ship Property)

Hull$:Str                                  (read-only)

Hull Id.

See also: Ship Properties

[Top]Hull$ (Combat Participant Property)

Hull$:Int                                  (read-only)

Hull number. EMPTY if the hull cannot be determined, or this is a planet.

See also: Combat Participant Properties

[Top]Hull.Short (Ship Property)

Hull.Short:Str                             (read-only)

Short name of the hull.

See also: Ship Properties

[Top]Hull.Special (Ship Property)

Hull.Special:Str                           (read-only)

Special function summary. This is a string identifying the major special functions of this ship. The string will contain each letter if and only if the ship has the respective ability assigned for all players.

See also: Ship Properties

[Top]Id - Disambiguation

There are multiple items with this name:

[Top]Id (Storm Property)

Id:Int                                     (read-only)

Ion storm's Id.

See also: Storm Properties

[Top]Id (Minefield Property)

Id:Int                                     (read-only)

Id of this minefield.

See also: Minefield Properties

[Top]Id (Incoming Message Property)

Id:Int                                     (read-only)

Id of message. This is the index into InMsg() to access this very message.

See also: Incoming Message Properties

[Top]Id (Planet Property)

Id:Int                                     (read-only)

Planet Id.

See also: Planet Properties

[Top]Id (Plugin Property)

Id:Str                                     (read-only)

Id of the plugin.

Since: PCC2 1.99.25

See also: Plugin Properties

[Top]Id (Ship Property)

Id:Int                                     (read-only)

Ship Id.

See also: Ship Properties

[Top]Id (Beam Property, Engine Property, Hull Property, Torpedo Property)

Id:Str                                     (read-only)

Component Id.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Id (Ufo Property)

Id:Int                                     (read-only)

Ufo Id.

See also: Ufo Properties

[Top]Id (Combat Participant Property)

Id:Int                                     (read-only)

Id of this ship or planet.

See also: Combat Participant Properties

[Top]Id2 (Ufo Property)

Id2:Int                                    (read/write)

Real Id number, or 0. Some add-ons send their own objects, which may have different Id numbers, to Ufos to make them visible to players. This field is to support these add-ons. Currently, this field is used with PHost's wormholes, where it holds the real Id number of the wormhole, using the usual rules (even Id = entry, odd Id = exit).

See also: Ufo Properties

[Top]If - Disambiguation

There are multiple items with this name:

[Top]If (Elementary Function)

If(cond:Bool, yes:Expr, [no:Expr]):Any

Conditional evaluation. If the condition cond evaluates to true, evaluates yes and returns its value. Otherwise, if the condition is false or EMPTY, evaluates no and returns its value (and if no is not specified, just returns EMPTY).

Since: PCC 0.98.5, PCC2 1.99.8

See also: Elementary Functions

[Top]If (Elementary Command)

 If cond Then command

 If cond [Then]
   commands
 Else If cond [Then]
   commands
 Else
   commands
 EndIf

Conditional execution. The If condition is evaluated. If it yields True, the first (or only) set of commands is executed. If it yields False or EMPTY, the Else If condition, if any, is checked, and the first matching set of commands is executed. If neither condition yields True, the Else commands are executed.

There can be any number of Else If blocks (including none at all), and zero or one Else blocks.

Version Differences: Else If is supported since PCC 1.1.13.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Select, If (Elementary Function), Elementary Commands

[Top]Image - Disambiguation

There are multiple items with this name:

[Top]Image (Hull Property)

Image:Int                                  (read/write)

Picture number used to display this ship in PCC.

See also: Hull Properties

[Top]Image (Combat Participant Property)

Image:Int                                  (read-only)

Number of ship picture. If the hull of the ship can be determined, your changes to the picture assignment will be honored, otherwise, the host-provided picture is returned. For planets, this property is 0.

See also: Combat Participant Properties

[Top]Image$ (Hull Property)

Image$:Int                                 (read-only)

Picture number used to display this ship in planets.exe.

See also: Hull Properties

[Top]InMsg (Context, Function)

InMsg(n:Int):Obj

Access incoming message. Use as

 ForEach InMsg Do ...

or

 With InMsg(n) Do ...

The parameter n runs from 1 to My.InMsgs.

Since: PCC 1.1.13, PCC2 1.99.13

See also: Incoming Message Properties, Contexts, Functions

[Top]InStr (Elementary Function)

InStr(haystack:Str, needle:Str):Str

Find substring. Locates the first occurrence of needle in haystack. It returns the position of that string as an integer, where 1 means the first position. If there is no match, returns 0.

Note that, by default, substring search is case-insensitive. Use StrCase to search case-sensitive.

Examples:

   InStr("frob","o") = 3
   InStr("frob","x") = 0

If any parameter is EMPTY, this function returns EMPTY.

Since: PCC 0.99.2, PCC2 1.99.8

See also: Elementary Functions

[Top]Index (Combat Participant Property)

Index:Int                                  (read-only)

Position of this unit in the fight. This is the index into the fight's Unit array.

See also: Combat Participant Properties

[Top]Industry (Planet Property)

Industry:Str                               (read-only)

Planetary industry level, human-readable.

See also: Industry$ (Planet Property), Planet Properties

[Top]Industry$ (Planet Property)

Industry$:Int                              (read-only)

Planetary industry level code.

Ind$ Ind
0 Minimal
1 Light
2 Moderate
3 Substantial
4 Heavy

See also: Planet Properties

[Top]Info1, Info2 (Ufo Property)

Info1:Str                                  (read-only)
Info2:Str                                  (read-only)

Description of this Ufo.

See also: Ufo Properties

[Top]Input (Global Command)

Input #f:File, var:Str, [flag:Bool]

Read line data. This command will read one line of text from the file, and place it in the variable var. The flag specifies what to do at the end of the file:

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]Int (Elementary Function)

Int(n:Num):Int

Convert to integer. If the parameter is a floating-point (fractional) number, truncates its fractional digits and converts it into an integer. If the parameter already is an integer, it is returned as is.

Examples:

   Int(2.5) = 2
   Int(-2.1) = -2

If the parameter is EMPTY, this function returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Round, Elementary Functions

[Top]IsArray (Elementary Function)

IsArray(a:Any):Int

Check for array. If the parameter refers to an array, returns the number of dimensions. If the parameter is another non-EMPTY value, returns 0. If the parameter is EMPTY, this function returns EMPTY.

Since every array has at least one dimension, this function can be used as if it returns a truth value if required:

  If IsArray(a) Then Print "This is an array!"

Since 1.99.22, this function also works for builtin arrays such as Ship().

Since: PCC2 1.99.12

See also: Dim (Elementary Function), Elementary Functions

[Top]IsEmpty (Elementary Function)

IsEmpty(a:Any):Bool

Check for EMPTY. If the parameter is EMPTY, returns True. Otherwise, returns False.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Elementary Functions

[Top]IsNum (Elementary Function)

IsNum(a:Any):Bool

Check for number. If the parameter is a number, returns True. Otherwise, returns False.

Version Differences: PCC 1.x returns False for Booleans. PCC2 returns True, since a Boolean can be used wherever a number is required.

Since: PCC 1.0.14, PCC2 1.99.8

See also: Elementary Functions

[Top]IsPlanet (Combat Participant Property)

IsPlanet:Bool                              (read-only)

True if this is a planet.

See also: Combat Participant Properties

[Top]IsSpecialFCode (Function)

IsSpecialFCode(fc:Str):Bool

Check for special friendly code. Returns true if the friendly code given as a parameter is a special friendly code.

Since: PCC 1.1.4, PCC2 1.99.8

See also: Functions

[Top]IsString (Elementary Function)

IsString(a:Any):Bool

Check for number. If the parameter is a string, returns True. Otherwise, returns False.

Since: PCC 1.0.14, PCC2 1.99.8

See also: Elementary Functions

[Top]Keep (Ufo Property)

Keep:Bool                                  (read/write)

True to keep this Ufo in the database. Defaults to False, i.e. the Ufo is only displayed when sent by the host.

See also: Ufo Properties

[Top]Key - Disambiguation

There are multiple items with this name:

[Top]Key (Elementary Function)

Key(k:Keymap, key:Str):Int

Look up key in keymap. The keymap is specified as the keymap name, the key is a string, as in

  Key(Global, "Alt-C")

If the key is bound in the keymap, returns its numeric command code. This usually is an atom that can be converted back into a command using AtomStr.

If the key is not bound in the keymap directly, its parent keymaps will be consulted. If the key cannot be found in those as well, the return value is EMPTY.

Version Differences: It is an error in PCC2 if the keymap does not exist. PCC 1.x just returns EMPTY in this case.

Since: PCC 1.1.10, PCC2 1.99.9

See also: Bind, Elementary Functions

[Top]Key (Hash Element Property)

Key:Str                                    (read-only)

The key of this hash element.

See also: Hash Element Properties

[Top]Kill (Beam Property, Torpedo Property)

Kill:Int                                   (read-only)

Anti-life power of this weapon.

See also: Beam Properties, Torpedo Properties

[Top]Killed (Incoming Message Property)

Killed:Bool                                (read-only)

True if this message is filtered and skipped by default.

See also: Incoming Message Properties

[Top]LTrim (Elementary Function)

LTrim(s:Str):Str

Trim leading (left) whitespace. Returns the string s with all leading space and tab characters removed.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.99, PCC2 1.99.8

See also: Trim, RTrim, Elementary Functions

[Top]LastScan - Disambiguation

There are multiple items with this name:

[Top]LastScan (Minefield Property)

LastScan:Int                               (read-only)

Turn when minefield was last scanned.

See also: Minefield Properties

[Top]LastScan (Ufo Property)

LastScan:Int                               (read-only)

Turn when Ufo was last scanned.

See also: Ufo Properties

[Top]Launcher (Context, Function)

Launcher(id:Int):Obj

Access torpedo launcher properties. Use as

 ForEach Launcher Do ...

or

 With Launcher(n) Do ...

Version Differences: This function was available for use in With under the name Launchers() since PCC 1.0.6. Do not use the name Launchers in new code, it is not supported by PCC2; use Launcher instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Torpedo Properties, Torpedo(), Contexts, Functions

[Top]Left - Disambiguation

There are multiple items with this name:

[Top]Left (Elementary Function)

Left(s:Str, n:Int):Str

Get initial (left) part of a string. Returns the first n characters of string s.

If any parameter is EMPTY, returns EMPTY. If n is negative, returns an empty string.

Since: PCC 0.99.2, PCC2 1.99.8

See also: Elementary Functions

[Top]Left, Right (Combat Property)

Left:Int                                   (read-only)
Right:Int                                  (read-only)

Name and type of this combat participant. A string of the form "name (Planet #Id)" resp. "name (Ship #Id)".

See also: Combat Properties

[Top]Left.Aux, Right.Aux (Combat Property)

Left.Aux:Str                               (read-only)
Right.Aux:Str                              (read-only)

Secondary weapon type, full name. Either a torpedo system name, "Fighters", or EMPTY.

See also: Combat Properties

[Top]Left.Aux$, Right.Aux$ (Combat Property)

Left.Aux$:Int                              (read-only)
Right.Aux$:Int                             (read-only)

Type of secondary weapon.

See also: Combat Properties

[Top]Left.Aux.Ammo, Right.Aux.Ammo (Combat Property)

Left.Aux.Ammo:Int                          (read-only)
Right.Aux.Ammo:Int                         (read-only)

Number of fighters or torpedoes on this unit.

See also: Combat Properties

[Top]Left.Aux.Count, Right.Aux.Count (Combat Property)

Left.Aux.Count:Int                         (read-only)
Right.Aux.Count:Int                        (read-only)

Number of fighter bays or torpedo launchers on this unit.

See also: Combat Properties

[Top]Left.Aux.Short, Right.Aux.Short (Combat Property)

Left.Aux.Short:Str                         (read-only)
Right.Aux.Short:Str                        (read-only)

Secondary weapon type, short name.

See also: Left.Aux (Combat Property), Combat Properties

[Top]Left.Beam, Right.Beam (Combat Property)

Left.Beam:Str                              (read-only)
Right.Beam:Str                             (read-only)

Beam type, full name.

See also: Combat Properties

[Top]Left.Beam$, Right.Beam$ (Combat Property)

Left.Beam$:Int                             (read-only)
Right.Beam$:Int                            (read-only)

Beam type. 0 if none, EMPTY if not known.

See also: Combat Properties

[Top]Left.Beam.Count, Right.Beam.Count (Combat Property)

Left.Beam.Count:Int                        (read-only)
Right.Beam.Count:Int                       (read-only)

Number of beams.

See also: Combat Properties

[Top]Left.Beam.Short, Right.Beam.Short (Combat Property)

Left.Beam.Short:Str                        (read-only)
Right.Beam.Short:Str                       (read-only)

Beam type, short name.

See also: Combat Properties

[Top]Left.Crew, Right.Crew (Combat Property)

Left.Crew:Int                              (read-only)
Right.Crew:Int                             (read-only)

Crew on this ship. EMPTY if this is a planet.

See also: Combat Properties

[Top]Left.Crew$, Right.Crew$ (Combat Property)

Left.Crew$:Int                             (read-only)
Right.Crew$:Int                            (read-only)

Crew. This returns the raw, unfiltered value of the Crew field within the VCR data structure. This field normally has a meaning only for ships.

See also: Crew (Combat Participant Property), Combat Properties

[Top]Left.Damage, Right.Damage (Combat Property)

Left.Damage:Int                            (read-only)
Right.Damage:Int                           (read-only)

Initial damage in percent.

See also: Combat Properties

[Top]Left.Fighter.Bays, Right.Fighter.Bays (Combat Property)

Left.Fighter.Bays:Int                      (read-only)
Right.Fighter.Bays:Int                     (read-only)

Number of fighter bays.

See also: Combat Properties

[Top]Left.Fighter.Count, Right.Fighter.Count (Combat Property)

Left.Fighter.Count:Int                     (read-only)
Right.Fighter.Count:Int                    (read-only)

Number of fighters.

See also: Combat Properties

[Top]Left.Hull, Right.Hull (Combat Property)

Left.Hull:Str                              (read-only)
Right.Hull:Str                             (read-only)

Hull name. EMPTY if the hull cannot be determined, or this is a planet.

See also: Combat Properties

[Top]Left.Hull$, Right.Hull$ (Combat Property)

Left.Hull$:Int                             (read-only)
Right.Hull$:Int                            (read-only)

Hull number. EMPTY if the hull cannot be determined, or this is a planet.

See also: Combat Properties

[Top]Left.Id, Right.Id (Combat Property)

Left.Id:Int                                (read-only)
Right.Id:Int                               (read-only)

Id of this ship or planet.

See also: Combat Properties

[Top]Left.Image, Right.Image (Combat Property)

Left.Image:Int                             (read-only)
Right.Image:Int                            (read-only)

Number of ship picture. If the hull of the ship can be determined, your changes to the picture assignment will be honored, otherwise, the host-provided picture is returned. For planets, this property is 0.

See also: Combat Properties

[Top]Left.Level, Right.Level (Combat Property)

Left.Level:Int                             (read-only)
Right.Level:Int                            (read-only)

Experience level for this unit. 0 if the fight does not include experience levels (because experience is not enabled, maybe).

See also: Combat Properties

[Top]Left.Mass, Right.Mass (Combat Property)

Left.Mass:Int                              (read-only)
Right.Mass:Int                             (read-only)

Combat mass of this unit. This mass includes the hull weight and optional bonuses, such as the Engine-Shield-Bonus, but not the ship's cargo, equipment or ammo. It therefore cannot be meaningfully compared to a ship's mass.

See also: Combat Properties

[Top]Left.Name, Right.Name (Combat Property)

Left.Name:Int                              (read-only)
Right.Name:Int                             (read-only)

Name of ship or planet.

See also: Combat Properties

[Top]Left.Owner, Right.Owner (Combat Property)

Left.Owner:Str                             (read-only)
Right.Owner:Str                            (read-only)

Short name of this player.

See also: Combat Properties

[Top]Left.Owner$, Right.Owner$ (Combat Property)

Left.Owner$:Int                            (read-only)
Right.Owner$:Int                           (read-only)

Player number.

See also: Combat Properties

[Top]Left.Owner.Adj, Right.Owner.Adj (Combat Property)

Left.Owner.Adj:Str                         (read-only)
Right.Owner.Adj:Str                        (read-only)

Adjective name of this player.

See also: Combat Properties

[Top]Left.Shield, Right.Shield (Combat Property)

Left.Shield:Int                            (read-only)
Right.Shield:Int                           (read-only)

Initial shield level in percent.

See also: Combat Properties

[Top]Left.Status, Right.Status (Combat Property)

Left.Status:Str                            (read-only)
Right.Status:Str                           (read-only)

Battle result, from the point-of-view of this unit.

Computing the value for this property may involve playing the whole VCR, and thus take a considerable amount of time. Results are cached, so you'll only have to wait once.

See also: Combat Properties

[Top]Left.Status$, Right.Status$ (Combat Property)

Left.Status$:Int                           (read-only)
Right.Status$:Int                          (read-only)

Battle result, from the point-of-view of this unit. This is an integer:

See also: Combat Properties

[Top]Left.Torp, Right.Torp (Combat Property)

Left.Torp:Str                              (read-only)
Right.Torp:Str                             (read-only)

Torpedo type, full name.

See also: Combat Properties

[Top]Left.Torp$, Right.Torp$ (Combat Property)

Left.Torp$:Int                             (read-only)
Right.Torp$:Int                            (read-only)

Torpedo type.

See also: Combat Properties

[Top]Left.Torp.Count, Right.Torp.Count (Combat Property)

Left.Torp.Count:Int                        (read-only)
Right.Torp.Count:Int                       (read-only)

Number of torpedoes. 0 if the ship has no torpedoes.

See also: Combat Properties

[Top]Left.Torp.LCount, Right.Torp.LCount (Combat Property)

Left.Torp.LCount:Int                       (read-only)
Right.Torp.LCount:Int                      (read-only)

Number of torpedo launchers on this ship.

See also: Combat Properties

[Top]Left.Torp.Short, Right.Torp.Short (Combat Property)

Left.Torp.Short:Str                        (read-only)
Right.Torp.Short:Str                       (read-only)

Torpedo type, short name.

See also: Combat Properties

[Top]Left.Type, Right.Type (Combat Property)

Left.Type:Str                              (read-only)
Right.Type:Str                             (read-only)

Classification of this unit. Possible values are:

See also: Combat Properties

[Top]Left.Type.Short, Right.Type.Short (Combat Property)

Left.Type.Short:Str                        (read-only)
Right.Type.Short:Str                       (read-only)

Classification of this unit, short. This is the first letter of the Type, see there.

See also: Combat Properties

[Top]Len (Elementary Function)

Len(s:Str):Int

Get length of string. Returns the number of characters within the string. Version Differences: PCC 1.x accepts all types and will stringify them. PCC2 only accepts strings.

Since: PCC 0.98.5, PCC2 1.99.8

See also: Elementary Functions

[Top]Level - Disambiguation

There are multiple items with this name:

[Top]Level (Planet Property)

Level:Int                                  (read-only)

Planet's experience level. If the experience system is not enabled, or the level is not known, yields EMPTY.

See also: Planet Properties

[Top]Level (Ship Property)

Level:Int                                  (read-only)

Ship's experience level. If the experience system is not enabled, or the level is not known, yields EMPTY.

See also: Ship Properties

[Top]Level (Combat Participant Property)

Level:Int                                  (read-only)

Experience level for this unit. 0 if the fight does not include experience levels (because experience is not enabled, maybe).

See also: Combat Participant Properties

[Top]Lines (Incoming Message Property)

Lines:Int                                  (read-only)

Number of lines in message.

See also: Incoming Message Properties

[Top]Listbox (Function)

 With Listbox(title:Str, Optional current:Int, width:Int, height:Int, help:Str) Do
   AddItem id:Int, text:Str
   Run
 EndWith

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

The parameters are as follows:

The Run command actually displays the list box and lets the user choose from it. It sets the UI.Result variable to the identifier (id) 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.

Since: PCC 1.1.1, PCC2 1.99.25

See also: Functions

[Top]Load - Disambiguation

There are multiple items with this name:

[Top]Load (Hook)

 On Load Do command

Commands registered for the Load hook are run immediately after a game has been loaded. This is the right place to load data that is needed for playing.

Since: PCC 1.0.9, PCC2 1.99.9

See also: Hooks

[Top]Load, TryLoad (Elementary Command)

Load name:Str
TryLoad name:Str

Load a script. The parameter is a file name. That file is loaded and executed, as if its content were part of a subroutine.

For Load, it is an error if the file cannot be found.

For TryLoad, it is not an error if the file cannot be found, but errors during its execution are still reported (whereas Try Load file would "swallow" all errors). This makes it ideal for loading optional files.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]LoadHelpFile (Global Command)

LoadHelpFile name:Str

Load a help file. PCC2 help files are files in a custom XML format. Help files can be added using plugins (HelpFile= directive), or using this command.

This command does not verify that the file actually exists; if the given name does not refer to a valid help file, a console message will be printed, but the command will not fail.

Since: PCC2 2.0.5

See also: Global Commands

[Top]LoadResource (Global Command)

LoadResource name:Str

Load a resource. You can specify all items you can also specify in cc-res.cfg.

File and directory names should be absolute.

If the given name does not refer to a valid resource item, a console message will be printed, but the command will not fail.

Because PCC2 caches loaded resource elements, you should call this command as early as possible (in pcc2init.q, usually).

For loading *.res files, also see the chapter on plugins; loading a *.res file using the ResourceFile plugin directive will also work in PlayVCR which has no script interpreter.

Since: PCC 1.0.19, PCC2 1.99.25

See also: Global Commands

[Top]Loc (Ship Property)

Loc:Str                                    (read-only)

Location of ship, as a human-readable string. If the ship is at a planet, returns that planet's name and Id. In deep space, returns an (X,Y) pair.

See also: Ship Properties

[Top]Loc.X - Disambiguation

There are multiple items with this name:

[Top]Loc.X (Drawing Property)

Loc.X:Int                                  (read-only)

X location of starting point/center.

See also: Drawing Properties

[Top]Loc.X (Storm Property)

Loc.X:Int                                  (read-only)

Ion storm center X coordinate.

See also: Storm Properties

[Top]Loc.X (Minefield Property)

Loc.X:Int                                  (read-only)

X location of center of minefield.

See also: Minefield Properties

[Top]Loc.X (Planet Property)

Loc.X:Int                                  (read-only)

Planet X location.

See also: Planet Properties

[Top]Loc.X (Ship Property)

Loc.X:Int                                  (read-only)

X location of ship.

See also: Ship Properties

[Top]Loc.X (Ufo Property)

Loc.X:Int                                  (read-only)

X location of Ufo center.

See also: Ufo Properties

[Top]Loc.Y - Disambiguation

There are multiple items with this name:

[Top]Loc.Y (Drawing Property)

Loc.Y:Int                                  (read-only)

Y location of starting point/center.

See also: Drawing Properties

[Top]Loc.Y (Storm Property)

Loc.Y:Int                                  (read-only)

Ion storm center Y coordinate.

See also: Storm Properties

[Top]Loc.Y (Minefield Property)

Loc.Y:Int                                  (read-only)

Y location of center of minefield.

See also: Minefield Properties

[Top]Loc.Y (Planet Property)

Loc.Y:Int                                  (read-only)

Planet Y location.

See also: Planet Properties

[Top]Loc.Y (Ship Property)

Loc.Y:Int                                  (read-only)

Y location of ship.

See also: Ship Properties

[Top]Loc.Y (Ufo Property)

Loc.Y:Int                                  (read-only)

Y location of Ufo center.

See also: Ufo Properties

[Top]Local (Elementary Command)

Local name [initializer],...

Create a local variable. Same as Dim Local, see there.

Since: PCC 1.0.6, PCC2 1.99.8

See also: Elementary Commands

[Top]Lock (Function)

Lock(name:Str, [hint:Str]):Any

Acquire a lock.

When auto-tasks control parts of the game, it must be made sure that two tasks do not accidentally stomp on each other's feet, or that you don't accidentally change something the auto-task controls. To do that, auto-tasks can acquire locks, which are honored by the user interface. If the user tries to do something which an auto-task claims for itself, a warning message is displayed, citing the auto-task name and the hint given by the Lock invocation.

Locks are acquired using the Lock function in combination with the With statement:

 With Lock(name) Do
   % protected code here
 EndWith

The With Lock statement acquires the lock. The lock is held by the current process until the With statement terminates, usually at the EndWith.

A lock is uniquely identified by a name. No two processes can have a lock at the same time. If a process tries to acquire a blocked lock, this fails with an error.

The following lock names are known by PCC, and honored by the user interface:

pNNN.tax Taxation. Controls the tax change commands (natives/colonists).
pNNN.struct Structures (mines/factories/defense). Controls the structure building commands.
sNNN.waypoint Waypoint. Controls the ship's waypoint. Setting an Intercept order is considered a waypoint change. Note that locking the waypoint on a fleet member can not always be enforced.

The names are case-insensitive. "NNN" stands for the unit Id (e.g. "p15.tax").

Note: A lock does not block particular operations. Even if someone has the tax lock, the SetColonistTax command will still work. The lock is intended as a hint for user-interface commands to display a warning, but not to block anything.

Note 2: Although Lock formally is a function, using it in other ways than a With Lock statement is not supported; it may work or not, it's not guaranteed. The return value cannot meaningfully be used.

Since: PCC 1.1.2, PCC2 1.99.17

See also: GetLockInfo, Functions

[Top]Log (Elementary Function)

Log(n:Num):Num

Natural logarithm. Computes the logarithm to base e, where e is Euler's number. The parameter must be a strictly positive number. This is the inverse to the Exp function.

If the parameter is EMPTY, returns EMPTY.

Since: PCC2 1.99.8

See also: Elementary Functions

[Top]Loop (Elementary Command)

This keyword is part of the Do loop, see there.

See also: Elementary Commands

[Top]Magic (Combat Property)

Magic:Int                                  (read-only)

VCR algorithm identification value. Valid only for classic combat, EMPTY for others.

See also: Combat Properties

[Top]MakeFileName (Function)

MakeFileName(n:Str...):Str

Create a file name. Parameters are file name fragments, i.e. directories, until the last fragment which is a file name. This function builds a file name from these, using operating-system dependant rules. For example,

 MakeFileName("a", "b", "c.txt")

will return "a\b\c.txt" or "a/b/c.txt", depending on the operating system.

Since: PCC 1.1.20, PCC2 1.99.12

See also: Functions

[Top]Maketurn (Hook)

 On Maketurn Do command

Commands registered for the Maketurn hook are run after turn files have been compiled by the Maketurn function.

Note: This functionality does not exist in PCC2.

Since: PCC 1.1.4

See also: Hooks

[Top]Mark (Minefield Command, Planet Command, Ship Command, Storm Command, Ufo Command)

Mark [flag:Bool]

Mark object. Marks the current object. If the flag is specified as False, unmarks it instead.

Version Differences: This command is also available for ufos, ion storms, and minefields since PCC2 1.99.13. Older versions and PCC 1.x only allow it for ships and planets.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Unmark, Minefield Commands, Planet Commands, Ship Commands, Storm Commands, Ufo Commands

[Top]Marked - Disambiguation

There are multiple items with this name:

[Top]Marked (Storm Property)

Marked:Bool                                (read-only)

True if ion storm is marked.

See also: Storm Properties

[Top]Marked (Minefield Property)

Marked:Bool                                (read-only)

True if minefield is marked.

See also: Minefield Properties

[Top]Marked (Planet Property)

Marked:Bool                                (read-only)

True if planet is marked.

See also: Planet Properties

[Top]Marked (Ship Property)

Marked:Bool                                (read-only)

True if ship is marked.

See also: Ship Properties

[Top]Marked (Ufo Property)

Marked:Bool                                (read-only)

True if Ufo is marked.

See also: Ufo Properties

[Top]Mass - Disambiguation

There are multiple items with this name:

[Top]Mass (Ship Property)

Mass:Int                                   (read-only)

Mass of ship (hull, components, and cargo).

See also: Ship Properties

[Top]Mass (Beam Property, Torpedo Property)

Mass:Int                                   (read-only)

Mass of this component, in kt.

See also: Beam Properties, Torpedo Properties

[Top]Mass (Combat Participant Property)

Mass:Int                                   (read-only)

Combat mass of this unit. This mass includes the hull weight and optional bonuses, such as the Engine-Shield-Bonus, but not the ship's cargo, equipment or ammo. It therefore cannot be meaningfully compared to a ship's mass.

See also: Combat Participant Properties

[Top]Max (Elementary Function)

Max(a:Any...):Any

Maximum. Compares all arguments, which must all be numbers, or all strings, and returns the maximum. If any argument is EMPTY, returns EMPTY.

Note that, by default, string comparison is case-insensitive. Use StrCase to compare case-sensitive.

Version Differences: Whereas PCC2 allows any number of parameters, PCC 1.x has a limit of 6.

Since: PCC 1.0.7, PCC2 1.99.8

See also: StrCase, Min, Elementary Functions

[Top]MessageBox (Global Command)

MessageBox text:Str, [heading:Str]

Display a message. In the graphical interface, displays an "OK" message box. In console mode, just prints out a message and continues.

Since: PCC 1.0.6, PCC2 1.99.9

See also: UI.Message, Global Commands

[Top]Messages - Disambiguation

There are multiple items with this name:

[Top]Messages (Planet Property)

Messages:Obj()                             (read-only)

If this planet has any messages, this property is non-null and contains an array of messages. Individual messages have the same form as the inbox messages (InMsg()).

Since: PCC2 2.0.3

See also: Incoming Message Properties, Planet Properties

[Top]Messages (Ship Property)

Messages:Obj()                             (read-only)

If this ship has any messages, this property is non-null and contains an array of messages. Individual messages have the same form as the inbox messages (InMsg()).

Since: PCC2 2.0.3

See also: Incoming Message Properties, Ship Properties

[Top]Mid (Elementary Function)

Mid(s:Str, pos:Int, [count:Int]):Str

Substring extraction. Returns count characters from string s starting at position pos. If count is not specified, returns all characters from that position.

If any parameter is EMPTY, returns EMPTY.

Since: PCC 0.99.2, PCC2 1.99.8

See also: RMid, Left, Right, Elementary Functions

[Top]Min (Elementary Function)

Min(a:Any...):Any

Minimum. Compares all arguments, which must all be numbers, or all strings, and returns the minimum. If any argument is EMPTY, returns EMPTY.

Note that, by default, string comparison is case-insensitive. Use StrCase to compare case-sensitive.

Version Differences: Whereas PCC2 allows any number of parameters, PCC 1.x has a limit of 6.

Since: PCC 1.0.7, PCC2 1.99.8

See also: StrCase, Max, Elementary Functions

[Top]Mined.D (Planet Property)

Mined.D:Int                                (read-only)

Mined Duranium, in kilotons.

See also: Planet Properties

[Top]Mined.M (Planet Property)

Mined.M:Int                                (read-only)

Mined Molybdenum, in kilotons.

See also: Planet Properties

[Top]Mined.N (Planet Property)

Mined.N:Int                                (read-only)

Mined Neutronium, in kilotons.

See also: Planet Properties

[Top]Mined.Str (Planet Property)

Mined.Str:Cargo                            (read-only)

Mined minerals, as a string.

See also: Planet Properties

[Top]Mined.T (Planet Property)

Mined.T:Int                                (read-only)

Mined Tritanium, in kilotons.

See also: Planet Properties

[Top]Minefield (Context, Function)

Minefield(id:Int):Obj

Access minefield properties. Use as

 ForEach Minefield Do ...

or

 With Minefield(n) Do ...

Version Differences: This function was available for use in With under the name Minefields() since PCC 1.0.11. Do not use the name Minefields in new code, it is not supported by PCC2; use Minefield instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Minefield Properties, Minefield Commands, Contexts, Functions

[Top]Mines (Planet Property)

Mines:Int                                  (read-only)

Number of mineral mines.

See also: Planet Properties

[Top]Mines.Max (Planet Property)

Mines.Max:Int                              (read-only)

Maximum number of mineral mines.

See also: Planet Properties

[Top]Mines.Want (Planet Property)

Mines.Want:Int                             (read/write)

Auto-build goal for mineral mines.

See also: Planet Properties

[Top]Mission - Disambiguation

There are multiple items with this name:

[Top]Mission (Planet Property)

Mission:Str                                (read-only)

Starbase mission. EMPTY if no base.

See also: Planet Properties

[Top]Mission (Ship Property)

Mission:Str                                (read-only)

Mission, full name.

See also: Ship Properties

[Top]Mission$ - Disambiguation

There are multiple items with this name:

[Top]Mission$ (Planet Property)

Mission$:Int                               (read/write)

Starbase mission number. EMPTY if no base.

See also: Planet Properties

[Top]Mission$ (Ship Property)

Mission$:Int                               (read/write)

Mission number.

See also: SetMission (Ship Command), Ship Properties

[Top]Mission.Intercept (Ship Property)

Mission.Intercept:Int                      (read/write)

Mission "Intercept" parameter.

See also: SetMission (Ship Command), Ship Properties

[Top]Mission.Short (Ship Property)

Mission.Short:Str                          (read-only)

Mission, short name.

See also: Ship Properties

[Top]Mission.Tow (Ship Property)

Mission.Tow:Int                            (read/write)

Mission "Tow" parameter.

See also: SetMission (Ship Command), Ship Properties

[Top]Money (Planet Property)

Money:Int                                  (read-only)

Money (megacredits) on planet.

See also: Planet Properties

[Top]Move.DX (Ufo Property)

Move.DX:Int                                (read/write)

Estimated/average per-turn movement in X direction. Used to update guessed positions when the Ufo is not scanned.

See also: Ufo Properties

[Top]Move.DY (Ufo Property)

Move.DY:Int                                (read/write)

Estimated/average per-turn movement in Y direction. Used to update guessed positions when the Ufo is not scanned.

See also: Ufo Properties

[Top]Move.ETA (Ship Property)

Move.ETA:Int                               (read-only)

Estimated time of arrival at waypoint (number of turns).

See also: Ship Properties

[Top]Move.Fuel (Ship Property)

Move.Fuel:Int                              (read-only)

Predicted fuel useage for movement, in kilotons.

See also: Ship Properties

[Top]MoveTo (Ship Command)

MoveTo x:Int, y:Int

Move ship to X,Y. This sets a waypoint, and suspends the script until the waypoint has been reached. As a special case, if the waypoint is in a warp well, the script continues when the planet has been reached.

Example:

  MoveTo 1240, 1500
  MoveTo 1400, 1520

This will move the ship to (1240,1500) and then to (1400,1520).

This command is intended to be used in auto tasks.

Since: PCC 1.0.6, PCC2 1.99.10

See also: Stop, Ship Commands

[Top]MoveTowards (Ship Command)

MoveTowards x:Int, y:Int

Move ship towards X,Y. This command sets the waypoint and waits one turn. This causes the ship to move towards the specified coordinate, but not necessarily reach it.

This command is intended to be used in auto tasks.

Since: PCC 1.1.3, PCC2 1.99.10

See also: Stop, Ship Commands

[Top]My.Bases (Global Property)

My.Bases:Int                               (read-only)

Number of bases this player has, according to score.

See also: Global Properties

[Top]My.InMsgs (Global Property)

My.InMsgs:Int                              (read-only)

Number of incoming (received) messages this turn.

See also: Global Properties

[Top]My.OutMsgs (Global Property)

My.OutMsgs:Int                             (read-only)

Number of outgoing (sent) messages this turn.

See also: Global Properties

[Top]My.PBPs (Global Property)

My.PBPs:Int                                (read-only)

Number of priority points. This reports the build queue priority points for a player, no matter what flavour of build points is active (PBPs, PAL).

Since: PCC 0.98.5, PCC2 1.99.25

See also: Global Properties

[Top]My.Planets (Global Property)

My.Planets:Int                             (read-only)

Number of planets this player has, according to score.

See also: Global Properties

[Top]My.Race (Global Property)

My.Race:Str                                (read-only)

Short name of this player.

See also: Global Properties

[Top]My.Race$ (Global Property)

My.Race$:Int                               (read-only)

Player number.

See also: Global Properties

[Top]My.Race.Adj (Global Property)

My.Race.Adj:Str                            (read-only)

Adjective name of this player.

See also: Global Properties

[Top]My.Race.Full (Global Property)

My.Race.Full:Str                           (read-only)

Full name of this player.

See also: Global Properties

[Top]My.Race.Id (Global Property)

My.Race.Id:Int                             (read-only)

Race assigned to this player.

See also: Global Properties

[Top]My.Race.Mission (Global Property)

My.Race.Mission:Int                        (read-only)

Special mission assigned to this player.

See also: Global Properties

[Top]My.Score (Global Property)

My.Score:Int                               (read-only)

This player's Tim-score.

See also: Global Properties

[Top]My.Score.Freighters (Global Property)

My.Score.Freighters:Int                    (read-only)

Number of freighters this player has, according to score.

See also: Global Properties

[Top]My.Ships (Global Property)

My.Ships:Int                               (read-only)

Number of ships this player has, according to score.

See also: Global Properties

[Top]My.Ships.Capital (Global Property)

My.Ships.Capital:Int                       (read-only)

Number of capital ships this player has, according to score.

See also: Global Properties

[Top]My.Team (Global Property)

My.Team:Int                                (read-only)

Team this player is in.

See also: Global Properties

[Top]My.VCRs (Global Property)

My.VCRs:Int                                (read-only)

Number of incoming combat recordings this turn.

See also: Global Properties

[Top]Name - Disambiguation

There are multiple items with this name:

[Top]Name (File Property)

Name:Str                                   (read-only)

Name of the item (file), for example, "player9.rst".

Since: PCC2 2.0.4

See also: File Properties

[Top]Name (Storm Property)

Name:Str                                   (read-only)

Ion storm name.

See also: Storm Properties

[Top]Name (Planet Property)

Name:Str                                   (read-only)

Name of planet.

See also: Planet Properties

[Top]Name (Plugin Property)

Name:Str                                   (read-only)

Human-readable name of the plugin.

Since: PCC2 1.99.25

See also: Plugin Properties

[Top]Name (Ship Property)

Name:Str                                   (read/write)

Ship name.

See also: SetName (Ship Command), Ship Properties

[Top]Name (Beam Property, Engine Property, Hull Property, Torpedo Property)

Name:Str                                   (read/write)

Name of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Name (Ufo Property)

Name:Str                                   (read-only)

Name of Ufo.

See also: Ufo Properties

[Top]Name (Combat Participant Property)

Name:Int                                   (read-only)

Name of ship or planet.

See also: Combat Participant Properties

[Top]Name.Full (Combat Participant Property)

Name.Full:Int                              (read-only)

Name and type of this combat participant. A string of the form "name (Planet #Id)" resp. "name (Ship #Id)".

See also: Combat Participant Properties

[Top]Name.Short (Beam Property, Engine Property, Hull Property, Torpedo Property)

Name.Short:Str                             (read/write)

Short name of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Natives (Planet Property)

Natives:Int                                (read-only)

Native population size, clans.

See also: Planet Properties

[Top]Natives.Change (Planet Property)

Natives.Change:Str                         (read-only)

Native happiness change, text.

See also: Planet Properties

[Top]Natives.Change$ (Planet Property)

Natives.Change$:Int                        (read-only)

Native happiness change, numeric value.

See also: Planet Properties

[Top]Natives.Gov (Planet Property)

Natives.Gov:Str                            (read-only)

Native government name.

See also: Planet Properties

[Top]Natives.Gov$ (Planet Property)

Natives.Gov$:Int                           (read-only)

Native government code.

See also: Planet Properties

[Top]Natives.Happy (Planet Property)

Natives.Happy:Str                          (read-only)

Native happiness, text.

See also: Planet Properties

[Top]Natives.Happy$ (Planet Property)

Natives.Happy$:Int                         (read-only)

Native happiness, numeric value.

See also: Planet Properties

[Top]Natives.Race (Planet Property)

Natives.Race:Str                           (read-only)

Native race, name.

See also: Planet Properties

[Top]Natives.Race$ (Planet Property)

Natives.Race$:Int                          (read-only)

Native race, numeric value.

See also: Planet Properties

[Top]Natives.Tax (Planet Property)

Natives.Tax:Int                            (read/write)

Native tax level.

See also: SetNativeTax (Planet Command), Planet Properties

[Top]Natives.Tax.Base (Planet Property)

Natives.Tax.Base:Int                       (read-only)

Natives base tax level. This is the tax level at which happiness does not change.

Since: PCC2 1.99.15

See also: Planet Properties

[Top]Natives.Tax.Income (Planet Property)

Natives.Tax.Income:Int                     (read-only)

Tax income from natives, megacredits.

Since: PCC2 1.99.15

See also: Planet Properties

[Top]Natives.Tax.Max (Planet Property)

Natives.Tax.Max:Int                        (read-only)

Natives maximum tax level. This is the tax level at which happiness changes by -30.

Since: PCC2 1.99.15

See also: Planet Properties

[Top]NewCircle (Global Command)

NewCircle x:Int, y:Int, radius:Int, [color:Int,
  tag:Int, expire:Int]

Create new circle drawing. The circle will be centered at x,y, and have the specified radius.

The color is an integer between 0 and 30, and selects the color. The tag is a value between 0 and 32767 you can use to identify your drawings, usually this value is created using Atom.

expire defines the time-of-expiry for the game as a turn number: if the current turn number is larger than this value, the drawing is automatically deleted. Thus, set expire=0 to make drawings only visible for the current session. expire=-1 is the default, drawings with this value never expire.

Since: PCC 1.0.5, PCC2 1.99.9

See also: NewLine, NewRectangle, NewMarker, Global Commands

[Top]NewHash (Elementary Function)

NewHash():Hash

Create hash. Allocates a new hash and returns it.

Normally, hashes are created using Dim ... As Hash, but this function remains available as a shortcut.

Since: PCC2 1.99.15

See also: Elementary Functions

[Top]NewLine (Global Command)

NewLine x1:Int, y1:Int, x2:Int, y2:Int, [color:Int,
  tag:Int, expire:Int]

Create new line drawing. On a wrapped map, the coordinates will be adjusted so that the line covers the minimum distance, possibly by crossing a map seam.

The color is an integer between 0 and 30, and selects the color. The tag is a value between 0 and 32767 you can use to identify your drawings, usually this value is created using Atom.

expire defines the time-of-expiry for the game as a turn number: if the current turn number is larger than this value, the drawing is automatically deleted. Thus, set expire=0 to make drawings only visible for the current session. expire=-1 is the default, drawings with this value never expire.

Since: PCC 1.0.5, PCC2 1.99.9

See also: NewCircle, NewLineRaw, NewRectangle, NewMarker, Global Commands

[Top]NewLineRaw (Global Command)

NewLineRaw x1:Int, y1:Int, x2:Int, y2:Int, [color:Int,
  tag:Int, expire:Int]

Create new line drawing. The coordinates will not be adjusted for wrapped maps.

The color is an integer between 0 and 30, and selects the color. The tag is a value between 0 and 32767 you can use to identify your drawings, usually this value is created using Atom.

expire defines the time-of-expiry for the game as a turn number: if the current turn number is larger than this value, the drawing is automatically deleted. Thus, set expire=0 to make drawings only visible for the current session. expire=-1 is the default, drawings with this value never expire.

Since: PCC 1.1.15, PCC2 1.99.9

See also: NewCircle, NewLine, NewRectangle, NewMarker, Global Commands

[Top]NewMarker (Global Command)

NewMarker x:Int, y:Int, type:Int, [color:Int, tag:Int,
  expire:Int]

Create new marker drawing. The type selects the marker shape.

The color is an integer between 0 and 30, and selects the color. The tag is a value between 0 and 32767 you can use to identify your drawings, usually this value is created using Atom.

expire defines the time-of-expiry for the game as a turn number: if the current turn number is larger than this value, the drawing is automatically deleted. Thus, set expire=0 to make drawings only visible for the current session. expire=-1 is the default, drawings with this value never expire.

Since: PCC 1.0.5, PCC2 1.99.9

See also: NewCircle, NewLineRaw, NewRectangle, NewMarker, Global Commands

[Top]NewRectangle (Global Command)

NewRectangle x1:Int, y1:Int, x2:Int, y2:Int,
  [color:Int, tag:Int, expire:Int]

Create new rectangle drawing. On a wrapped map, the coordinates will be adjusted so that the rectangle spans the minimum area, possibly by crossing a map seam.

The color is an integer between 0 and 30, and selects the color. The tag is a value between 0 and 32767 you can use to identify your drawings, usually this value is created using Atom.

expire defines the time-of-expiry for the game as a turn number: if the current turn number is larger than this value, the drawing is automatically deleted. Thus, set expire=0 to make drawings only visible for the current session. expire=-1 is the default, drawings with this value never expire.

Since: PCC 1.0.5, PCC2 1.99.9

See also: NewCircle, NewLine, NewRectangleRaw, NewMarker, Global Commands

[Top]NewRectangleRaw (Global Command)

NewRectangleRaw x1:Int, y1:Int, x2:Int, y2:Int,
  [color:Int, tag:Int, expire:Int]

Create new rectangle drawing. The coordinates will not be adjusted for wrapped maps.

The color is an integer between 0 and 30, and selects the color. The tag is a value between 0 and 32767 you can use to identify your drawings, usually this value is created using Atom.

expire defines the time-of-expiry for the game as a turn number: if the current turn number is larger than this value, the drawing is automatically deleted. Thus, set expire=0 to make drawings only visible for the current session. expire=-1 is the default, drawings with this value never expire.

Since: PCC 1.1.15, PCC2 1.99.9

See also: NewCircle, NewLine, NewRectangle, NewMarker, Global Commands

[Top]NewTurn (Hook)

 On NewTurn Do command

Commands registered for the NewTurn hook are run immediately after Load (Hook) when PCC is started first in a new turn.

Since: PCC 1.1.13, PCC2 1.99.12

See also: Hooks

[Top]Next (Elementary Command)

This keyword is part of the For and ForEach loops, see there.

See also: Elementary Commands

[Top]Notify (Global Command)

Notify s:Str, [t:Int]

Notify message. This command stops execution of an auto task, and informs the player of an event using the message text s. 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 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

When the turn number t 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.

Since: PCC 1.0.18, PCC2 1.99.16

See also: AddNotify, Global Commands

[Top]NumUnits (Combat Property)

NumUnits:Int                               (read-only)

Number of units participating in this fight. This is the number of elements in the Unit array.

Since: PCC2 1.99.19

See also: Combat Properties

[Top]On (Elementary Command)

On event:Hook Do command

Execute command on event. Stores the specified command to be executed when the event happens.

The event is an identifier. Predefined identifiers for event are listed here.

You can define any number of commands for each event. You can also invent your own events, and trigger them using RunHook.

Version Differences: PCC 1.x allows canceling execution of event handlers registered later on using a command such as On event Do Return. This was never documented, and does not work in PCC2.

Since: PCC 1.0.9, PCC2 1.99.9

See also: RunHook, Elementary Commands

[Top]Open (Global Command)

Open name:Str For Input|Output|Random|Append As #file:File]

Open a file. The mode specifies what you intend to do with the file:

Operations with this file will use file number file. If that number already referred to an existing file before, that one will be closed first.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]Option (Elementary Command)

 Option opt(param), ...

Set interpreter options. This command is an "escape" mechanism to give an instruction to the script interpreter. It does not by itself do something, but affect how the interpreter reads and executes your script. If the interpreter understands this instruction, it will honor it, otherwise the instruction will be ignored.

General

The Option command should used be only at places it is intended for. It may not work correctly when used elsewhere.

Since it usually interpreted when the script is read, not when it is executed, parameters to commands cannot be expressions, nor does it make sense to execute Option conditionally within an If or Try.

Option Encoding

 Option Encoding("type")

Defines the script encoding. If you have strings written in a particular character set, name that character set using this command. For example,

 Option Encoding("koi8-r")

says that you wrote your strings in a cyrillic character set.

Place the command at the beginning of your script. It will affect all lines after it.

This option is supported by PCC2 1.99.12 (desktop version), ignored by PCC2 Web and PCC 1.x.

Option Optimize

 Option Optimize(level)

Set the optimisation level. The parameter is a numeric literal. When PCC2 reads the script and compiles it into an internal representation, it can perform some transformations that make the script quicker to execute. Possible optimisation levels are:

As of PCC2 1.99.22, no level 2 or 3 optimisations are implemented.

Place the command at the beginning of your script or subroutine. It will affect this script/subroutine and everything defined within, but not other subroutines following yours.

This option is supported by PCC2 1.99.22.

Option LocalSubs / LocalTypes

 Option LocalSubs(flag)
 Option LocalTypes(flag)

Set availability of the experimental features Local Subroutines and Local Types, see there. The parameter is either 0 (off, default) or 1 (on).

Place the command at the beginning of your script or subroutine. It will affect this script/subroutine and everything defined within, but not other subroutines following yours.

These options are supported by PCC2 1.99.22.

Since: PCC 1.0.19, PCC2 1.99.9

See also: Elementary Commands

[Top]Orbit - Disambiguation

There are multiple items with this name:

[Top]Orbit (Planet Property)

Orbit:Int                                  (read-only)

Total number of ships in orbit of this planet.

See also: Planet Properties

[Top]Orbit (Ship Property)

Orbit:Str                                  (read-only)

Name of planet this ship is orbiting. EMPTY if none.

See also: Ship Properties

[Top]Orbit$ (Ship Property)

Orbit$:Int                                 (read-only)

Id of planet this ship is orbiting. 0 if none.

See also: Ship Properties

[Top]Orbit.Enemy (Planet Property)

Orbit.Enemy:Int                            (read-only)

Number of enemy (=not own) ships in orbit of this planet.

See also: Planet Properties

[Top]Orbit.Own (Planet Property)

Orbit.Own:Int                              (read-only)

Number of own ships in orbit of this planet.

See also: Planet Properties

[Top]Owner - Disambiguation

There are multiple items with this name:

[Top]Owner (Minefield Property, Planet Property, Ship Property)

Owner:Str                                  (read-only)

Short name of this player.

See also: Minefield Properties, Planet Properties, Ship Properties

[Top]Owner (Combat Participant Property)

Owner:Str                                  (read-only)

Short name of this player.

See also: Combat Participant Properties

[Top]Owner$ - Disambiguation

There are multiple items with this name:

[Top]Owner$ (Minefield Property, Planet Property, Ship Property)

Owner$:Int                                 (read-only)

Player number.

See also: Minefield Properties, Planet Properties, Ship Properties

[Top]Owner$ (Combat Participant Property)

Owner$:Int                                 (read-only)

Player number.

See also: Combat Participant Properties

[Top]Owner.Adj - Disambiguation

There are multiple items with this name:

[Top]Owner.Adj (Minefield Property, Planet Property, Ship Property)

Owner.Adj:Str                              (read-only)

Adjective name of this player.

See also: Minefield Properties, Planet Properties, Ship Properties

[Top]Owner.Adj (Combat Participant Property)

Owner.Adj:Str                              (read-only)

Adjective name of this player.

See also: Combat Participant Properties

[Top]Owner.Real (Ship Property)

Owner.Real:Int                             (read-only)

Real owner of this ship, player number. The real owner can differ from the Owner reported normally when the ship is under remote control.

See also: Ship Properties

[Top]PBPs (Player Property)

PBPs:Int                                   (read-only)

Number of priority points. This reports the build queue priority points for a player, no matter what flavour of build points is active (PBPs, PAL).

Since: PCC 0.98.5, PCC2 1.99.25

See also: Player Properties

[Top]Path (File Property)

Path:Str                                   (read-only)

Path of this item. This is the full name of the file that can be used with Open or DirectoryEntry, for example, "/home/user/game/player3.rst".

Since: PCC2 2.0.4

See also: File Properties

[Top]Planet - Disambiguation

There are multiple items with this name:

[Top]Planet (Keymap)

 Bind Planet key := command

Keys on this keymap are active whenever focus is on a planet.

Since: PCC 1.1.17, PCC2 1.99.9

See also: Keymaps

[Top]Planet (Context, Function)

Planet(sid:Int):Obj

Access planet (and starbase) properties. Use as

 ForEach Planet Do ...

or

 With Planet(n) Do ...

Version Differences: This function was available for use in With under the name Planets() since PCC 1.0.6. Do not use the name Planets in new code, it is not supported by PCC2; use Planet instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Planet Properties, Planet Commands, Contexts, Functions

[Top]PlanetAt (Function)

PlanetAt(x:Int, y:Int, [flag:Bool]):Int

Get planet by location.

Returns the Id number of the planet at position (x,y). When flag is True (nonzero, nonempty), returns the planet whose gravity wells are in effect at that place; when flag is False or not specified at all, returns only exact matches. If there is no such planet, it returns zero.

Since: PCC 1.0.18, PCC2 1.99.9

See also: Functions

[Top]PlanetLock (Keymap)

 Bind PlanetLock key := command

Keys on this keymap are active when a planet is locked on the starchart. An unknown planet (nothing but location and name known) uses the UnknownPlanetLock keymap instead, which includes (derives from) this one.

This keymap includes (derives from) Starchart and Planet.

Since: PCC2 1.99.9

See also: Keymaps

[Top]PlanetName (Function)

PlanetName(pid:Int):Str

Get name of a planet.

Since: PCC 0.99.7, PCC2 1.99.8

See also: ShipName, Functions

[Top]PlanetScreen (Keymap)

 Bind PlanetScreen key := command

Keys on this keymap are active on the planet screen.

This keymap includes (derives from) ControlScreen and Planet.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Keymaps

[Top]PlanetTaskScreen (Keymap)

 Bind PlanetTaskScreen key := command

Keys on this keymap are active on the planet auto task screens.

This keymap includes (derives from) AutoTaskScreen.

Since: PCC2 1.99.16

See also: Keymaps

[Top]Planets (Player Property)

Planets:Int                                (read-only)

Number of planets this player has, according to score.

See also: Player Properties

[Top]Played - Disambiguation

There are multiple items with this name:

[Top]Played (Planet Property)

Played:Bool                                (read-only)

True if this planet is played.

Since: PCC 1.1.19

See also: Planet Properties

[Top]Played (Ship Property)

Played:Bool                                (read-only)

True if this ship is played.

Since: PCC 1.1.19

See also: Ship Properties

[Top]Player (Context, Function)

Player(uid:Int):Obj

Access player properties such as other players' race names and scores. Use as

 ForEach Player Do ...

or

 With Player(n) Do ...

Version Differences: This function was available for use in With under the name Players() since PCC 1.0.8. Do not use the name Players in new code, it is not supported by PCC2; use Player instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Player Properties, Contexts, Functions

[Top]Print (Elementary Command)

 Print item, ...
 Print #file:File, item, ...

Print text to console or file. Evaluates all parameters, concatenates them to a string, and prints them to the console. EMPTY values are ignored (but if all values are EMPTY, no line is printed at all).

With the second form, the line is written to the specified file.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]Put (Global Command)

Put #fd:File, v:Blob, [length:Int]

Write binary data. Writes the data block v into the file at the current position. If the length is specified (recommended), it determines the number of bytes to write. If the length is not specified, PCC writes as many bytes as the block contains.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]Quit (Hook)

 On Quit Do command

Commands registered for the Quit hook are run just before PCC closes.

Since: PCC 1.0.10, PCC2 1.99.25

See also: Hooks

[Top]RAdd (Function)

RAdd(args:RichText...):RichText

Concatenate all arguments, which can be strings or rich text, to a new rich text string, and returns that.

If any argument is EMPTY, returns EMPTY. If no arguments are given, returns an empty (=zero length) rich text string.

In text mode, this function produces plain strings instead, as rich text attributes have no meaning to the text mode applications.

Since: PCC2 1.99.21

See also: Functions

[Top]RLen (Function)

RLen(str:RichText):Int

Returns the number of characters in a rich text string.

If str is EMPTY, returns EMPTY.

In text mode, this function deals with plain strings instead, as rich text attributes have no meaning to the text mode applications.

Since: PCC2 1.99.21

See also: Functions

RLink(target:Str, content:RichText...):RichText

Attaches a link to a rich text string. Produces a rich text string that contains a link to the specified target, and the concatenation of all content parameters as text.

If any argument is EMPTY, returns EMPTY.

In text mode, this function just returns the concatenation of the content, as rich text attributes have no meaning to the text mode applications.

Since: PCC2 1.99.21

See also: RStyle, RXml, Functions

[Top]RMid (Function)

RMid(str:RichText, first:Int, [length:Int]):RichText

Returns a substring of a rich text string.

first specifies the first character position to extract, where 1 means the first. length specifies the number of characters to extract. If length is omitted or EMPTY, the remaining string is extracted.

If str or first are EMPTY, returns EMPTY.

In text mode, this function deals with plain strings instead, as rich text attributes have no meaning to the text mode applications.

Since: PCC2 1.99.21

See also: Functions

[Top]RString (Function)

RString(str:RichText):Str

Returns the text content of a rich text string, i.e. the string with all attributes removed.

If str is EMPTY, returns EMPTY.

In text mode, this function deals with plain strings instead, as rich text attributes have no meaning to the text mode applications.

Since: PCC2 1.99.21

See also: Functions

[Top]RStyle (Function)

RStyle(style:Str, content:RichText...):RichText

Attaches a new style to a rich text string. Concatenates all content parameters, and returns a new rich text string with the specified attribute added.

  RStyle("red", "This is ", RStyle("bold", "great"))

produces "This is great".

If any argument is EMPTY, returns EMPTY.

In text mode, this function just returns the concatenation of the content, as rich text attributes have no meaning to the text mode applications.

Styles: the style parameter can contain a list of comma-separated keywords. Keywords are a superset of tag and color names used in RXml.

b, bold, em bold font
big bigger font size
blue text color
dim text color
fixed, tt typewriter font
green text color
kbd, key keycaps (Like This)
none no style
red text color
small smaller font size
static default text color
u, underline underlined text
white text color
yellow text color

Since: PCC2 1.99.21

See also: RLink, RXml, Functions

[Top]RTrim (Elementary Function)

RTrim(s:Str):Str

Trim trailing (right) whitespace. Returns the string s with all trailing space and tab characters removed.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.99, PCC2 1.99.8

See also: Trim, LTrim, Elementary Functions

[Top]RXml (Function)

RXml(xml:Str, args:Str...):RichText

Create rich text string from XML. Parses the xml string. Tags are converted into rich text attributes. Entity references of the form &<digits>; are replaced by the respective element from args, where the first element is &0;.

For example,

  RXml("<font color='&0;'>This is <b>&1;</b></font>",
       "red", "great")

produces This is great.

In text mode, this function uses a simpler XML parser, and returns a plain string, as rich text attributes have no meaning to the text mode applications.

XML format: the following XML tags are allowed. They are inspired by XHTML tags.

<a href="..."> Link
<b> Bold font
<big> Bigger font size
<br /> Line break
<em> Currently, bold font
<font color="..."> Text color; one of static (default), green, yellow, red, white, blue, dim.
<kbd>, <key> Key caps (Like This)
<small> Smaller font size
<tt> Typewriter font
<u> Underlined font

Note that PCC2 expects actual XML, not HTML, so you must write <br />, and you must otherwise match each opening tag with a closing tag.

Since: PCC2 1.99.21

See also: RStyle, RLink, Functions

[Top]Race (Player Property)

Race:Str                                   (read-only)

Full name of this player.

See also: Player Properties

[Top]Race$ (Player Property)

Race$:Int                                  (read-only)

Player number.

See also: Player Properties

[Top]Race.Adj (Player Property)

Race.Adj:Str                               (read-only)

Adjective name of this player.

See also: Player Properties

[Top]Race.Id (Player Property)

Race.Id:Int                                (read-only)

Race assigned to this player.

See also: Player Properties

[Top]Race.Mission (Player Property)

Race.Mission:Int                           (read-only)

Special mission assigned to this player.

See also: Player Properties

[Top]Race.Short (Player Property)

Race.Short:Str                             (read-only)

Short name of this player.

See also: Player Properties

[Top]RaceScreen (Keymap)

 Bind RaceScreen key := command

Keys on this keymap are active on the race screen (player main menu).

This keymap includes (derives from) Global.

Since: PCC 1.1.17, PCC2 1.99.9

See also: Keymaps

[Top]Radius - Disambiguation

There are multiple items with this name:

[Top]Radius (Drawing Property)

Radius:Int                                 (read/write)

Radius of drawing. Valid for circles, EMPTY for others.

See also: Drawing Properties

[Top]Radius (Storm Property)

Radius:Int                                 (read-only)

Ion storm radius in ly.

See also: Storm Properties

[Top]Radius (Minefield Property)

Radius:Int                                 (read-only)

Minefield radius in ly.

See also: Minefield Properties

[Top]Radius (Ufo Property)

Radius:Int                                 (read-only)

Radius of Ufo in ly.

See also: Ufo Properties

[Top]Random (Function)

Random(a:Int, [b:Int]):Int

Generate random number. With one parameter, generates a random number in range [0,a) (i.e. including zero, not including a). With two parameters, generates a random number in range [a,b) (i.e. including a, not including b).

For example, Random(10) generates random numbers between 0 and 9, as does Random(0, 10).

Random(1,500) generates random numbers between 1 and 499, Random(500,1) generates random numbers between 2 and 500 (the first parameter always included in the range, the second one is not).

Since: PCC 1.0.7, PCC2 1.99.9

See also: Functions

[Top]RandomFCode (Function)

RandomFCode():Str

Generate a random friendly code. The friendly code will not have a special meaning.

Since: PCC 1.1.11, PCC2 1.99.8

See also: Functions

[Top]ReDim (Elementary Command)

ReDim name(dims),...

Resize an array.

The name is the name of an array variable. dims are the new dimensions, as a list of integer expressions.

Note that you can change the size of the array, but not the number of dimensions: a one-dimensional array will stay one-dimensional, and accept only ReDim commands that specify one dimension.

Current values in the array are kept if their position also exists in the new array. If you enlarge the array, new positions are filled with EMPTY. If you shrink the array, excess positons are deleted.

For example:

 Dim a(10)         % Make array with 10 elements
 ReDim a(20)       % Make it have 20 elements

Changing an array's first (or only) dimension is very efficient. Changing the shape of an array will have to move data around and therefore be slow.

Since: PCC2 1.99.22

See also: Elementary Commands

[Top]RecycleShip - Disambiguation

There are multiple items with this name:

[Top]RecycleShip (Planet Command)

RecycleShip sid:Int

Recycle a ship. The sid is a ship Id, or 0 to cancel a pending shipyard order.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Planet Commands

[Top]RecycleShip (Ship Command)

RecycleShip

Recycle this ship at the starbase. Changes the base's order to recycle this ship.

Since: PCC 1.0.5, PCC2 1.99.9

See also: FixShip (Planet Command), Ship Commands

[Top]RecycleShipWait - Disambiguation

There are multiple items with this name:

[Top]RecycleShipWait (Ship Command)

RecycleShipWait

Recycle ship at starbase when possible. Waits until the order can be submitted (i.e. the starbase's shipyard is idle), then gives the order.

Although documented as a Ship and Planet command, this actually is a global command. When calling it from a ship, do not specify a parameter. When calling it from a planet, specify a ship Id.

Since: PCC 1.0.16, PCC2 1.99.21

See also: RecycleShip (Ship Command), RecycleShip (Planet Command), Ship Commands

[Top]RecycleShipWait (Planet Command)

RecycleShipWait id:Int

Recycle ship at starbase when possible. Waits until the order can be submitted (i.e. the starbase's shipyard is idle), then gives the order.

Although documented as a Ship and Planet command, this actually is a global command. When calling it from a ship, do not specify a parameter. When calling it from a planet, specify a ship Id.

Since: PCC 1.0.16, PCC2 1.99.21

See also: RecycleShip (Ship Command), RecycleShip (Planet Command), Planet Commands

[Top]Rest (Elementary Function)

Rest(delim:Str, list:Str):Str

Split string, return remainder.

Assuming that list is a string containing multiple fields, separated by delim, this function returns everything but the first field. For example,

   Rest(",", "cln,-57,Clone a ship")

returns "-57,Clone a ship". If the string does not contain the delimiter, this function returns EMPTY.

   Rest(",", "huh?")

Note that, by default, substring search is case-insensitive. Use StrCase to search case-sensitive.

If any parameter is EMPTY, this function returns EMPTY.

Since: PCC 1.0.17, PCC2 1.99.8

See also: First, Elementary Functions

[Top]Restart (Elementary Command)

This is not an actual script command. It can only be used in auto tasks. It causes the auto task to start again from the beginning.

Since: PCC 1.0.19, PCC2 1.99.16

See also: Elementary Commands

[Top]Return (Elementary Command)

Return [value:Any]

Return from subroutine or function.

If used within a subroutine, there must not be a parameter. The subroutine returns when this command is executed.

If used within a function, the parameter must be specified. The function returns when this command is executed, and gives the value to its caller.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Sub, Function, Elementary Commands

[Top]Right - Disambiguation

There are multiple items with this name:

[Top]Right (Elementary Function)

Right(s:Str, n:Int):Str

Get ending (right) part of a string. Returns the last n characters of string s.

If any parameter is EMPTY, returns EMPTY. If n is negative, returns an empty string.

Since: PCC 0.99.2, PCC2 1.99.8

See also: Elementary Functions

[Top]Round (Elementary Function)

Round(n:Num):Int

Round to integer. If the parameter is a floating-point (fractional) number, it is rounded using the usual arithmetic rules: .5 or higher rounds up towards infinity, below rounds down towards 0. If the parameter already is an integer, it is returned as is.

Examples:

   Round(2.5) = 3
   Round(-2.5) = -3

If the parameter is EMPTY, this function returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Int, Elementary Functions

[Top]Run (Listbox Command)

Run

Shows the list box and let the user select an item. If the user confirms the selection, the chosen item's id is stored in UI.Result. If the user cancels, UI.Result is set to EMPTY.

Since: PCC 1.1.1, PCC2 1.99.25

See also: Listbox(), Listbox Commands

[Top]RunHook (Elementary Command)

RunHook event:Hook

Run hook commands. Executes the commands registered for the event using On. The event is an identifier. If no commands are registered for that event, nothing happens.

Since: PCC 1.0.9, PCC2 1.99.9

See also: Elementary Commands

[Top]SaveGame (Global Command)

SaveGame

Save current game.

See also: Global Commands

[Top]Scanned (Minefield Property)

Scanned:Int                                (read-only)

Last reported action on this minefield.

0 Not scanned this turn
1 Laid this turn
2 Swept this turn
3 Scanned this turn

See also: Minefield Properties

[Top]Score - Disambiguation

There are multiple items with this name:

[Top]Score (Player Property)

Score:Int                                  (read-only)

This player's Tim-score.

See also: Player Properties

[Top]Score (Planet Property, Ship Property)

Score:Int()                                (read-only)

Get unit's score of a given type.

PHost can associate various scores with ships and planets (utilX.dat records 49 and 50). This property makes these scores available to scripts. Valid parameters can be found in the PHost documentation. As of PHost 4.1, the following values are valid:

This property yields EMPTY if the respective score does not exist or is not known.

Since: PCC 1.1.16, PCC2 1.99.21

See also: Planet Properties, Ship Properties

[Top]Score.Freighters (Player Property)

Score.Freighters:Int                       (read-only)

Number of freighters this player has, according to score.

See also: Player Properties

[Top]Seed (Combat Property)

Seed:Int                                   (read-only)

Random number seed. Valid only for classic combat, EMPTY for others.

See also: Combat Properties

[Top]Seek (Global Command)

Seek #fd:File, pos:Int

Go to position in file.

Since: PCC 1.0.13, PCC2 1.99.12

See also: FPos(), FSize(), Global Commands

[Top]Select (Elementary Command)

 Select Case expr
   Case value, value...
     commands
   Case Is <= value
     commands
   Case Else
     commands
 EndSelect

Multi-part decision. The expression expr is evaluated and compared to each of the Case blocks. The first matching block's commands are executed.

There can be any number of Case branches, each of which lists a number of values to match. For example,

 Case 1, 3, 5

matches numbers one, three or five. Using the Is keyword, you can also match on relations, as in

 Case Is >= 9

which matches all numbers greater or equal than nine. Each Case can contain any number of selectors separated by comma. Although these examples all use integer numbers, you can also select on real numbers or strings.

Cases are evaluated from top to bottom, the first matching one is taken. If no case matches, the Case Else, if present, is run.

Values in Case expressions should be constants, although this is not currently enforced.

Example:

 Select Case i
   Case 1
     Print "one"
   Case 2,3,4
     Print "two to four"
   Case Is < 10
     Print "below ten, but not one to four"
   Case Else
     Print "anything else"
 EndSelect

Since: PCC 1.1.13, PCC2 1.99.9

See also: If, Elementary Commands

[Top]Selection.Layer (Global Property)

Selection.Layer:Int                        (read/write)

Current selection layer. A number from 0 to 7.

See also: Global Properties

[Top]SelectionExec (Elementary Command)

 SelectionExec [target :=] expr

Modify selection. Executes a selection expression, and assigns the result to target (or the current selection, if target is omitted).

The target must be a selection layer name, namely

For a description of the selection expression, see the Selection Manager help page.

Since: PCC 1.0.10, PCC2 1.99.10

See also: Elementary Commands

[Top]SelectionLayer (Global Command)

SelectionLayer l:Any

Change active selection layer. This is a convenience routine that accepts the parameter in multiple formats, namely a selection layer number (0-7) or name ("A"-"H").

Since: PCC 1.0.15, PCC2 1.99.10

See also: Global Commands

[Top]SelectionLoad (Global Command)

SelectionLoad file:File, [flags:Str]

Load selection from file.

The flags argument is a combination of the following options:

Since: PCC 1.1.3, PCC2 1.99.13

See also: SelectionSave, Selection.Layer, Global Commands

[Top]SelectionSave (Global Command)

SelectionSave file:File, [flags:Str]

Save selection into file.

The flags argument is a combination of the following options:

Since: PCC 1.1.3, PCC2 1.99.13

See also: SelectionLoad, Selection.Layer, Global Commands

[Top]SellSupplies (Planet Command)

SellSupplies amount:Int, [flags:Str]

Sell or buy supplies. Sells the specified number of supplies (for one megacredit each), or buys supplies if count is negative. You can only buy back supplies you sold this turn. Fails if you don't own the planet, or the rules forbid you to buy/sell the specified amount (because you don't have enough, maybe).

Optionally, you can specify the flag "n", as in

 SellSupplies 1000, "n"

When you can't sell/buy the specified amount, this will sell as much as possible instead of failing. The variable Build.Remainder will be set to the amount that was not sold. For example, if the planet on which you run the above command only has 650 supplies, Build.Remainder will be set to 350.

Since: PCC 1.0.19, PCC2 1.99.9

See also: Planet Commands

[Top]SetByte (Global Command)

SetByte v:Blob, pos:Int, value:Int...

Store bytes into blob. Packs the value arguments into the blob v, one byte per element, starting at position pos. The first position in the blob has index 0.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]SetColonistTax (Planet Command)

SetColonistTax n:Int

Set colonist tax.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Colonists.Tax, Planet Commands

[Top]SetColor (Drawing Command)

SetColor c:Int

Set drawing color.

Since: PCC 1.0.14, PCC2 1.99.20

See also: Color (Drawing Property), Drawing Commands

[Top]SetComment - Disambiguation

There are multiple items with this name:

[Top]SetComment (Drawing Command)

SetComment s:Str

Set drawing comment.

Since: PCC 1.0.14, PCC2 1.99.20

See also: Comment (Drawing Property), Drawing Commands

[Top]SetComment (Planet Command)

SetComment s:Str

Set planet comment.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Comment (Planet Property), Planet Commands

[Top]SetComment (Ship Command)

SetComment s:Str

Set ship comment.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Comment (Ship Property), Ship Commands

[Top]SetEnemy (Ship Command)

SetEnemy n:Int

Set ship primary enemy. n is an integer, either 0 (=no enemy) or 1..11 (player).

Since: PCC 1.0.5, PCC2 1.99.9

See also: Enemy$ (Ship Property), Ship Commands

[Top]SetFCode - Disambiguation

There are multiple items with this name:

[Top]SetFCode (Planet Command)

SetFCode fc:Str

Set planet friendly code.

Since: PCC 1.0.5, PCC2 1.99.9

See also: FCode (Planet Property), Planet Commands

[Top]SetFCode (Ship Command)

SetFCode fc:Str

Set ship friendly code.

Since: PCC 1.0.5, PCC2 1.99.9

See also: FCode (Ship Property), Ship Commands

[Top]SetFleet (Ship Command)

SetFleet fid:Int

Sets the fleet this ship is member of. fid can be one of the following:

If you're putting the ship into a fleet, but it is already member of a different one, it leaves its old fleet first (as if you had written SetFleet 0). This makes a difference when you're putting a fleet leader into another fleet.

See also: Fleet$ (Ship Property), Ship Commands

[Top]SetFleetName (Ship Command)

SetFleetName name:Str

Change fleet name. This ship must be member of a fleet to use this command. The fleet's name will be changed to name.

Since: PCC 1.0.14, PCC2 1.99.17

See also: Ship Commands

[Top]SetLong (Global Command)

SetLong v:Blob, pos:Int, value:Int...

Store longs into blob. Packs the value arguments into the blob v, four bytes (32 bits) per element, starting at position pos. The first position in the blob has index 0.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]SetMission - Disambiguation

There are multiple items with this name:

[Top]SetMission (Planet Command)

SetMission number:Int

Set starbase mission.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Planet Commands

[Top]SetMission (Ship Command)

SetMission m:Int, [i:Int, t:Int]

Set ship mission. m is the mission number, i and t are the Intercept and Tow parameters, respectively.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Mission$ (Ship Property), Mission.Intercept, Mission.Tow, Ship Commands

[Top]SetName (Ship Command)

SetName n:Str

Set ship name.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Name (Ship Property), Ship Commands

[Top]SetNativeTax (Planet Command)

SetNativeTax n:Int

Set native tax.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Natives.Tax, Planet Commands

[Top]SetSpeed (Ship Command)

SetSpeed sp:Int

Set ship warp speed. sp is an integer between 0 and 9.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Speed$ (Ship Property), Ship Commands

[Top]SetStr (Global Command)

SetStr v:Blob, pos:Int, length:Int, str:Int

Store string into blob. The string is converted to the game character set, padded with spaces or truncated to match the length, and then stored into the blob v starting at position pos. The first position in the blob has index 0.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]SetTech (Planet Command)

SetTech area:Int, level:Int

Set starbase tech level. area is 1 for engines, 2 for hulls, 3 for beams, 4 for torpedoes. level is the new tech level.

Note that when you build a ship, PCC automatically upgrades tech. You can raise tech levels, and lower them again when you have not yet used them.

Since: PCC 1.1, PCC2 1.99.9

See also: Planet Commands

[Top]SetWaypoint (Ship Command)

SetWaypoint x:Int, y:Int

Change the ship's waypoint. When playing on a wrapped map, this sets the waypoint to move the shortest possible way to the specified coordinates.

Since: PCC 1.0.5, PCC2 1.99.9

See also: MoveTo, Ship Commands

[Top]SetWord (Global Command)

SetWord v:Blob, pos:Int, value:Int...

Store words into blob. Packs the value arguments into the blob v, two bytes (16 bits) per element, starting at position pos. The first position in the blob has index 0.

Since: PCC 1.0.13, PCC2 1.99.12

See also: Global Commands

[Top]Shape (Drawing Property)

Shape:Int                                  (read/write)

Marker shape. Valid for markers, EMPTY for others.

See also: Drawing Properties

[Top]Shared (Elementary Command)

Shared name [initializer],...

Create a local variable. Same as Dim Shared, see there.

Since: PCC 1.0.6, PCC2 1.99.8

See also: Elementary Commands

[Top]Shield (Combat Participant Property)

Shield:Int                                 (read-only)

Initial shield level in percent.

See also: Combat Participant Properties

[Top]Ship - Disambiguation

There are multiple items with this name:

[Top]Ship (Keymap)

 Bind Ship key := command

Keys on this keymap are active whenever focus is on a ship.

Since: PCC 1.1.17, PCC2 1.99.9

See also: Keymaps

[Top]Ship (Context, Function)

Ship(sid:Int):Obj

Access starship properties. Use as

 ForEach Ship Do ...

or

 With Ship(n) Do ...

Version Differences: This function was available for use in With under the name Ships() since PCC 1.0.6. Do not use the name Ships in new code, it is not supported by PCC2; use Ship instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Ship Properties, Ship Commands, Contexts, Functions

[Top]ShipBuildScreen (Keymap)

 Bind ShipBuildScreen key := command

Keys on this keymap are active on the ship build screen.

This keymap includes (derives from) Global.

Note: This functionality does not exist in PCC2. Although keys can be defined, they will not be honored.

Since: PCC 1.0.15

See also: Keymaps

[Top]ShipLock (Keymap)

 Bind ShipLock key := command

Keys on this keymap are active when a ship is locked on the starchart.

This keymap includes (derives from) Starchart and Ship.

Since: PCC2 1.99.9

See also: Keymaps

[Top]ShipName (Function)

ShipName(sid:Int):Str

Get name of a ship. Similar to Ship(sid).Name.

Version Differences: In PCC 1.x, this function returns a decorated name such as "USS Lincoln (#123)". In PCC2 since 1.99.20, this function returns just the name. Use ShipNameAndId for the old behaviour.

Since: PCC 0.99.7, PCC2 1.99.8

See also: ShipNameAndId, PlanetName, Functions

[Top]ShipNameAndId (Function)

ShipNameAndId(sid:Int):Str

Get name of a ship, together with its Id.

Note that this function does what ShipName does in PCC 1.x. In PCC2, ShipName returns just the plain name which I believe is more useful and consistent with PlanetName. Code that used ShipName can now use ShipNameAndId.

Since: PCC2 1.99.20

See also: ShipName, Functions

[Top]ShipScreen (Keymap)

 Bind ShipScreen key := command

Keys on this keymap are active on the ship screen.

This keymap includes (derives from) ControlScreen and Ship.

Since: PCC 1.0.12, PCC2 1.99.9

See also: Keymaps

[Top]ShipTaskScreen (Keymap)

 Bind ShipTaskScreen key := command

Keys on this keymap are active on the ship auto task screens.

This keymap includes (derives from) AutoTaskScreen.

Since: PCC2 1.99.16

See also: Keymaps

[Top]Ships (Player Property)

Ships:Int                                  (read-only)

Number of ships this player has, according to score.

See also: Player Properties

[Top]Ships.Capital (Player Property)

Ships.Capital:Int                          (read-only)

Number of capital ships this player has, according to score.

See also: Player Properties

[Top]Ships.Freighters (Global Property)

Ships.Freighters:Int                       (read-only)

Total number of freighters (from this player's score information).

See also: Global Properties

[Top]Ships.Total (Global Property)

Ships.Total:Int                            (read-only)

Total number of ships (from this player's score information).

See also: Global Properties

[Top]Shipyard (Planet Property)

Shipyard:Str                               (read-only)

Shipyard order in human-readable form. A combination of Shipyard.Action and Shipyard.Name. EMPTY if no base, or no shipyard order set.

See also: Planet Properties

[Top]Shipyard.Action (Planet Property)

Shipyard.Action:Str                        (read-only)

Shipyard action on base. One of "Fix" or "Recycle". EMPTY if no base, or no shipyard order set.

See also: Planet Properties

[Top]Shipyard.Id (Planet Property)

Shipyard.Id:Int                            (read-only)

Id of ship being worked on by starbase. EMPTY if no base.

See also: Planet Properties

[Top]Shipyard.Name (Planet Property)

Shipyard.Name:Str                          (read-only)

Name of ship being worked on by starbase. EMPTY if no base, or no shipyard order set.

See also: Planet Properties

[Top]Sin (Elementary Function)

Sin(x:Num):Num

Compute the sine of an angle. The angle x is specified in degrees (not radians as many other programming languages). The result is a value between -1 and +1.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Cos, Tan, Elementary Functions

[Top]Size (File Property)

Size:Int                                   (read-only)

Size of the item (file) in bytes. EMPTY if the property is requested for an item that does not have a size (e.g. a directory).

Since: PCC2 2.0.4

See also: FSize(), File Properties

[Top]Special (Hull Property)

Special:Str                                (read-only)

Special function summary. This is a string identifying the major special functions of this hull. The string will contain each letter if and only if the hull has the respective ability assigned for all players.

See also: Hull Properties

[Top]Speed - Disambiguation

There are multiple items with this name:

[Top]Speed (Storm Property)

Speed:Str                                  (read-only)

Ion storm speed, as human-readable string.

See also: Storm Properties

[Top]Speed (Ship Property)

Speed:Str                                  (read-only)

Speed, as human-readable string. If the hyperdrive is active, reports "Hyperdrive", otherwise "Warp x".

See also: Ship Properties

[Top]Speed (Ufo Property)

Speed:Str                                  (read-only)

Speed, as human-readable string.

See also: Ufo Properties

[Top]Speed$ - Disambiguation

There are multiple items with this name:

[Top]Speed$ (Storm Property)

Speed$:Int                                 (read-only)

Ion storm speed (warp factor).

See also: Storm Properties

[Top]Speed$ (Ship Property)

Speed$:Int                                 (read/write)

Speed (warp factor).

See also: SetSpeed (Ship Command), Ship Properties

[Top]Speed$ (Engine Property)

Speed$:Int                                 (read-only)

Nominal speed of this engine. This is the speed PCC considers "optimal" for this engine. It defaults to the lowest speed at which the engine runs at 120% fuel consumption or less. You can assign a value between 1 and 9 to this property to change what PCC considers optimal.

Since: PCC 1.1.15, PCC2 1.99.8

See also: Engine Properties

[Top]Speed$ (Ufo Property)

Speed$:Int                                 (read-only)

Speed (warp factor).

See also: Ufo Properties

[Top]Sqr, Sqrt (Elementary Function)

Sqr(x:Num):Num
Sqrt(x:Num):Num

Square root. Returns the square root of its argument, i.e. a number that, when multiplied by itself, returns the argument again. Square roots are defined for non-negative values only.

If the parameter is EMPTY, returns EMPTY.

This function can be used to compute distances using the Pythagorean theorem:

   dist := Sqrt(xDisplacement^2 + yDisplacement^2)

Note that PCC also offers a Distance function.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Elementary Functions

[Top]Starchart (Keymap)

 Bind Starchart key := command

Keys on this keymap are active on the starchart. When an object is locked, that object's keymap is active as well (ShipLock, PlanetLock, BaseLock, UnknownPlanetLock)).

This keymap includes (derives from) Global.

Since: PCC 1.0.15, PCC2 1.99.9

See also: Keymaps

[Top]Static (Elementary Command)

Static name [initializer],...

Create a static variable. Same as Dim Static, see there.

Since: PCC 1.0.6, PCC2 1.99.8

See also: Elementary Commands

[Top]Status - Disambiguation

There are multiple items with this name:

[Top]Status (Storm Property)

Status:Str                                 (read-only)

Ion storm status, as human-readable string.

See also: Storm Properties

[Top]Status (Combat Participant Property)

Status:Str                                 (read-only)

Battle result, from the point-of-view of this unit.

Computing the value for this property may involve playing the whole VCR, and thus take a considerable amount of time. Results are cached, so you'll only have to wait once.

See also: Combat Participant Properties

[Top]Status$ - Disambiguation

There are multiple items with this name:

[Top]Status$ (Storm Property)

Status$:Bool                               (read-only)

Ion storm status.

See also: Storm Properties

[Top]Status$ (Combat Participant Property)

Status$:Int                                (read-only)

Battle result, from the point-of-view of this unit. This is an integer:

See also: Combat Participant Properties

[Top]Stop (Elementary Command)

Stop

Suspend the process. The process will automatically be woken up periodically (normally, whenever you open your turn). This can be used to implement things like `Wait one turn':

 Local t = Turn
 Do While t = Turn
   Stop
 Loop

(this is precisely the definition of WaitOneTurn).

Suspended processes will be saved to disk. However, there are restrictions upon the suspended process:

As a general guideline, functions should not suspend, directly or indirectly.

When a script wakes up again, all sorts of things may have been changed (for example, a turn has passed). Local and static variables will be saved with the process (because they belong to it exclusively), shared variables will not be saved.

When the script executes in a context that no longer exists, it will not be restored. PCC will not wake up scripts when you temporarily switched back to an earlier turn.

Since: PCC 1.0.7, PCC2 1.99.10

See also: Elementary Commands

[Top]Storage.Ammo (Planet Property)

Storage.Ammo:Int()                         (read-only)

Number of torpedoes or fighters in starbase storage. Index can be 0 (=total number of weapons), a torpedo type (=number of torpedoes of that type), or 11 (=number of fighters, see Fighters (Planet Property). EMPTY if no base.

See also: Planet Properties

[Top]Storage.Beams (Planet Property)

Storage.Beams:Int()                        (read-only)

Number of beams in starbase storage. Index can be 0 (=total number of beams) or a beam type (=number of beams of that type). EMPTY if no base.

See also: Planet Properties

[Top]Storage.Engines (Planet Property)

Storage.Engines:Int()                      (read-only)

Number of engines in starbase storage. Index can be 0 (=total number of engines) or an engine type (=number of engines of that type). EMPTY if no base.

See also: Planet Properties

[Top]Storage.Hulls (Planet Property)

Storage.Hulls:Int()                        (read-only)

Number of engines in starbase storage. Index can be 0 (=total number of hulls) or a hull type (=number of engines of that type). EMPTY if no base.

See also: Planet Properties

[Top]Storage.Launchers (Planet Property)

Storage.Launchers:Int()                    (read-only)

Number of torpedo launchers in starbase storage. Index can be 0 (=total number of launchers) or a torpedo type (=number of launchers of that type). EMPTY if no base.

See also: Planet Properties

[Top]Storm (Context, Function)

Storm(id:Int):Obj

Access ion storm properties. Use as

 ForEach Storm Do ...

or

 With Storm(n) Do ...

Version Differences: This function was available for use in With under the name Storms() since PCC 1.0.11. Do not use the name Storms in new code, it is not supported by PCC2; use Storm instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Storm Properties, Storm Commands, Contexts, Functions

[Top]Str (Elementary Function)

Str(x:Any, [precision:Int]):Str

Convert to string. Returns a string containing a human-readable representation of x. If the precision argument is specified, it defines the number of fractional decimal places to use for numbers. If it is not specified, the same conversion as for the Print command or the "&" operator is used.

If any parameter is EMPTY, this function returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Elementary Functions

[Top]StrCase (Elementary Function)

StrCase(x:Expr):Any

Case-sensitive evaluation. By default, string comparisons and substring searches are case-insensitive. The StrCase function causes the expression x to be evaluated in case-sensitive mode. For example,

   "a" = "A"           % True
   StrCase("a" = "A")  % False

Note that case-sensitivity only applies to operations that happen directly in the expression x. If x calls a user-defined function, that function's body operates case-insensitive again.

Since: PCC 1.0.4, PCC2 1.99.8

See also: Elementary Functions

[Top]String, String$ (Elementary Function)

String(n:Int, [s:Str]):Str
String$(n:Int, [s:Str]):Str

Replicate string. Returns a string that contains n copies of s. If s is not specified, returns a string containing n spaces.

If any parameter is EMPTY, this function returns EMPTY.

Since: PCC 0.98.5, PCC2 1.99.8

See also: Elementary Functions

[Top]Struct (Elementary Command)

 Struct name
   field [initializer], field [initializer], ...
 EndStruct

Define a structure. A structure is a blueprint for a series of objects with an identical set of properties.

Lines after the Struct keyword define the properties (fields) that are part of the structure. Each line defines one or more fields, separated by commas.

A structure is instantiated with Dim:

 Struct Pair
   First, Second
 EndStruct
 Dim p As Pair
 p->First := 1          % Set a field
 With p Do Second := 2  % Alternative version

Each field can have an optional initializer. See Dim for allowed forms of initializers. The initializer defines the initial value of the structure field. If no initializer is given, the field starts out EMPTY.

Internally, a structure is implemented as a constructor function. Instead of using Dim...As, you could also call the constructor function directly: p := Pair().

Since: PCC2 1.99.19

See also: Dim, Elementary Commands

[Top]Sub (Elementary Command)

 Sub name(param, param, Optional param, rest())
   commands
 EndSub

Define a subroutine. The subroutine can take parameters. The names of these parameters are specified in parentheses after the subroutine name.

If one parameter is preceded by Optional, all parameters following it are optional and can be omitted by the caller. They will report EMPTY when read.

The last parameter can be followed by (). This allows the caller to specify any number of values (including none at all) for this parameter, which will be packed into an array (making this a "varargs subroutine", for C programmers).

A subroutine can be called by listing its name, followed by the parameters:

 Sub test(a)
   Print a
 EndSub
 test "hello, world"

If there already is a subroutine or function with the same name as this subroutine, it will be replaced by the new definition.

Version Differences: PCC 1.x does not support the rest() form.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Function, Elementary Commands

[Top]Supplies (Planet Property)

Supplies:Int                               (read-only)

Supplies on this planet.

See also: Planet Properties

[Top]System.Err (Global Variable)

System.Err:Str                             (read/write)

Error message. If a command within a Try statement generates an error, the error message is stored in this variable. The Else part of the Try statement can therefore look at the message, or re-throw the error using Abort.

If a local variable System.Err is visible, the error message is stored in that instead of the global one.

Version Differences: In PCC 1.x, System.Err is a global property; the error message is always stored in the global property, and a local System.Err is ignored.

See also: Global Variables

[Top]System.ExitClient (Global Command)

System.ExitClient

Leave PCC2. Saves the game and closes the program. This command will also terminate the current process (as if the End command had been used).

Since: PCC2 1.99.26

See also: Global Commands

[Top]System.ExitRace (Global Command)

System.ExitRace

Leave current race. Saves the game and returns to the game selection menu.

Since: PCC2 1.99.10

See also: Global Commands

[Top]System.GUI (Global Property)

System.GUI:Bool                            (read-only)

Graphical interface flag. True if PCC is running with graphical interface, False if it is running in console mode.

See also: Global Properties

[Top]System.GameDirectory (Global Property)

System.GameDirectory:Str                   (read-only)

Game directory. EMPTY when no game loaded.

The game directory is the directory containing the current game's files.

Version Differences: In PCC 1.x, it is possible to concatenate this property with a file name to access a file in the game directory. This does no longer work in PCC2. Use the MakeFileName function, as in

 Open MakeFileName(System.GameDirectory, "file.txt") For Input As #1

to access files in the game directory.

See also: Global Properties

[Top]System.GameType (Global Property)

System.GameType:Str                        (read-only)

Registration flag. One of "Shareware" or "Registered".

See also: Global Properties

[Top]System.GameType$ (Global Property)

System.GameType$:Bool                      (read-only)

Registration flag. True if you use a shareware key (Tech 6 limit), False if you use a full version.

See also: Global Properties

[Top]System.Host (Global Property)

System.Host:Str                            (read-only)

Name of Host program. Values in use so far:

See also: Global Properties

[Top]System.Host$ (Global Property)

System.Host$:Int                           (read-only)

Name of Host program. Values in use so far:

System.Host System.Host$
Host 0
SRace 1
PHost 2

You should prefer using System.Host instead.

See also: Global Properties

[Top]System.HostVersion (Global Property)

System.HostVersion:Int                     (read-only)

Host version number. The version number is converted to a number, with three digits fo the patchlevel and two for the minor version. If the respective host version uses letters to specify the patchlevel, "a" is 1, "b" is 2, and so on. PCC2 also knows that some host versions use "3.1" to actually mean "3.10". Examples:

Version Value
3.22.20 322020
3.15 315000
3.5c 305003

See also: Global Properties

[Top]System.Language (Global Property)

System.Language:Str                        (read-only)

Language code. This is the language the user wants to use, usually in the form of a two-letter ISO 639 code ("en" = English).

Since: PCC2 1.99.25

See also: Global Properties

[Top]System.Local (Global Property)

System.Local:Str                           (read-only)

Local file format. Reports the file format PCC uses to store your player files:

See also: Global Properties

[Top]System.Plugin (Function)

System.Plugin(id:Str):Obj

Accesses the properties of the plugin given by the name Id. If no such plugin was loaded, returns EMPTY.

Since: PCC2 1.99.25

See also: Plugin Properties, Functions

[Top]System.Program (Global Property)

System.Program:Str                         (read-only)

Name of the program executing the script. Values in use so far:

See also: Global Properties

[Top]System.RandomSeed (Global Property)

System.RandomSeed:Int                      (read/write)

Random number generator seed. Using the same seed, you can reproduce the same random number sequence. The seed is a full 32-bit value.

The underlying random number generator is undocumented as of now, and has nothing to do with the random number generators used in VCR/PVCR. It is not guaranteed that the same random number generator will be used throughout all versions of PCC.

See also: Random, Global Properties

[Top]System.RegStr1 (Global Property)

System.RegStr1:Str                         (read-only)

Your registration key. This is the first line (name or registration number) of the key.

See also: Global Properties

[Top]System.RegStr2 (Global Property)

System.RegStr2:Str                         (read-only)

Your registration key. This is the second line (registration number or date) of the key.

See also: Global Properties

[Top]System.Remote (Global Property)

System.Remote:Str                          (read-only)

Remote file format. Reports the file format PCC uses for your turn files, i.e. what the "remote" host system sees:

See also: Global Properties

[Top]System.RootDirectory (Global Property)

System.RootDirectory:Str                   (read-only)

Root directory.

The root directory is the directory within the program installation directory containing the default specification files. If a specification file cannot be found in the game directory, it is looked for in the root directory. This directory typically is one of

Version Differences: In PCC 1.x, it is possible to concatenate this property with a file name to access a file in the root directory. This does no longer work in PCC2. Use the MakeFileName function, as in

 Open MakeFileName(System.RootDirectory, "file.txt") For Input As #1

to access files in the root directory.

See also: Global Properties

[Top]System.Sim (Global Property)

System.Sim:Bool                            (read-only)

True if the combat simulator is currently in use, otherwise false.

Since: PCC 1.0.9, PCC2 1.99.10

See also: Global Properties

[Top]System.Version (Global Property)

System.Version:Str                         (read-only)

Version number of the program executing the script. For example, "1.1.18", or "1.99.20".

See also: Global Properties

[Top]System.Version$ (Global Property)

System.Version$:Int                        (read-only)

Version number of the program executing the script. The version number has three digits for the "patchlevel" field, and two digits for the "minor" field. For example, "101018" or "199020" for "1.1.18" and "1.99.20", respectively.

See also: Global Properties

[Top]Tag (Drawing Property)

Tag:Int                                    (read/write)

Marker tag. Usually an integer created with Atom().

See also: Drawing Properties

[Top]Tan (Elementary Function)

Tan(x:Num):Num

Compute the tangent of an angle. The angle x is specified in degrees (not radians as many other programming languages). The result is a value between -1 and +1.

The tangent of 90° or 270° cannot be computed and produces an error.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.98.3, PCC2 1.99.8

See also: Sin, Cos, Elementary Functions

[Top]Task - Disambiguation

There are multiple items with this name:

[Top]Task (Planet Property)

Task:Bool                                  (read-only)

True if this planet has an Auto Task.

See also: Planet Properties

[Top]Task (Ship Property)

Task:Bool                                  (read-only)

True if this ship has an auto task.

See also: Ship Properties

[Top]Task.Base (Planet Property)

Task.Base:Bool                             (read-only)

True if this planet's starbase has an Auto Task.

See also: Planet Properties

[Top]Team (Player Property)

Team:Int                                   (read-only)

Team this player is in.

See also: Player Properties

[Top]Tech (Beam Property, Engine Property, Hull Property, Torpedo Property)

Tech:Int                                   (read-only)

Tech level of this component.

See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties

[Top]Tech.Beam - Disambiguation

There are multiple items with this name:

[Top]Tech.Beam (Planet Property)

Tech.Beam:Int                              (read-only)

Beam tech level on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Tech.Beam (Beam Property)

Tech.Beam:Int                              (read-only)

Tech level of this component.

See also: Beam Properties

[Top]Tech.Engine - Disambiguation

There are multiple items with this name:

[Top]Tech.Engine (Planet Property)

Tech.Engine:Int                            (read-only)

Engine tech level on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Tech.Engine (Engine Property)

Tech.Engine:Int                            (read-only)

Tech level of this component.

See also: Engine Properties

[Top]Tech.Hull - Disambiguation

There are multiple items with this name:

[Top]Tech.Hull (Planet Property)

Tech.Hull:Int                              (read-only)

Hull tech level on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Tech.Hull (Hull Property, Ship Property)

Tech.Hull:Int                              (read-only)

Hull tech level.

See also: Hull Properties, Ship Properties

[Top]Tech.Torpedo - Disambiguation

There are multiple items with this name:

[Top]Tech.Torpedo (Planet Property)

Tech.Torpedo:Int                           (read-only)

Torpedo tech level on starbase. EMPTY if no base.

See also: Planet Properties

[Top]Tech.Torpedo (Torpedo Property)

Tech.Torpedo:Int                           (read-only)

Tech level of this component.

See also: Torpedo Properties

[Top]Temp (Planet Property)

Temp:Int                                   (read-only)

Temperature class, human-readable.

See also: Planet Properties

[Top]Temp$ (Planet Property)

Temp$:Int                                  (read-only)

Temperature, numeric value.

See also: Planet Properties

[Top]Text (Incoming Message Property)

Text:Str()                                 (read-only)

Message text, line by line.

See also: Incoming Message Properties

[Top]Torp (Combat Participant Property, Ship Property)

Torp:Str                                   (read-only)

Torpedo type, full name.

See also: Combat Participant Properties, Ship Properties

[Top]Torp$ (Combat Participant Property, Ship Property)

Torp$:Int                                  (read-only)

Torpedo type.

See also: Combat Participant Properties, Ship Properties

[Top]Torp.Count (Combat Participant Property, Ship Property)

Torp.Count:Int                             (read-only)

Number of torpedoes on this ship. 0 if the ship has no torpedoes.

See also: Combat Participant Properties, Ship Properties

[Top]Torp.LCount (Combat Participant Property, Ship Property)

Torp.LCount:Int                            (read-only)

Number of torpedo launchers on this ship.

See also: Combat Participant Properties, Ship Properties

[Top]Torp.LMax (Hull Property, Ship Property)

Torp.LMax:Int                              (read-only)

Maximum number of torpedo launchers on this ship.

See also: Hull Properties, Ship Properties

[Top]Torp.Short (Combat Participant Property, Ship Property)

Torp.Short:Str                             (read-only)

Torpedo type, short name.

See also: Combat Participant Properties, Ship Properties

[Top]Torpedo (Context, Function)

Torpedo(id:Int):Obj

Access torpedo properties. Use as

 ForEach Torpedo Do ...

or

 With Torpedo(n) Do ...

Version Differences: This function was available for use in With under the name Torpedoes() since PCC 1.0.6. Do not use the name Torpedoes in new code, it is not supported by PCC2; use Torpedo instead.

Since: PCC 1.0.18, PCC2 1.99.8

See also: Torpedo Properties, Launcher(), Contexts, Functions

[Top]Total.Capital (Global Property)

Total.Capital:Int                          (read-only)

Total number of capital ships (from this player's score information).

See also: Global Properties

[Top]Transfer.Ship (Ship Property)

Transfer.Ship:Bool                         (read-only)

True if cargo is being transported to another ship.

See also: Ship Properties

[Top]Transfer.Ship.Colonists (Ship Property)

Transfer.Ship.Colonists:Int                (read-only)

Number of colonists being transferred to another ship.

See also: Ship Properties

[Top]Transfer.Ship.D (Ship Property)

Transfer.Ship.D:Int                        (read-only)

Amount of Duranium being transferred to another ship.

See also: Ship Properties

[Top]Transfer.Ship.Id (Ship Property)

Transfer.Ship.Id:Int                       (read-only)

Id of cargo transfer target ship.

See also: Ship Properties

[Top]Transfer.Ship.M (Ship Property)

Transfer.Ship.M:Int                        (read-only)

Amount of Molybdenum being transferred to another ship.

See also: Ship Properties

[Top]Transfer.Ship.N (Ship Property)

Transfer.Ship.N:Int                        (read-only)

Amount of Neutronium being transferred to another ship.

See also: Ship Properties

[Top]Transfer.Ship.Name (Ship Property)

Transfer.Ship.Name:Str                     (read-only)

Name of cargo transfer target ship.

See also: Ship Properties

[Top]Transfer.Ship.Supplies (Ship Property)

Transfer.Ship.Supplies:Int                 (read-only)

Amount of Supplies being transferred to another ship.

See also: Ship Properties

[Top]Transfer.Ship.T (Ship Property)

Transfer.Ship.T:Int                        (read-only)

Amount of Tritanium being transferred to another ship.

See also: Ship Properties

[Top]Transfer.Unload (Ship Property)

Transfer.Unload:Bool                       (read-only)

True if cargo is being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Transfer.Unload.Colonists (Ship Property)

Transfer.Unload.Colonists:Int              (read-only)

Number of colonists being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Transfer.Unload.D (Ship Property)

Transfer.Unload.D:Int                      (read-only)

Amount of Duranium being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Transfer.Unload.Id (Ship Property)

Transfer.Unload.Id:Int                     (read-only)

Id of planet cargo is being unloaded to. 0 for jettison.

See also: Ship Properties

[Top]Transfer.Unload.M (Ship Property)

Transfer.Unload.M:Int                      (read-only)

Amount of Molybdenum being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Transfer.Unload.N (Ship Property)

Transfer.Unload.N:Int                      (read-only)

Amount of Neutronium being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Transfer.Unload.Name (Ship Property)

Transfer.Unload.Name:Int                   (read-only)

Name of planet cargo is being unloaded to. "Jettison" for jettison.

See also: Ship Properties

[Top]Transfer.Unload.Supplies (Ship Property)

Transfer.Unload.Supplies:Int               (read-only)

Amount of Supplies being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Transfer.Unload.T (Ship Property)

Transfer.Unload.T:Int                      (read-only)

Amount of Tritanium being unloaded to a planet or deep space.

See also: Ship Properties

[Top]Translate (Function)

Translate(str:Str):Str

Translate a string. Uses PCC's internal language database to reproduce the English string given as parameter in the user's preferred language. If the string is not contained in the language database, returns the original string.

Since: PCC2 1.99.9

See also: Functions

[Top]Trim (Elementary Function)

Trim(s:Str):Str

Trim whitespace. Returns the string s with all leading and trailing space and tab characters removed.

If the parameter is EMPTY, returns EMPTY.

Since: PCC 0.99, PCC2 1.99.8

See also: LTrim, RTrim, Elementary Functions

[Top]Truehull (Function)

Truehull(slot:Int, [player:Int]):Int

Access per-player hull assignments. Returns the Id of the slot'th hull number the specified player can build. If the player parameter is omitted, uses your player slot. If the specified slot does not contain a buildable hull, returns 0.

Since: PCC 1.0.12, PCC2 1.99.8

See also: Functions

[Top]Try (Elementary Command)

 Try command

 Try
   commands
 Else
   commands
 EndTry

Catch errors. The commands after the Try are executed. If any command produces an error, either by doing something bad such as dividing by zero or using an undefined property, or by using the Abort command, the Else part is executed. If there is no Else part, the error is silently ignored.

In any case, the error message is assigned to the System.Err variable where it can be examined.

Version Differences: In PCC 1.x, System.Err is a global property. In PCC2, System.Err is a global variable, and you can define a local version of it to avoid modifying the global one.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]Turn (Global Property)

Turn:Int                                   (read-only)

Turn number.

See also: Global Properties

[Top]Turn.Date (Global Property)

Turn.Date:Str                              (read-only)

Turn date. Date of last host run, in mm-dd-yyyy format, using the host's timezone.

See also: Global Properties

[Top]Turn.IsNew (Global Property)

Turn.IsNew:Bool                            (read-only)

New-turn flag. True if this is a new turn, false if you have opened PCC for the second time this turn.

See also: Global Properties

[Top]Turn.Time (Global Property)

Turn.Time:Str                              (read-only)

Turn time. Time of last host run, in hh:mm:ss format, using the host's timezone and 24-hour format.

See also: Global Properties

[Top]Type - Disambiguation

There are multiple items with this name:

[Top]Type (File Property)

Type:Str                                   (read-only)

Type of this item. Contains "f" for regular files, "d" for directories. Other items can produce other values, or EMPTY.

Since: PCC2 2.0.4

See also: File Properties

[Top]Type (Drawing Property)

Type:Str                                   (read-only)

Type of drawing.

See also: Type$ (Drawing Property), Drawing Properties

[Top]Type (Minefield Property)

Type:Str                                   (read-only)

Minefield type, human-readable. One of "Web Mines" or "Mines".

See also: Minefield Properties

[Top]Type (Planet Property)

Type:Str                                   (read-only)

Always "Planet" for planets.

Since: PCC 1.1.20, PCC2 1.99.21

See also: Type (Ship Property), Type (Combat Participant Property), Planet Properties

[Top]Type (Ship Property)

Type:Str                                   (read-only)

Classification of ship. Possible values are:

See also: Ship Properties

[Top]Type (Ufo Property)

Type:Int                                   (read-only)

Type of Ufo. This is an integer reported by the add-on providing the Ufo, identifying the Ufo type.

See also: Ufo Properties

[Top]Type (Combat Participant Property)

Type:Str                                   (read-only)

Classification of this unit. Possible values are:

See also: Combat Participant Properties

[Top]Type$ - Disambiguation

There are multiple items with this name:

[Top]Type$ (Drawing Property)

Type$:Int                                  (read-only)

Type of drawing.

Type$ Type
0 Line
1 Rectangle
2 Circle
3 Marker

See also: Drawing Properties

[Top]Type$ (Minefield Property)

Type$:Bool                                 (read-only)

True if this is a web mine field.

See also: Minefield Properties

[Top]Type$ (Combat Property)

Type$:Int                                  (read-only)

Unit type identification value.

Valid only for classic combat, EMPTY for others.

See also: Combat Properties

[Top]Type.Short - Disambiguation

There are multiple items with this name:

[Top]Type.Short (Planet Property)

Type.Short:Str                             (read-only)

Always "P" for planets.

Since: PCC 1.1.20, PCC2 1.99.21

See also: Type.Short (Ship Property), Type.Short (Combat Participant Property), Planet Properties

[Top]Type.Short (Ship Property)

Type.Short:Str                             (read-only)

Classification of ship, short. This is the first letter of the Type, see there.

See also: Ship Properties

[Top]Type.Short (Combat Participant Property)

Type.Short:Str                             (read-only)

Classification of this unit, short. This is the first letter of the Type, see there.

See also: Combat Participant Properties

[Top]UI.ChooseObject (Global Command)

UI.ChooseObject screen:Int

Choose game object. You specify a screen number to choose the object for:

1, 11 Own starships
2, 12 Own planets
3, 13 Own starbases
6 History starships
10 Fleets

or example, UI.ChooseObject 1 does the same as the F1 key in most screens. hen there is just one ship, no dialog is displayed.

he chosen object Id is returned in UI.Result; the result is MPTY if the user canceled. his command does not work in text mode.

since PCC 1.1.1, PCC2 1.99.9

See also: Global Commands

[Top]UI.Directory (Global Variable)

UI.Directory:Str                           (read/write)

Current directory. This is the default directory for operations like UI.FileWindow.

See also: Global Variables

[Top]UI.EditAlliances (Global Command)

UI.EditAlliances

Alliance editor dialog. Brings up a dialog that allows the user to edit alliances. This command takes no further parameters.

Since: PCC2 1.99.23

See also: Global Commands

[Top]UI.FileWindow (Global Command)

UI.FileWindow title:Str, wildcard:Str, [helpId:Str]

File selection.

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

The file dialog uses the variable UI.Directory to initialize and store the current directory.

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

Version Differences: In PCC 1.x, the help Id is an integer. In PCC2, it is a string.

Since: PCC 1.0.15, PCC2 1.99.21

See also: Global Commands

[Top]UI.GotoChart (Global Command)

UI.GotoChart x:Int, y:Int

Go to starchart. This command activates the starchart at the specified position. 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

Since: PCC 1.0.14, PCC2 1.99.10

See also: UI.GotoScreen, Global Commands

[Top]UI.GotoScreen (Global Command)

UI.GotoScreen screen:Int, [id:Int]

Go to control screen. This command activates the specified screen. If the id is specified and valid, shows that object.

Id Screen
0 Race screen. You can not specify an id here.
1 Ship screen. id is a ship Id.
2 Planet screen. id is a planet Id.
3 Starbase screen. id is a starbase Id.
4 Starchart. You can not specify an id here. Also see UI.GotoChart.
6 Starship history. id is a ship Id.
10 Fleet screen. id is a fleet Id.
11 Ship auto task screen. id is a ship Id.
12 Planet auto task screen. id is a planet Id.
13 Starbase auto task screen. id is a starbase Id.

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

Since: PCC 1.0.14, PCC2 1.99.10

See also: UI.GotoChart, Global Commands

[Top]UI.Help (Global Command)

UI.Help page:Str

Open help screen. The help page name is passed as a parameter.

Version Differences: In PCC 1.x, it is a script error if the page does not exist. PCC2 silently displays an error page.

Since: PCC 1.0.15, PCC2 1.99.15

See also: Global Commands

[Top]UI.Input (Global Command)

UI.Input prompt:Str, [title:Str, max:Int, flags:Any,
  def:Str]

Text input.

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

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

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

he result is returned in UI.Result: f the user hits Enter, UI.Result contains the input. f the user hits ESC, UI.Result will be EMPTY.

xample: 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).

n text mode, this command makes a simple input line using the prompt only. since PCC 1.0.9, PCC2 1.99.9

See also: Global Commands

[Top]UI.InputFCode (Global Command)

UI.InputFCode flags:Any, [default:Str]

Ask for friendly code input. This uses the regular friendly code input window with a list of friendly code.

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

You should specify either "D", or 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. If the dialog is canceled, UI.Result will be EMPTY.

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

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

Version Differences: The "D" flag is supported in PCC2 only.

Since: PCC 1.0.17, PCC2 1.99.21

See also: Global Commands

[Top]UI.InputNumber (Global Command)

UI.InputNumber title:Str, [min:Int, max:Int,
  current:Int, help:Any]

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

The parameters are

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.

Since: PCC 1.1.16, PCC2 1.99.9

See also: Global Commands

[Top]UI.KeymapInfo (Global Command)

UI.KeymapInfo

Open keymap debugger for current keymap.

Since: PCC2 1.99.10

See also: Global Commands

[Top]UI.ListFleets (Global Command)

UI.ListFleets x:Int, y:Int, [flags:Any, ok:Str,
  heading:Str]

Choose a fleet. Lists all fleets at the specified x,y. If the user chooses one, returns their Id in UI.Result. If the user cancels the dialog using ESC, UI.Result is set to EMPTY.

The flags parameter modifies the function's behaviour:

Since: PCC2 1.99.17

See also: Global Commands

[Top]UI.ListShipPrediction (Global Command)

UI.ListShipPrediction x:Int, y:Int, [sid:Int, ok:Str,
  heading:Str]

List ship prediction (visual scanner).

Computes future positions of all (known) ships and lists all those that will be at x,y using the Visual Scan window. When the sid parameter is given and refers to a valid ship Id, uses that ship's predicted position instead of x,y.

The last three parameters are optional and modify behaviour details. The ok string specifies the name of the "OK" button, it defaults to "OK". Likewise, the heading specifies the window title, it defaults to "Ship Prediction".

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.

Since: PCC2 1.99.26

See also: UI.ChooseObject, UI.ListShips, Global Commands

[Top]UI.ListShips (Global Command)

UI.ListShips x:Int, y:Int, [flags:Any, ok:Str,
  heading:Str]

List ships (visual scanner).

Lists all ships at position x,y using the Visual Scan window. The last three parameters are optional and modify behaviour details.

The flags parameter contains a list of flag letters:

The ok string specifies the name of the "OK" button, it defaults to "OK". Likewise, the heading specifies the window title, it defaults to "List Ships".

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

Since: PCC 1.1.1, PCC2 1.99.10

See also: UI.ChooseObject, UI.ListShipPrediction, Global Commands

[Top]UI.Message (Global Command)

UI.Message text:RichText, [title:Str, buttons:Str]

Display a message. This displays a standard message box with the specified text and title, and the specified buttons. For example,

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

displays a message box with three buttons: "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.

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

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

Version Differences: PCC 1.x allows up to 10 buttons; PCC2 has no such limit (but you are adviced to keep the number of buttons and the length of the texts short anyway).

Since: PCC 1.0.9, PCC2 1.99.9

See also: MessageBox, UI.Input, Global Commands

[Top]UI.OverlayMessage (Global Command)

UI.OverlayMessage msg:Str

Display an overlay message. The message is shown centered on the screen, and automatically decays. Because it's not a window, the user doesn't have to explicitly confirm it. Use this for status updates from scripts that are not otherwise interactive. For example, this command is used to report changes of the current selection layer.

Since: PCC2 1.99.10

See also: Global Commands

[Top]UI.PlanetInfo (Global Command)

UI.PlanetInfo pid:Int

Open planet information for planet pid.

Since: PCC2 1.99.10

See also: Global Commands

[Top]UI.PopupConsole (Global Command)

UI.PopupConsole

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

Since: PCC 1.1.2, PCC2 1.99.10

See also: Global Commands

[Top]UI.Prefix (Global Variable)

UI.Prefix:Int                              (read/write)

Current prefix argument. In keyboard actions (commands bound to a key using Bind), this variable contains the current prefix argument (0 if none).

See also: Global Variables

[Top]UI.Result (Global Variable)

UI.Result:Str                              (read/write)

Result of last user-interface operation. Operations like UI.Message store their result in a variable UI.Result. If a local variable UI.Result is visible, the result is stored in that instead of the global one. It is therefore a good idea to define a local variable to capture results without disturbing or being disturbed by other scripts.

See also: Global Variables

[Top]UI.Screen (Global Property)

UI.Screen:Int                              (read-only)

Number of current screen. See UI.GotoScreen for a list. 0 if no control screen is active.

Since: PCC 1.0.14, PCC2 1.99.10

See also: UI.GotoScreen, Global Properties

[Top]UI.Search (Global Command)

UI.Search [query:Str, flags:Any]

Search.

When called with no parameters, just opens the Search dialog. When a search query is present, it is immmediately evaluated. The query parameter is the search string, the flags specify the kind of search:

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.

Since: PCC 1.1.2, PCC2 1.99.10

See also: Global Commands

[Top]UI.SelectionManager (Global Command)

UI.SelectionManager

Open selection manager.

Since: PCC2 1.99.10

See also: Global Commands

[Top]UI.Update (Global Command)

UI.Update [flag:Bool]

Update graphical user interface. This causes all the screen to be redrawn. With the flag specified as True, redraws even if there are no changes.

In console mode, this function does nothing.

Since: PCC 1.0.13, PCC2 1.99.9

See also: Global Commands

[Top]UI.X, UI.Y (Global Property)

UI.X:Int                                   (read/write)
UI.Y:Int                                   (read/write)

Scanner position.

Since: PCC 1.0.14, PCC2 1.99.10

See also: Global Properties

[Top]Ufo (Context, Function)

Ufo(uid:Int):Obj

Access Ufo properties. Use as

 ForEach Ufo Do ...

or

 With Ufo(n) Do ...

See also: Ufo Properties, Ufo Commands, Contexts, Functions

[Top]Unit (Combat Property)

Unit:Obj()                                 (read-only)

Information about all participating units. Each object in this array has Combat Participant Properties. Indexes are 1 to NumUnits.

The properties of Units(1) and Units(2) are also available as Combat Properties Left.XXX and Right.XXX, mainly for classic 1:1 combat.

Since: PCC2 1.99.19

See also: Combat Properties

[Top]Units (Minefield Property)

Units:Int                                  (read-only)

Number of mine units.

See also: Minefield Properties

[Top]UnknownPlanetLock (Keymap)

 Bind UnknownPlanetLock key := command

Keys on this keymap are active when an unknown planet (nothing but location and name known) planet is locked on the starchart.

This keymap includes (derives from) PlanetLock.

Since: PCC2 1.99.10

See also: Keymaps

[Top]Unmark (Minefield Command, Planet Command, Ship Command, Storm Command, Ufo Command)

Unmark

Unmark object. Unmarks the current object.

Version Differences: This command is also available for ufos, ion storms, and minefields since PCC2 1.99.13. Older versions and PCC 1.x only allow it for ships and planets.

Since: PCC 1.0.5, PCC2 1.99.9

See also: Mark, Minefield Commands, Planet Commands, Ship Commands, Storm Commands, Ufo Commands

[Top]Unpack (Hook)

 On Unpack Do command

Commands registered for the Unpack hook are run after result files have been unpacked.

Note: This functionality does not exist in PCC2.

Since: PCC 1.1.4

See also: Hooks

[Top]UnpackScan (Hook)

 On UnpackScan Do command

Commands registered for the UnpackScan hook are run just before PCC looks for new result files.

Note: This functionality does not exist in PCC2.

Since: PCC 1.1.4

See also: Hooks

[Top]UseKeymap (Global Command)

UseKeymap name:Keymap

Temporarily enable a secondary keymap. The next keypress will be processed according to the specified keymap instead of the normal keymap for the current place. This way, you can create multi-keystroke commands.

For example,

 CreateKeymap CtrlXMap
 Bind CtrlXMap 'C-s' := 'SaveGame'

will create a keymap CtrlXMap in which Ctrl-S invokes the SaveGame command. You can now bind that keymap to a key:

 Bind ControlScreen 'C-x' := 'UseKeymap CtrlXMap'

Now, the key sequence Ctrl-X Ctrl-S will save the game from any control screen.

Only one UseKeymap command can be active at a time. A second command will cancel the first.

This command does not wait for the keystroke to actually occur; it immediately proceeds execution of the script. The secondary keymap is used when PCC is waiting for input next time. As a reminder of the temporarily changed keybindings, a pop-up message will occur after little idle time, or when a key is pressed which is not bound in the keymap. As a quick way out, ESC cancels the secondary keymap, unless ESC is bound in it.

It is recommended that you only bind direct invocations of UseKeymap to keys. In particular, the keymap debugger can then help you to look at these alternate keymaps. Although it is possible to call UseKeymap from subroutines, you should avoid that if you can. In particular, you should not call any complicated user-interface command after UseKeymap; this will not always do what you want.

Since: PCC 1.1.10, PCC2 1.99.22

See also: Global Commands

[Top]Val (Elementary Function)

Val(s:Str):Num

Convert string to number. Attempts to interpret the string as a number, and returns that. If the string does not look like a number, returns EMPTY (leading and trailing whitespace is OK, though).

Since: PCC 0.99.6, PCC2 1.99.8

See also: Elementary Functions

[Top]Value (Hash Element Property)

Value:Any                                  (read/write)

The value of this hash element.

See also: Hash Element Properties

[Top]Vcr (Context, Function)

Vcr(uid:Int):Obj

Access properties of combat recordings. Use as

 ForEach Vcr Do ...

or

 With Vcr(n) Do ...

See also: Combat Properties, Contexts, Functions

[Top]Visible.Planet (Ufo Property)

Visible.Planet:Int                         (read-only)

Distance from which Ufo can be seen from a planet, in ly.

See also: Ufo Properties

[Top]Visible.Ship (Ufo Property)

Visible.Ship:Int                           (read-only)

Distance from which Ufo can be seen from a ship, in ly.

See also: Ufo Properties

[Top]Voltage (Storm Property)

Voltage:Int                                (read-only)

Ion storm voltage, in MeV.

See also: Storm Properties

[Top]WaitOneTurn (Global Command)

WaitOneTurn

Suspend script for one turn. Execution proceeds next turn (or later, when a turn is missed). See Stop for details and restrictions on suspension.

Since: PCC 1.0.6, PCC2 1.99.10

See also: Stop, Global Commands

[Top]Waypoint (Ship Property)

Waypoint:Str                               (read-only)

Waypoint, as a human-readable string. Version Differences: For ships on intercept course, PCC2 version 2.0.7 and later as well as PCC 1.x will return the name of the intercept target. Earlier PCC2 versions only return the name of the location (planet or X,Y's).

See also: Ship Properties

[Top]Waypoint.DX (Ship Property)

Waypoint.DX:Int                            (read-only)

X distance to waypoint.

See also: Ship Properties

[Top]Waypoint.DY (Ship Property)

Waypoint.DY:Int                            (read-only)

Y distance to waypoint.

See also: Ship Properties

[Top]Waypoint.Dist (Ship Property)

Waypoint.Dist:Num                          (read-only)

Distance to waypoint, in ly. This can be a fractional number.

See also: Ship Properties

[Top]Waypoint.Planet (Ship Property)

Waypoint.Planet:Int                        (read-only)

Id of planet at waypoint.

See also: PlanetAt(), Ship Properties

[Top]Waypoint.X (Ship Property)

Waypoint.X:Int                             (read-only)

X location of waypoint.

See also: Ship Properties

[Top]Waypoint.Y (Ship Property)

Waypoint.Y:Int                             (read-only)

Y location of waypoint.

See also: Ship Properties

[Top]With (Elementary Command)

 With obj:Obj Do command

 With obj:Obj [Do]
   commands
 EndWith

Evaluate command in object context. The expression obj specifies an object, such as a planet (Planet(14)). That object's context is activated, and all commands are executed within it. For example, within a planet context, SetFCode would change the planet's friendly code, and the FCode property would return it.

Since: PCC 1.0.6, PCC2 1.99.9

See also: Elementary Commands

[Top]Write (Incoming Message Command)

Write #fd:File, [flags:Str]

Write message to file. The file fd must be a text file open for writing.

By default, this writes the message in mailbox format. This way, you can later open the file with the View Mailbox function ([Alt-M]) in PCC. That is, PCC will automatically prepend a special header to the message text, to later be able to recognize message boundaries. By specifying the second, optional parameter as "r", these headers are omitted and just the raw text is written.

Since: PCC 1.1.16, PCC2 1.99.13

See also: Incoming Message Commands

[Top]Z, Zap (Elementary Function)

Z(x:Any):Any
Zap(x:Any):Any

Force false expression to EMPTY. If the parameter is an empty string, False, or zero, returns EMPTY. Otherwise, the parameter is returned as-is. The idea is to make zero/empty values disappear in messages, e.g.

   Z(Money) # ' mc'

will return a string like "10 mc" if there is some money, but disappear if there's none.

Since: PCC 0.98.5, PCC2 1.99.8

See also: Elementary Functions