This is the PCC2 help in one big HTML file. This help is also available within the program, using Alt-H.
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.
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.
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.
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.
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.
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:
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.
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.
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!
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.
Expressions compute values. They do so by combining elementary values (literals, properties, variables) using operators and functions. The following sections describe expressions.
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
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.
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) | a 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). |
| a 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) | a 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. | |
| a 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 to operators are shown as "a" and "b" above. The following things are possible operands:
A function invocation has the general form
NameOfFunction(FirstParameter, SecondParameter, ...)
There are two kinds of functions, elementary functions and regular 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 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.
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:
A script or auto task is a list of Statements (also called Commands). Statements perform actions, or control execution of other statements.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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:
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.
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.
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.
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
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.
This section explains the ideas behind the scripting language, and why things are as they are.
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.
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 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.
Functions documented to accept or return Any accept more than one data type.
(from doc/interpreter_manual.txt:900)
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.
(from doc/interpreter_manual.txt:903)
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.
(from doc/interpreter_manual.txt:913)
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.
(from doc/interpreter_manual.txt:924)
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.
(from doc/interpreter_manual.txt:937)
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.
(from doc/interpreter_manual.txt:966)
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.)
(from doc/interpreter_manual.txt:973)
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.
(from doc/interpreter_manual.txt:989)
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").
Since 2.0.8, you can also specify the name of the hook as an expression using the ByName() pseudo-function:
On ByName(n) Do Whatever
Here, the name of the hook is specified in variable n.
(from doc/interpreter_manual.txt:1006)
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.
(from doc/interpreter_manual.txt:1021)
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.
Since 2.0.8, you can also specify keymap names as an expression using the ByName() pseudo-function:
Bind ByName(n) "x" := "My.Command"
Here, the name of the keymap is specified in variable n.
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. |
(from doc/interpreter_manual.txt:1039)
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.
(from doc/interpreter_manual.txt:1088)
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.
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
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
(from doc/interpreter_manual.txt:1108)
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.
(from doc/interpreter_manual.txt:1152)
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.
(from doc/interpreter_manual.txt:1163)
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.
First version with Search function.
(from doc/interpreter_manual.txt:1765)
Items introduced in this version:
(from doc/interpreter_manual.txt:1763)
Items introduced in this version:
First version with Print function.
(from doc/interpreter_manual.txt:1760)
Items introduced in this version:
(from doc/interpreter_manual.txt:1758)
Items introduced in this version:
(from doc/interpreter_manual.txt:1756)
Items introduced in this version:
(from doc/interpreter_manual.txt:1754)
Items introduced in this version:
(from doc/interpreter_manual.txt:1752)
Items introduced in this version:
First version that supports scripting, as one-line commands entered at the console.
(from doc/interpreter_manual.txt:1749)
Items introduced in this version:
(from doc/interpreter_manual.txt:1744)
Items introduced in this version:
(from doc/interpreter_manual.txt:1728)
Items introduced in this version:
(from doc/interpreter_manual.txt:1721)
Items introduced in this version:
(from doc/interpreter_manual.txt:1713)
Items introduced in this version:
(from doc/interpreter_manual.txt:1706)
Items introduced in this version:
Dim Shared Name
With Ships(1) Do Name := "USS " & Name
does no longer read the ship name (right side) but assign to the global variable (left side).
They now both refer to the ship name (which can't yet be assigned to).(from doc/interpreter_manual.txt:1695)
Items introduced in this version:
(from doc/interpreter_manual.txt:1691)
Items introduced in this version:
(from doc/interpreter_manual.txt:1687)
Items introduced in this version:
(from doc/interpreter_manual.txt:1682)
Items introduced in this version:
(from doc/interpreter_manual.txt:1677)
Items introduced in this version:
(from doc/interpreter_manual.txt:1674)
Items introduced in this version:
(from doc/interpreter_manual.txt:1672)
Items introduced in this version:
(from doc/interpreter_manual.txt:1668)
Items introduced in this version:
(from doc/interpreter_manual.txt:1665)
Items introduced in this version:
(from doc/interpreter_manual.txt:1663)
Items introduced in this version:
(from doc/interpreter_manual.txt:1661)
Items introduced in this version:
(from doc/interpreter_manual.txt:1659)
Items introduced in this version:
(from doc/interpreter_manual.txt:1656)
Items introduced in this version:
(from doc/interpreter_manual.txt:1651)
Items introduced in this version:
(from doc/interpreter_manual.txt:1649)
Items introduced in this version:
(from doc/interpreter_manual.txt:1639)
Items introduced in this version:
(from doc/interpreter_manual.txt:1637)
Items introduced in this version:
(from doc/interpreter_manual.txt:1627)
Items introduced in this version:
(from doc/interpreter_manual.txt:1624)
Items introduced in this version:
(from doc/interpreter_manual.txt:1617)
Items introduced in this version:
(from doc/interpreter_manual.txt:1612)
Items introduced in this version:
(from doc/interpreter_manual.txt:1589)
Items introduced in this version:
(from doc/interpreter_manual.txt:1587)
Items introduced in this version:
First version of PCC2 that can evaluate expressions, with Search, object labels, and console.
(from doc/interpreter_manual.txt:1583)
Items introduced in this version:
First version of PCC2 that can execute commands.
(from doc/interpreter_manual.txt:1580)
Items introduced in this version:
(from doc/interpreter_manual.txt:1576)
Items introduced in this version:
(from doc/interpreter_manual.txt:1571)
Items introduced in this version:
(from doc/interpreter_manual.txt:1567)
Items introduced in this version:
(from doc/interpreter_manual.txt:1564)
Items introduced in this version:
(from doc/interpreter_manual.txt:1562)
Items introduced in this version:
(from doc/interpreter_manual.txt:1560)
Items introduced in this version:
(from doc/interpreter_manual.txt:1558)
Items introduced in this version:
(from doc/interpreter_manual.txt:1556)
Items introduced in this version:
(from doc/interpreter_manual.txt:1553)
Items introduced in this version:
(from doc/interpreter_manual.txt:1551)
Items introduced in this version:
(from doc/interpreter_manual.txt:1549)
Items introduced in this version:
This version introduces plugins and closes some gaps still remaining between PCC 1.x and PCC2.
(from doc/interpreter_manual.txt:1543)
Items introduced in this version:
(from doc/interpreter_manual.txt:1541)
Items introduced in this version:
(from doc/interpreter_manual.txt:1535)
Items introduced in this version:
(from doc/interpreter_manual.txt:1533)
Items introduced in this version:
(from doc/interpreter_manual.txt:1531)
Items introduced in this version:
(from doc/interpreter_manual.txt:1529)
Items introduced in this version:
(from doc/interpreter_manual.txt:1514)
Items introduced in this version:
This version adds access to the user configuration file (pcc2.ini).
(from doc/interpreter_manual.txt:1511)
Items introduced in this version:
(from doc/interpreter_manual.txt:1509)
Items introduced in this version:
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.
(from doc/interpreter_manual.txt:1188)
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.
(from doc/interpreter_manual.txt:1211)
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.
(from doc/interpreter_manual.txt:1194)
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.
(from doc/interpreter_manual.txt:1222)
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.
(from doc/interpreter_manual.txt:1243)
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.
(from doc/interpreter_manual.txt:1249)
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.
(from doc/interpreter_manual.txt:1260)
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.
(from doc/interpreter_manual.txt:1275)
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.
(from doc/interpreter_manual.txt:1288)
File properties are accessible using the ForEach DirectoryEntry(dir) command.
(from doc/interpreter_manual.txt:1499)
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.
(from doc/interpreter_manual.txt:1295)
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.
(from doc/interpreter_manual.txt:1304)
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.
(from doc/interpreter_manual.txt:1314)
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.
(from doc/interpreter_manual.txt:1331)
You can iterate through the elements of a Hash using ForEach:
Dim hh As Hash % ... ForEach hh Do Print Key, " = ", Value Next
(from doc/interpreter_manual.txt:1341)
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.
(from doc/interpreter_manual.txt:1349)
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.
(from doc/interpreter_manual.txt:1356)
The following commands can be used for messages.
(from doc/interpreter_manual.txt:1365)
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.
(from doc/interpreter_manual.txt:1368)
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.
(from doc/interpreter_manual.txt:1375)
This section describes all predefined keymaps. A keymap is defined using CreateKeymap and can be manipulated using Bind.
Also see keymap cross-reference.
(from doc/interpreter_manual.txt:1381)
These commands are used when building list boxes. See Listbox() for details.
(from doc/interpreter_manual.txt:1387)
The following commands can be used for minefields.
(from doc/interpreter_manual.txt:1391)
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.
(from doc/interpreter_manual.txt:1394)
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.
(from doc/interpreter_manual.txt:1404)
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.
(from doc/interpreter_manual.txt:1410)
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.
(from doc/interpreter_manual.txt:1424)
This section describes plugin properties. These can be accessed using System.Plugin(id).FIELD.
(from doc/interpreter_manual.txt:1431)
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.
(from doc/interpreter_manual.txt:1435)
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.
(from doc/interpreter_manual.txt:1441)
These commands are valid at ion storms.
To execute an ion storm command, use the With Storm(id) Do command.
(from doc/interpreter_manual.txt:1464)
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.
(from doc/interpreter_manual.txt:1469)
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.
(from doc/interpreter_manual.txt:1476)
These commands are valid at Ufos.
To execute an Ufo command, use the With Ufo(id) Do command.
(from doc/interpreter_manual.txt:1485)
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.
(from doc/interpreter_manual.txt:1490)
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
(from int/builtin.cc:592)
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
(from int/statement.cc:751)
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
(from int/builtin.cc:571)
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
(from int/if/globalif.cc:1333)
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
(from int/if/globalif.cc:1364)
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
(from int/if/globalif.cc:1420)
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
(from int/if/listif.cc:220)
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
(from resource/core.q:595)
AddPref line:Str
Modify the user configuration (preferences/options). line is a configuration assignment as it could appear in pcc2.ini. This command will process the line, and update the in-memory configuration accordingly. The configuration file will be rewritten the next time PCC2 exits the game.
You can only modify complete options, there's no way to modify just one slot of an array option.
For PCC2, this command will fail if the specified option does not exist.
Since: PCC2 2.0.12
See also: Global Commands
(from int/if/guiif.cc:157)
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
(from doc/interpreter_manual.txt:2019)
Algorithm:Str (read-only)
Name of VCR algorithm.
See also: Combat Properties
(from int/if/vcrif.cc:990)
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
(from int/builtin.cc:579)
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
(from int/builtin.cc:613)
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
(from int/builtin.cc:625)
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
(from int/if/globalif.cc:1456)
AutoBuild
Perform a standard auto-build operation.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Planet Commands
(from int/if/planetif.cc:125)
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
(from doc/interpreter_manual.txt:2200)
AutoTaxColonists
Auto-tax for colonists.
Since: PCC2 1.99.15
See also: Planet Commands
(from int/if/planetif.cc:437)
AutoTaxNatives
Auto-tax for natives.
Since: PCC2 1.99.15
See also: Planet Commands
(from int/if/planetif.cc:457)
Aux:Str (read-only)
Secondary weapon type, full name. Either a torpedo system name, "Fighters", or EMPTY.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1017)
Aux$:Int (read-only)
Type of secondary weapon.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:978)
Aux.Ammo:Int (read-only)
Number of fighters/torpedoes.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:991)
Aux.Count:Int (read-only)
Number of fighter bays/torpedo launchers.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:996)
Aux.Short:Str (read-only)
Secondary weapon type, short name.
See also: Aux (Ship Property), Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1006)
There are multiple items with this name:
Bind Base key := command
Keys on this keymap are active whenever focus is on a starbase.
Since: PCC2 1.99.9
See also: Keymaps
(from doc/interpreter_manual.txt:2123)
Base:Str (read-only)
Starbase status, human-readable. One of
See also: Planet Properties
(from int/if/planetif.cc:901)
Base.Building:Bool (read-only)
True if this planet is building a base.
See also: Planet Properties
(from int/if/planetif.cc:892)
Base.YesNo:Bool (read-only)
True if this planet has a base.
See also: Planet Properties
(from int/if/planetif.cc:887)
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
(from doc/interpreter_manual.txt:2266)
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
(from doc/interpreter_manual.txt:2172)
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
(from doc/interpreter_manual.txt:2227)
Bases:Int (read-only)
Number of bases this player has, according to score.
See also: Player Properties
(from int/if/playerif.cc:263)
There are multiple items with this name:
Beam:Str (read-only)
Beam type, full name.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1046)
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
(from int/if/specif.cc:105)
Beam$:Int (read-only)
Beam type. 0 if none, EMPTY if not known.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1028)
Beam.Count:Int (read-only)
Number of beams.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1033)
Beam.Max:Int (read-only)
Maximum number of beams on this ship.
See also: Hull Properties, Ship Properties
(from int/if/hullif.cc:194)
Beam.Short:Str (read-only)
Beam type, short name.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1038)
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
(from doc/interpreter_manual.txt:2026)
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. keymap is an identifier or ByName() expression. 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
(from int/statement.cc:784)
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
(from int/builtin.cc:634)
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
(from int/builtin.cc:643)
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
(from int/builtin.cc:650)
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
(from int/builtin.cc:659)
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
(from int/statement.cc:224)
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
(from int/if/baseif.cc:258)
Build.Beam$:Int (read-only)
Beam type for ship to build on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:230)
Build.Beam.Count:Int (read-only)
Number of beams for ship to build on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:235)
Build.Engine$:Int (read-only)
Number of engines for ship to build on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:240)
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
(from int/if/baseif.cc:250)
Build.QPos:Int (read-only)
Position of starbase in build queue. EMPTY if no base, or position not known.
See also: Planet Properties
(from int/if/baseif.cc:280)
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
(from resource/core.q:1219)
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
(from int/if/baseif.cc:269)
Build.Torp$:Int (read-only)
Torpedo type for ship to build on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:285)
Build.Torp.Count:Int (read-only)
Number of torpedo tubes for ship to build on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:290)
Build.YesNo:Bool (read-only)
Ship build flag. True if this base is building a ship. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:245)
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
(from int/if/planetif.cc:142)
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
(from int/if/planetif.cc:166)
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
(from resource/core.q:443)
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
(from int/if/baseif.cc:677)
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
(from int/if/planetif.cc:191)
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
(from resource/core.q:428)
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
(from int/if/baseif.cc:574)
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
(from int/if/planetif.cc:216)
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
(from resource/core.q:413)
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
(from int/if/baseif.cc:544)
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
(from int/if/baseif.cc:605)
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
(from int/if/baseif.cc:646)
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
(from int/if/planetif.cc:241)
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
(from resource/core.q:398)
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
(from int/if/baseif.cc:808)
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
(from int/if/baseif.cc:708)
ByName(name:Str):Keymap ByName(name:Str):Hook
Commands that operate on keymaps and hooks take the keymap or hook name as an identifier. That is, RunHook X will run the hook named "X", even if X is a variable.
If you wish to fetch the hook/keymap name from a variable or expression, you can write ByName(expression), where the expression produces the actual name.
Note: ByName() can only be used at places where keymap or hook names are required, nowhere else.
Since: PCC2 2.0.8
See also: Elementary Functions
(from int/statement.cc:3341)
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
(from int/if/globalif.cc:1113)
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
(from resource/core.q:639)
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
(from resource/core.q:624)
CC$Get(old:Blob, fd:File, length:Int):Blob
Backend to Get.
See also: Internal
(from int/file.cc:867)
CC$Input(old:Str, fd:File, [flag:Bool]):Str
Backend to Input.
See also: Internal
(from int/file.cc:892)
CC$LibraryVersion:Str (read-only)
Version of the standard library (core.q).
See also: Internal
(from resource/core.q:18)
CC$Notify msg:Str, associateWithProcess:Bool
Back-end to Notify and AddNotify.
See also: Internal
(from int/if/globalif.cc:1901)
CC$NotifyConfirmed():Bool
Part of the implementation of Notify. Returns true if there is a confirmed notification message for this process.
See also: Internal
(from int/if/globalif.cc:273)
CC$Open(fd:File, name:Str, mode:Int):Any
Backend to Open.
See also: Internal
(from int/file.cc:917)
CC$Print(fd:File, text:Str):Any
Backend to Print to a file.
See also: Internal
(from int/file.cc:975)
CC$Reset x:Int, y:Int
Reset location dialog.
See also: Internal
(from int/if/guiif.cc:2057)
CC$SelectionExec layer:Int, code:Str
Back-end to SelectionExec.
See also: Internal
(from int/if/globalif.cc:1879)
CC$SetInt(v:Blob, size:Int, pos:Int, value:Int...):Blob
Backend to SetByte, SetWord, SetLong.
See also: Internal
(from int/file.cc:683)
CC$SetStr(v:Blob, pos:Int, size:Int, value:Str):Blob
Backend to SetStr.
See also: Internal
(from int/file.cc:735)
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
(from int/if/guiif.cc:2037)
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
(from int/if/globalif.cc:1137)
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
(from int/if/globalif.cc:1158)
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
(from int/if/globalif.cc:1221)
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
(from int/if/globalif.cc:1252)
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
(from int/if/globalif.cc:1276)
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
(from int/if/globalif.cc:1305)
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
(from int/statement.cc:889)
Capabilities:Int (read-only)
VCR feature identification value. Valid only for classic combat, EMPTY for others.
See also: Combat Properties
(from int/if/vcrif.cc:995)
Cargo.Colonists:Int (read-only)
Number of colonists aboard this ship.
See also: Ship Properties
(from int/if/shipif.cc:1054)
Cargo.D:Int (read-only)
Duranium aboard this ship, kilotons.
See also: Ship Properties
(from int/if/shipif.cc:1059)
Cargo.Free:Int (read-only)
Free cargo room.
See also: Ship Properties
(from int/if/shipif.cc:1064)
Cargo.M:Int (read-only)
Molybdenum aboard this ship, kilotons.
See also: Ship Properties
(from int/if/shipif.cc:1069)
Cargo.Max:Int (read-only)
Maximum cargo on this ship.
See also: Hull Properties, Ship Properties
(from int/if/hullif.cc:199)
Cargo.MaxFuel:Int (read-only)
Maximum fuel on this ship.
See also: Hull Properties, Ship Properties
(from int/if/hullif.cc:204)
Cargo.Money:Int (read-only)
Money aboard this ship.
See also: Ship Properties
(from int/if/shipif.cc:1074)
Cargo.N:Int (read-only)
Neutronium aboard this ship, kilotons.
See also: Ship Properties
(from int/if/shipif.cc:1079)
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
(from resource/core.q:1207)
Cargo.Str:Cargo (read-only)
Cargo aboard this ship. String containing amounts of minerals, supplies, colonists, cash, and torpedoes/fighters.
See also: Ship Properties
(from int/if/shipif.cc:1084)
Cargo.Supplies:Int (read-only)
Supplies aboard this ship, kilotons.
See also: Ship Properties
(from int/if/shipif.cc:1112)
Cargo.T:Int (read-only)
Tritanium aboard this ship, kilotons.
See also: Ship Properties
(from int/if/shipif.cc:1117)
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
(from int/if/shipif.cc:362)
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
(from resource/core.q:355)
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
(from int/if/shipif.cc:473)
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
(from resource/core.q:380)
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
(from int/if/shipif.cc:495)
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
(from resource/core.q:325)
This keyword is part of the Select command, see there.
See also: Elementary Commands
(from int/statement.cc:281)
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
(from int/if/globalif.cc:861)
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
(from resource/core.q:469)
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
(from int/if/guiif.cc:1917)
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
(from int/if/globalif.cc:73)
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
(from int/builtin.cc:678)
Class:Int (read-only)
Ion storm's class.
See also: Storm Properties
(from int/if/ionif.cc:184)
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
(from int/file.cc:1103)
Colonists:Int (read-only)
Colonist population, number of clans.
See also: Planet Properties
(from int/if/planetif.cc:967)
Colonists.Change:Str (read-only)
Colonist happiness change, text.
See also: Planet Properties
(from int/if/planetif.cc:920)
Colonists.Change$:Int (read-only)
Colonist happiness change, numeric value.
See also: Planet Properties
(from int/if/planetif.cc:915)
Colonists.Happy:Str (read-only)
Colonist happiness, text.
See also: Planet Properties
(from int/if/planetif.cc:936)
Colonists.Happy$:Int (read-only)
Colonist happiness, numeric value.
See also: Planet Properties
(from int/if/planetif.cc:931)
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
(from int/if/planetif.cc:944)
Colonists.Tax:Int (read/write)
Colonist tax.
See also: SetColonistTax (Planet Command), Planet Properties
(from int/if/planetif.cc:950)
Colonists.Tax.Income:Int (read-only)
Tax income from colonists, megacredits.
Since: PCC2 1.99.15
See also: Planet Properties
(from int/if/planetif.cc:957)
There are multiple items with this name:
Color:Int (read/write)
Color of this drawing.
See also: SetColor (Drawing Command), NewLine, NewCircle, NewRectangle, NewMarker, Drawing Properties
(from int/if/drawingif.cc:299)
Color:Int (read-only)
Ufo color. This color is compatible to the NewLine, NewMarker etc. commands.
See also: Color (Ufo Property), Ufo Properties
(from int/if/ufoif.cc:215)
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
(from int/if/ufoif.cc:208)
There are multiple items with this name:
Comment:Str (read/write)
User comment. This is the comment that can be edited with F9.
See also: Planet Properties, Ship Properties
(from int/intglobal.cc:56)
Comment:Str (read/write)
Comment of this drawing. Displayed for markers.
See also: SetComment (Drawing Command), Drawing Properties
(from int/if/drawingif.cc:306)
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
(from int/if/vcrif.cc:894)
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
(from int/if/vcrif.cc:887)
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
(from int/if/vcrif.cc:922)
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
(from int/if/vcrif.cc:912)
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
(from int/if/vcrif.cc:904)
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
(from int/statement.cc:240)
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
(from doc/interpreter_manual.txt:2140)
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
(from int/builtin.cc:699)
Cost.D:Int (read-only)
Duranium cost of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:626)
Cost.M:Int (read-only)
Molybdenum cost of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:631)
Cost.MC:Int (read-only)
Money cost of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:636)
Cost.Str:Cargo (read-only)
Cost of this component, as a string.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:644)
Cost.T:Int (read-only)
Tritanium cost of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:621)
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
(from int/builtin.cc:710)
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
(from int/builtin.cc:720)
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
(from int/builtin.cc:729)
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 or ByName() expression 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
(from int/statement.cc:950)
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
(from int/statement.cc:1023)
There are multiple items with this name:
Crew:Int (read-only)
Current crew size.
See also: Ship Properties
(from int/if/shipif.cc:1122)
Crew:Int (read-only)
Crew on this ship. EMPTY if this is a planet.
See also: Combat Participant Properties
(from int/if/vcrif.cc:692)
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
(from int/if/vcrif.cc:702)
Crew.Normal:Int (read-only)
Maximum crew on this ship.
See also: Hull Properties, Ship Properties
(from int/if/hullif.cc:209)
There are multiple items with this name:
Damage:Int (read-only)
Starbase damage. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:198)
Damage:Int (read-only)
Damage level in percent.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1127)
Damage:Int (read-only)
Explosive power of this weapon.
See also: Beam Properties, Torpedo Properties
(from int/if/specif.cc:716)
Defense:Int (read-only)
Number of planetary defense posts.
See also: Planet Properties
(from int/if/planetif.cc:972)
Defense.Base:Int (read-only)
Starbase defense. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:203)
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
(from int/if/baseif.cc:208)
Defense.Base.Speed:Int (read/write)
Auto-build speed for starbase defense.
Since: PCC2 2.0.14
See also: Planet Properties
(from int/if/planetif.cc:872)
Defense.Base.Want:Int (read/write)
Auto-build goal for starbase defense.
See also: Planet Properties
(from int/if/planetif.cc:880)
Defense.Max:Int (read-only)
Maximum number of planetary defense posts.
See also: Planet Properties
(from int/if/planetif.cc:977)
Defense.Speed:Int (read/write)
Auto-build speed for defense posts.
Since: PCC2 2.0.14
See also: Planet Properties
(from int/if/planetif.cc:982)
Defense.Want:Int (read/write)
Auto-build goal for defense posts.
See also: Planet Properties
(from int/if/planetif.cc:990)
There are multiple items with this name:
Delete
Delete this drawing.
Since: PCC 1.0.14, PCC2 1.99.20
See also: Drawing Commands
(from int/if/drawingif.cc:46)
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
(from int/if/mineif.cc:133)
Density.D:Int (read-only)
Density of Duranium in planet core.
See also: Planet Properties
(from int/if/planetif.cc:997)
Density.M:Int (read-only)
Density of Molybdenum in planet core.
See also: Planet Properties
(from int/if/planetif.cc:1002)
Density.N:Int (read-only)
Density of Neutronium in planet core.
See also: Planet Properties
(from int/if/planetif.cc:1007)
Density.T:Int (read-only)
Density of Tritanium in planet core.
See also: Planet Properties
(from int/if/planetif.cc:1012)
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
(from int/if/plugif.cc:144)
There are multiple items with this name:
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
(from int/builtin.cc:738)
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
(from int/statement.cc:1076)
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
(from int/if/plugif.cc:151)
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
(from int/file.cc:1179)
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
(from int/if/globalif.cc:631)
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
(from int/statement.cc:1158)
This keyword is part of the If, and Try statements, see there.
See also: Elementary Commands
(from int/statement.cc:286)
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
(from int/statement.cc:268)
End.X:Int (read-only)
X location of endpoint. Valid for lines and rectangles, EMPTY for others.
See also: Drawing Properties
(from int/if/drawingif.cc:314)
End.Y:Int (read-only)
Y location of endpoint. Valid for lines and rectangles, EMPTY for others.
See also: Drawing Properties
(from int/if/drawingif.cc:324)
This keyword is part of the Function command, see there.
See also: Elementary Commands
(from int/statement.cc:308)
This keyword is part of the If statement, see there.
See also: Elementary Commands
(from int/statement.cc:291)
This keyword is part of the On statement, see there.
Since: PCC2 2.0.8
See also: Elementary Commands
(from int/statement.cc:296)
This keyword is part of the Struct command, see there.
See also: Elementary Commands
(from int/statement.cc:338)
This keyword is part of the Sub command, see there.
See also: Elementary Commands
(from int/statement.cc:303)
This keyword is part of the Try command, see there.
See also: Elementary Commands
(from int/statement.cc:313)
This keyword is part of the With command, see there.
See also: Elementary Commands
(from int/statement.cc:318)
Enemy:Str (read-only)
Short name of this player.
See also: Ship Properties
(from int/if/playerif.cc:249)
Enemy$:Int (read/write)
Primary Enemy. 0=none, or a player number.
See also: SetEnemy (Ship Command), Ship Properties
(from int/if/shipif.cc:1132)
Enemy.Adj:Str (read-only)
Adjective name of this player.
See also: Ship Properties
(from int/if/playerif.cc:196)
There are multiple items with this name:
Engine:Str (read-only)
Type of engine, full name.
See also: Ship Properties
(from int/if/shipif.cc:1144)
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
(from int/if/specif.cc:140)
Engine$:Int (read-only)
Type of engine.
See also: Ship Properties
(from int/if/shipif.cc:1139)
Engine.Count:Int (read-only)
Number of engines.
See also: Hull Properties, Ship Properties
(from int/if/hullif.cc:214)
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
(from resource/core.q:301)
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
(from doc/interpreter_manual.txt:2033)
There are multiple items with this name:
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
(from int/builtin.cc:767)
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
(from int/statement.cc:1261)
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
(from doc/interpreter_manual.txt:2040)
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
(from int/builtin.cc:778)
Expire:Int (read/write)
Expiration time.
See also: NewLine, NewCircle, NewMarker, NewRectangle, Drawing Properties
(from int/if/drawingif.cc:334)
There are multiple items with this name:
FCode:Str (read/write)
Friendly code.
See also: SetFCode (Planet Command), Planet Properties
(from int/if/planetif.cc:1017)
FCode:Str (read/write)
Friendly code.
See also: SetFCode (Ship Command), Ship Properties
(from int/if/shipif.cc:1152)
FPos(#fd:File):Int
Get current position within a file.
Since: PCC 1.0.13, PCC2 1.99.12
(from int/file.cc:989)
FSize(#fd:File):Int
Get size of the file, in bytes.
Since: PCC 1.0.13, PCC2 1.99.12
(from int/file.cc:1029)
Factories:Int (read-only)
Number of factories on planet.
See also: Planet Properties
(from int/if/planetif.cc:1027)
Factories.Max:Int (read-only)
Maximum number of factories on planet.
See also: Planet Properties
(from int/if/planetif.cc:1032)
Factories.Speed:Int (read/write)
Auto-build speed for factories.
Since: PCC2 2.0.14
See also: Planet Properties
(from int/if/planetif.cc:1037)
Factories.Want:Int (read/write)
Auto-build goal for factories.
See also: Planet Properties
(from int/if/planetif.cc:1045)
There are multiple items with this name:
Fighter.Bays:Int (read-only)
Number of fighter bays on this ship.
See also: Hull Properties
(from int/if/hullif.cc:257)
Fighter.Bays:Int (read-only)
Number of fighter bays.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1162)
Fighter.Count:Int (read-only)
Number of fighters.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1167)
Fighters:Int (read-only)
Number of fighters on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:214)
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
(from int/if/baseif.cc:219)
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
(from int/builtin.cc:788)
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
(from int/builtin.cc:799)
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
(from int/builtin.cc:811)
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
(from resource/core.q:655)
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
(from int/builtin.cc:823)
There are multiple items with this name:
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
(from int/if/baseif.cc:850)
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
(from int/if/shipif.cc:202)
There are multiple items with this name:
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
(from resource/core.q:497)
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
(from resource/core.q:497)
There are multiple items with this name:
Bind Fleet key := command
Keys on this keymap are active whenever focus is on a fleet.
Since: PCC2 1.99.9
See also: Keymaps
(from doc/interpreter_manual.txt:2132)
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
(from int/if/shipif.cc:1206)
Fleet$:Int (read/write)
Id of fleet this ship is in.
See also: SetFleet (Ship Command), Ship Properties
(from int/if/shipif.cc:1175)
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
(from int/if/shipif.cc:1182)
Fleet.Status:Str (read-only)
Fleet status. One of
See also: Ship Properties
(from int/if/shipif.cc:1190)
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
(from doc/interpreter_manual.txt:2181)
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
(from int/statement.cc:1291)
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
(from int/statement.cc:1474)
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
(from int/if/globalif.cc:994)
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
(from int/file.cc:1004)
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
(from int/if/specif.cc:739)
FullText:Str (read-only)
Message text, in one big string.
See also: Incoming Message Properties
(from int/if/msgif.cc:227)
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
(from int/statement.cc:2534)
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
(from int/file.cc:605)
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
(from int/file.cc:806)
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
(from int/file.cc:1086)
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
(from int/file.cc:1069)
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
(from int/mutex.cc:469)
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
(from int/file.cc:828)
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
(from int/file.cc:839)
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
(from int/file.cc:817)
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
(from doc/interpreter_manual.txt:2098)
Ground.D:Int (read-only)
Amount of Duranium in ground, kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1052)
Ground.M:Int (read-only)
Amount of Molybdenum in ground, kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1057)
Ground.N:Int (read-only)
Amount of Neutronium in ground, kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1062)
Ground.T:Int (read-only)
Amount of Tritanium in ground, kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1067)
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
(from int/if/msgif.cc:210)
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
(from int/if/shipif.cc:598)
There are multiple items with this name:
Heading:Str (read-only)
Ion storm's heading, as compass point. For example, "NE" for north-east.
See also: Storm Properties
(from int/if/ionif.cc:194)
Heading:Str (read-only)
Current angle of movement, as compass direction.
See also: Ship Properties
(from int/if/shipif.cc:1229)
Heading:Str (read-only)
Heading, as compass direction.
See also: Ufo Properties
(from int/if/ufoif.cc:230)
There are multiple items with this name:
Heading$:Int (read-only)
Ion storm's heading, in degrees.
See also: Storm Properties
(from int/if/ionif.cc:189)
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
(from int/if/shipif.cc:1223)
Heading$:Int (read-only)
Heading, in degrees. EMPTY if Ufo does not move or heading is not known.
See also: Ufo Properties
(from int/if/ufoif.cc:222)
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
(from doc/interpreter_manual.txt:2190)
There are multiple items with this name:
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
(from int/if/hullif.cc:29)
Hull:Str (read-only)
Name of the ship's hull.
See also: Ship Properties
(from int/if/specif.cc:653)
Hull:Str (read-only)
Hull name. EMPTY if the hull cannot be determined, or this is a planet.
See also: Combat Participant Properties
(from int/if/vcrif.cc:818)
There are multiple items with this name:
Hull$:Str (read-only)
Hull Id.
See also: Ship Properties
(from int/if/specif.cc:670)
Hull$:Int (read-only)
Hull number. EMPTY if the hull cannot be determined, or this is a planet.
See also: Combat Participant Properties
(from int/if/vcrif.cc:823)
Hull.Short:Str (read-only)
Short name of the hull.
See also: Ship Properties
(from int/if/specif.cc:662)
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
(from int/if/shipif.cc:1238)
There are multiple items with this name:
Id:Int (read-only)
Ion storm's Id.
See also: Storm Properties
(from int/if/ionif.cc:200)
Id:Int (read-only)
Id of this minefield.
See also: Minefield Properties
(from int/if/mineif.cc:271)
Id:Int (read-only)
Id of message. This is the index into InMsg() to access this very message.
See also: Incoming Message Properties
(from int/if/msgif.cc:198)
Id:Int (read-only)
Planet Id.
See also: Planet Properties
(from int/if/planetif.cc:1072)
Id:Str (read-only)
Id of the plugin.
Since: PCC2 1.99.25
See also: Plugin Properties
(from int/if/plugif.cc:130)
Id:Int (read-only)
Ship Id.
See also: Ship Properties
(from int/if/shipif.cc:1266)
Id:Str (read-only)
Component Id.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:667)
Id:Int (read-only)
Ufo Id.
See also: Ufo Properties
(from int/if/ufoif.cc:238)
Id:Int (read-only)
Id of this ship or planet.
See also: Combat Participant Properties
(from int/if/vcrif.cc:717)
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
(from int/if/ufoif.cc:243)
There are multiple items with this name:
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
(from int/builtin.cc:846)
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
(from int/statement.cc:1677)
There are multiple items with this name:
Image:Int (read/write)
Picture number used to display this ship in PCC.
See also: Hull Properties
(from int/if/hullif.cc:262)
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
(from int/if/vcrif.cc:838)
Image$:Int (read-only)
Picture number used to display this ship in planets.exe.
See also: Hull Properties
(from int/if/hullif.cc:268)
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
(from int/if/msgif.cc:96)
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
(from int/builtin.cc:856)
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
(from int/if/vcrif.cc:426)
Industry:Str (read-only)
Planetary industry level, human-readable.
See also: Industry$ (Planet Property), Planet Properties
(from int/if/planetif.cc:1077)
Industry$:Int (read-only)
Planetary industry level code.
| Ind$ | Ind |
|---|---|
| 0 | Minimal |
| 1 | Light |
| 2 | Moderate |
| 3 | Substantial |
| 4 | Heavy |
See also: Planet Properties
(from int/if/planetif.cc:1086)
Info1:Str (read-only) Info2:Str (read-only)
Description of this Ufo.
See also: Ufo Properties
(from int/if/ufoif.cc:255)
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
(from int/file.cc:633)
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
(from int/builtin.cc:877)
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
(from int/builtin.cc:896)
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
(from int/builtin.cc:915)
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
(from int/builtin.cc:924)
IsPlanet:Bool (read-only)
True if this is a planet.
See also: Combat Participant Properties
(from int/if/vcrif.cc:881)
IsSpecialFCode(fc:Str):Bool
Check for special friendly code. Returns true if the friendly code given as a parameter is a special friendly code.
A special friendly code is one defined as special through the fcodes.cc file, or through xtrfcode.txt. Note that PCC2 before 2.0.8 does not consider xtrfcode.txt.
Since: PCC 1.1.4, PCC2 1.99.8
See also: Functions
(from int/if/globalif.cc:926)
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
(from int/builtin.cc:936)
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
(from int/if/ufoif.cc:262)
There are multiple items with this name:
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
(from int/builtin.cc:944)
Key:Str (read-only)
The key of this hash element.
See also: Hash Element Properties
(from int/hash.cc:173)
Kill:Int (read-only)
Anti-life power of this weapon.
See also: Beam Properties, Torpedo Properties
(from int/if/specif.cc:711)
Killed:Bool (read-only)
True if this message is filtered and skipped by default.
See also: Incoming Message Properties
(from int/if/msgif.cc:217)
LCase(s:Str):Str
Convert string to lower case. Returns the string with all ASCII characters converted to lower-case.
If the parameter is EMPTY, returns EMPTY.
Since: PCC2 2.0.8
See also: UCase, Elementary Functions
(from int/builtin.cc:965)
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
(from int/builtin.cc:1006)
There are multiple items with this name:
LastScan:Int (read-only)
Turn when minefield was last scanned.
See also: Minefield Properties
(from int/if/mineif.cc:276)
LastScan:Int (read-only)
Turn when Ufo was last scanned.
See also: Ufo Properties
(from int/if/ufoif.cc:269)
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
(from int/if/specif.cc:76)
There are multiple items with this name:
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
(from int/builtin.cc:976)
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
(from int/if/vcrif.cc:738)
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
(from int/if/vcrif.cc:572)
Left.Aux$:Int (read-only) Right.Aux$:Int (read-only)
Type of secondary weapon.
See also: Combat Properties
(from int/if/vcrif.cc:557)
Left.Aux.Ammo:Int (read-only) Right.Aux.Ammo:Int (read-only)
Number of fighters or torpedoes on this unit.
See also: Combat Properties
(from int/if/vcrif.cc:533)
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
(from int/if/vcrif.cc:545)
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
(from int/if/vcrif.cc:585)
Left.Beam:Str (read-only) Right.Beam:Str (read-only)
Beam type, full name.
See also: Combat Properties
(from int/if/vcrif.cc:673)
Left.Beam$:Int (read-only) Right.Beam$:Int (read-only)
Beam type. 0 if none, EMPTY if not known.
See also: Combat Properties
(from int/if/vcrif.cc:667)
Left.Beam.Count:Int (read-only) Right.Beam.Count:Int (read-only)
Number of beams.
See also: Combat Properties
(from int/if/vcrif.cc:661)
Left.Beam.Short:Str (read-only) Right.Beam.Short:Str (read-only)
Beam type, short name.
See also: Combat Properties
(from int/if/vcrif.cc:683)
Left.Crew:Int (read-only) Right.Crew:Int (read-only)
Crew on this ship. EMPTY if this is a planet.
See also: Combat Properties
(from int/if/vcrif.cc:692)
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
(from int/if/vcrif.cc:702)
Left.Damage:Int (read-only) Right.Damage:Int (read-only)
Initial damage in percent.
See also: Combat Properties
(from int/if/vcrif.cc:712)
Left.Fighter.Bays:Int (read-only) Right.Fighter.Bays:Int (read-only)
Number of fighter bays.
See also: Combat Properties
(from int/if/vcrif.cc:598)
Left.Fighter.Count:Int (read-only) Right.Fighter.Count:Int (read-only)
Number of fighters.
See also: Combat Properties
(from int/if/vcrif.cc:604)
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
(from int/if/vcrif.cc:818)
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
(from int/if/vcrif.cc:823)
Left.Id:Int (read-only) Right.Id:Int (read-only)
Id of this ship or planet.
See also: Combat Properties
(from int/if/vcrif.cc:717)
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
(from int/if/vcrif.cc:838)
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
(from int/if/vcrif.cc:847)
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
(from int/if/vcrif.cc:723)
Left.Name:Int (read-only) Right.Name:Int (read-only)
Name of ship or planet.
See also: Combat Properties
(from int/if/vcrif.cc:732)
Left.Owner:Str (read-only) Right.Owner:Str (read-only)
Short name of this player.
See also: Combat Properties
(from int/if/vcrif.cc:765)
Left.Owner$:Int (read-only) Right.Owner$:Int (read-only)
Player number.
See also: Combat Properties
(from int/if/vcrif.cc:759)
Left.Owner.Adj:Str (read-only) Right.Owner.Adj:Str (read-only)
Adjective name of this player.
See also: Combat Properties
(from int/if/vcrif.cc:749)
Left.Shield:Int (read-only) Right.Shield:Int (read-only)
Initial shield level in percent.
See also: Combat Properties
(from int/if/vcrif.cc:775)
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
(from int/if/vcrif.cc:854)
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
(from int/if/vcrif.cc:871)
Left.Torp:Str (read-only) Right.Torp:Str (read-only)
Torpedo type, full name.
See also: Combat Properties
(from int/if/vcrif.cc:651)
Left.Torp$:Int (read-only) Right.Torp$:Int (read-only)
Torpedo type.
See also: Combat Properties
(from int/if/vcrif.cc:610)
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
(from int/if/vcrif.cc:620)
Left.Torp.LCount:Int (read-only) Right.Torp.LCount:Int (read-only)
Number of torpedo launchers on this ship.
See also: Combat Properties
(from int/if/vcrif.cc:631)
Left.Torp.Short:Str (read-only) Right.Torp.Short:Str (read-only)
Torpedo type, short name.
See also: Combat Properties
(from int/if/vcrif.cc:641)
Left.Type:Str (read-only) Right.Type:Str (read-only)
Classification of this unit. Possible values are:
See also: Combat Properties
(from int/if/vcrif.cc:782)
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
(from int/if/vcrif.cc:791)
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
(from int/builtin.cc:987)
There are multiple items with this name:
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
(from int/if/planetif.cc:1099)
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
(from int/if/shipif.cc:1271)
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
(from int/if/vcrif.cc:847)
Lines:Int (read-only)
Number of lines in message.
See also: Incoming Message Properties
(from int/if/msgif.cc:204)
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
(from int/if/listif.cc:284)
There are multiple items with this name:
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
(from doc/interpreter_manual.txt:2047)
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
(from int/statement.cc:1780)
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
(from int/if/guiif.cc:1317)
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
(from int/if/guiif.cc:1280)
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
(from int/if/shipif.cc:1299)
There are multiple items with this name:
Loc.X:Int (read-only)
X location of starting point/center.
See also: Drawing Properties
(from int/if/drawingif.cc:341)
Loc.X:Int (read-only)
Ion storm center X coordinate.
See also: Storm Properties
(from int/if/ionif.cc:205)
Loc.X:Int (read-only)
X location of center of minefield.
See also: Minefield Properties
(from int/if/mineif.cc:281)
Loc.X:Int (read-only)
Planet X location.
See also: Planet Properties
(from int/if/planetif.cc:1111)
Loc.X:Int (read-only)
X location of ship.
See also: Ship Properties
(from int/if/shipif.cc:1283)
Loc.X:Int (read-only)
X location of Ufo center.
See also: Ufo Properties
(from int/if/ufoif.cc:274)
There are multiple items with this name:
Loc.Y:Int (read-only)
Y location of starting point/center.
See also: Drawing Properties
(from int/if/drawingif.cc:346)
Loc.Y:Int (read-only)
Ion storm center Y coordinate.
See also: Storm Properties
(from int/if/ionif.cc:210)
Loc.Y:Int (read-only)
Y location of center of minefield.
See also: Minefield Properties
(from int/if/mineif.cc:286)
Loc.Y:Int (read-only)
Planet Y location.
See also: Planet Properties
(from int/if/planetif.cc:1116)
Loc.Y:Int (read-only)
Y location of ship.
See also: Ship Properties
(from int/if/shipif.cc:1291)
Loc.Y:Int (read-only)
Y location of Ufo center.
See also: Ufo Properties
(from int/if/ufoif.cc:279)
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
(from int/statement.cc:2257)
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
(from int/mutex.cc:367)
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
(from int/builtin.cc:995)
This keyword is part of the Do loop, see there.
See also: Elementary Commands
(from int/statement.cc:323)
Magic:Int (read-only)
VCR algorithm identification value. Valid only for classic combat, EMPTY for others.
See also: Combat Properties
(from int/if/vcrif.cc:967)
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
(from int/file.cc:1044)
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
(from doc/interpreter_manual.txt:2054)
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
(from int/if/objif.cc:89)
There are multiple items with this name:
Marked:Bool (read-only)
True if ion storm is marked.
See also: Storm Properties
(from int/if/ionif.cc:215)
Marked:Bool (read-only)
True if minefield is marked.
See also: Minefield Properties
(from int/if/mineif.cc:291)
Marked:Bool (read-only)
True if planet is marked.
See also: Planet Properties
(from int/if/planetif.cc:1121)
Marked:Bool (read-only)
True if ship is marked.
See also: Ship Properties
(from int/if/shipif.cc:1309)
Marked:Bool (read-only)
True if Ufo is marked.
See also: Ufo Properties
(from int/if/ufoif.cc:284)
There are multiple items with this name:
Mass:Int (read-only)
Mass of ship (hull, components, and cargo).
See also: Ship Properties
(from int/if/shipif.cc:1314)
Mass:Int (read-only)
Mass of this component, in kt.
See also: Beam Properties, Torpedo Properties
(from int/if/specif.cc:605)
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
(from int/if/vcrif.cc:723)
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
(from int/builtin.cc:1017)
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
(from int/if/guiif.cc:208)
There are multiple items with this name:
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
(from int/if/planetif.cc:1126)
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
(from int/if/shipif.cc:1319)
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
(from int/builtin.cc:1031)
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
(from int/builtin.cc:1043)
Mined.D:Int (read-only)
Mined Duranium, in kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1134)
Mined.M:Int (read-only)
Mined Molybdenum, in kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1139)
Mined.N:Int (read-only)
Mined Neutronium, in kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1144)
Mined.Str:Cargo (read-only)
Mined minerals, as a string.
See also: Planet Properties
(from int/if/planetif.cc:1149)
Mined.T:Int (read-only)
Mined Tritanium, in kilotons.
See also: Planet Properties
(from int/if/planetif.cc:1168)
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
(from int/if/mineif.cc:84)
Mines:Int (read-only)
Number of mineral mines.
See also: Planet Properties
(from int/if/planetif.cc:1173)
Mines.Max:Int (read-only)
Maximum number of mineral mines.
See also: Planet Properties
(from int/if/planetif.cc:1178)
Mines.Speed:Int (read/write)
Auto-build speed for mineral mines.
Since: PCC2 2.0.14
See also: Planet Properties
(from int/if/planetif.cc:1183)
Mines.Want:Int (read/write)
Auto-build goal for mineral mines.
See also: Planet Properties
(from int/if/planetif.cc:1191)
There are multiple items with this name:
Mission:Str (read-only)
Starbase mission. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:311)
Mission:Str (read-only)
Mission, full name.
See also: Ship Properties
(from int/if/shipif.cc:1362)
There are multiple items with this name:
Mission$:Int (read/write)
Starbase mission number. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:305)
Mission$:Int (read/write)
Mission number.
See also: SetMission (Ship Command), Ship Properties
(from int/if/shipif.cc:1327)
Mission.Intercept:Int (read/write)
Mission "Intercept" parameter.
See also: SetMission (Ship Command), Ship Properties
(from int/if/shipif.cc:1334)
Mission.Short:Str (read-only)
Mission, short name.
See also: Ship Properties
(from int/if/shipif.cc:1341)
Mission.Tow:Int (read/write)
Mission "Tow" parameter.
See also: SetMission (Ship Command), Ship Properties
(from int/if/shipif.cc:1355)
Money:Int (read-only)
Money (megacredits) on planet.
See also: Planet Properties
(from int/if/planetif.cc:1198)
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
(from int/if/ufoif.cc:289)
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
(from int/if/ufoif.cc:296)
Move.ETA:Int (read-only)
Estimated time of arrival at waypoint (number of turns).
See also: Ship Properties
(from int/if/shipif.cc:1381)
Move.Fuel:Int (read-only)
Predicted fuel useage for movement, in kilotons.
See also: Ship Properties
(from int/if/shipif.cc:1392)
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
(from resource/core.q:258)
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
(from resource/core.q:286)
My.Bases:Int (read-only)
Number of bases this player has, according to score.
See also: Global Properties
(from int/if/playerif.cc:263)
My.InMsgs:Int (read-only)
Number of incoming (received) messages this turn.
See also: Global Properties
(from int/if/globalif.cc:377)
My.OutMsgs:Int (read-only)
Number of outgoing (sent) messages this turn.
See also: Global Properties
(from int/if/globalif.cc:385)
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
(from int/if/playerif.cc:223)
My.Planets:Int (read-only)
Number of planets this player has, according to score.
See also: Global Properties
(from int/if/playerif.cc:269)
My.Race:Str (read-only)
Short name of this player.
See also: Global Properties
(from int/if/playerif.cc:249)
My.Race$:Int (read-only)
Player number.
See also: Global Properties
(from int/if/playerif.cc:210)
My.Race.Adj:Str (read-only)
Adjective name of this player.
See also: Global Properties
(from int/if/playerif.cc:196)
My.Race.Full:Str (read-only)
Full name of this player.
See also: Global Properties
(from int/if/playerif.cc:204)
My.Race.Id:Int (read-only)
Race assigned to this player.
See also: Global Properties
(from int/if/playerif.cc:243)
My.Race.Mission:Int (read-only)
Special mission assigned to this player.
See also: Global Properties
(from int/if/playerif.cc:217)
My.Score:Int (read-only)
This player's Tim-score.
See also: Global Properties
(from int/if/playerif.cc:281)
My.Score.Freighters:Int (read-only)
Number of freighters this player has, according to score.
See also: Global Properties
(from int/if/playerif.cc:295)
My.Ships:Int (read-only)
Number of ships this player has, according to score.
See also: Global Properties
(from int/if/playerif.cc:275)
My.Ships.Capital:Int (read-only)
Number of capital ships this player has, according to score.
See also: Global Properties
(from int/if/playerif.cc:289)
My.Team:Int (read-only)
Team this player is in.
See also: Global Properties
(from int/if/playerif.cc:257)
My.VCRs:Int (read-only)
Number of incoming combat recordings this turn.
See also: Global Properties
(from int/if/globalif.cc:393)
There are multiple items with this name:
Name:Str (read-only)
Name of the item (file), for example, "player9.rst".
Since: PCC2 2.0.4
See also: File Properties
(from int/file.cc:206)
Name:Str (read-only)
Ion storm name.
See also: Storm Properties
(from int/if/ionif.cc:220)
Name:Str (read-only)
Name of planet.
See also: Planet Properties
(from int/if/planetif.cc:1203)
Name:Str (read-only)
Human-readable name of the plugin.
Since: PCC2 1.99.25
See also: Plugin Properties
(from int/if/plugif.cc:137)
Name:Str (read/write)
Ship name.
See also: SetName (Ship Command), Ship Properties
(from int/if/shipif.cc:1404)
Name:Str (read/write)
Name of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:649)
Name:Str (read-only)
Name of Ufo.
See also: Ufo Properties
(from int/if/ufoif.cc:303)
Name:Int (read-only)
Name of ship or planet.
See also: Combat Participant Properties
(from int/if/vcrif.cc:732)
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
(from int/if/vcrif.cc:738)
Name.Short:Str (read/write)
Short name of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:658)
Natives:Int (read-only)
Native population size, clans.
See also: Planet Properties
(from int/if/planetif.cc:1315)
Natives.Change:Str (read-only)
Native happiness change, text.
See also: Planet Properties
(from int/if/planetif.cc:1216)
Natives.Change$:Int (read-only)
Native happiness change, numeric value.
See also: Planet Properties
(from int/if/planetif.cc:1208)
Natives.Gov:Str (read-only)
Native government name.
See also: Planet Properties
(from int/if/planetif.cc:1224)
Natives.Gov$:Int (read-only)
Native government code.
See also: Planet Properties
(from int/if/planetif.cc:1232)
Natives.Happy:Str (read-only)
Native happiness, text.
See also: Planet Properties
(from int/if/planetif.cc:1248)
Natives.Happy$:Int (read-only)
Native happiness, numeric value.
See also: Planet Properties
(from int/if/planetif.cc:1240)
Natives.Race:Str (read-only)
Native race, name.
See also: Planet Properties
(from int/if/planetif.cc:1256)
Natives.Race$:Int (read-only)
Native race, numeric value.
See also: Planet Properties
(from int/if/planetif.cc:1264)
Natives.Tax:Int (read/write)
Native tax level.
See also: SetNativeTax (Planet Command), Planet Properties
(from int/if/planetif.cc:1272)
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
(from int/if/planetif.cc:1282)
Natives.Tax.Income:Int (read-only)
Tax income from natives, megacredits.
Since: PCC2 1.99.15
See also: Planet Properties
(from int/if/planetif.cc:1296)
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
(from int/if/planetif.cc:1289)
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
(from int/if/globalif.cc:1488)
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
(from int/builtin.cc:1057)
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
(from int/if/globalif.cc:1626)
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
(from int/if/globalif.cc:1648)
NewMarker x:Int, y:Int, type:Int, [color:Int, text:Str, 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 text contains the marker's comment shown on the map. 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.
Note: this command was erroneously documented without the text argument in some versions, but has always accepted the parameters as shown above.
Since: PCC 1.0.5, PCC2 1.99.9
See also: NewCircle, NewLineRaw, NewRectangle, NewMarker, Global Commands
(from int/if/globalif.cc:1669)
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
(from int/if/globalif.cc:1583)
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
(from int/if/globalif.cc:1605)
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
(from doc/interpreter_manual.txt:2063)
This keyword is part of the For and ForEach loops, see there.
See also: Elementary Commands
(from int/statement.cc:328)
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
(from resource/core.q:552)
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
(from int/if/vcrif.cc:1005)
On event Do command On event Do commands EndDo
Execute command on event. Stores the specified command to be executed when the event happens.
The event is an identifier or ByName() expression. 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.
Version Differences: The multi-line form is supported since PCC2 2.0.8.
Since: PCC 1.0.9, PCC2 1.99.9
See also: RunHook, Elementary Commands
(from int/statement.cc:1825)
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
(from int/file.cc:542)
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.
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("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(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(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
(from int/statement.cc:1915)
There are multiple items with this name:
Orbit:Int (read-only)
Total number of ships in orbit of this planet.
See also: Planet Properties
(from int/if/planetif.cc:1330)
Orbit:Str (read-only)
Name of planet this ship is orbiting. EMPTY if none.
See also: Ship Properties
(from int/if/shipif.cc:1422)
Orbit$:Int (read-only)
Id of planet this ship is orbiting. 0 if none.
See also: Ship Properties
(from int/if/shipif.cc:1414)
Orbit.Enemy:Int (read-only)
Number of enemy (=not own) ships in orbit of this planet.
See also: Planet Properties
(from int/if/planetif.cc:1320)
Orbit.Own:Int (read-only)
Number of own ships in orbit of this planet.
See also: Planet Properties
(from int/if/planetif.cc:1325)
There are multiple items with this name:
Owner:Str (read-only)
Short name of this player.
See also: Minefield Properties, Planet Properties, Ship Properties
(from int/if/playerif.cc:249)
Owner:Str (read-only)
Short name of this player.
See also: Combat Participant Properties
(from int/if/vcrif.cc:765)
There are multiple items with this name:
Owner$:Int (read-only)
Player number.
See also: Minefield Properties, Planet Properties, Ship Properties
(from int/if/playerif.cc:210)
Owner$:Int (read-only)
Player number.
See also: Combat Participant Properties
(from int/if/vcrif.cc:759)
There are multiple items with this name:
Owner.Adj:Str (read-only)
Adjective name of this player.
See also: Minefield Properties, Planet Properties, Ship Properties
(from int/if/playerif.cc:196)
Owner.Adj:Str (read-only)
Adjective name of this player.
See also: Combat Participant Properties
(from int/if/vcrif.cc:749)
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
(from int/if/shipif.cc:1436)
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
(from int/if/playerif.cc:223)
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
(from int/file.cc:239)
There are multiple items with this name:
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
(from doc/interpreter_manual.txt:2114)
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
(from int/if/planetif.cc:51)
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
(from int/if/globalif.cc:751)
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
(from doc/interpreter_manual.txt:2256)
PlanetName(pid:Int):Str
Get name of a planet.
Since: PCC 0.99.7, PCC2 1.99.8
(from int/if/globalif.cc:728)
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
(from doc/interpreter_manual.txt:2163)
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
(from doc/interpreter_manual.txt:2219)
Planets:Int (read-only)
Number of planets this player has, according to score.
See also: Player Properties
(from int/if/playerif.cc:269)
There are multiple items with this name:
Played:Bool (read-only)
True if this planet is played.
Since: PCC 1.1.19
See also: Planet Properties
(from int/if/planetif.cc:1335)
Played:Bool (read-only)
True if this ship is played.
Since: PCC 1.1.19
See also: Ship Properties
(from int/if/shipif.cc:1430)
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
(from int/if/playerif.cc:34)
Pref(key:Str, [index:Int]):Any
Access user configuration (preferences). The first parameter is the name of a preference setting, such as "Backup.Turn" or "Label.Ship". The function returns the value of this option, an integer, boolean or string.
If the option is an array option, the second parameter must be specified as the index into the array, starting at 1.
Since: PCC2 2.0.12
See also: Functions
(from int/if/globalif.cc:900)
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
(from int/statement.cc:2070)
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
(from int/file.cc:1120)
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
(from doc/interpreter_manual.txt:2070)
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
(from int/if/richif.cc:154)
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
(from int/if/richif.cc:254)
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
(from int/if/richif.cc:349)
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
(from int/if/richif.cc:191)
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
(from int/if/richif.cc:231)
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 |
| background-color | UI color: background |
| big | bigger font size |
| blue | text color |
| contrast-color | UI color: contrast |
| dim | text color |
| fixed, tt | typewriter font |
| green | text color |
| heading-color | UI color: heading |
| input-color | UI color: text input |
| inverse-color | UI color: inverse |
| kbd, key | keycaps (Like This) |
| link-color | UI color: link |
| link-focus-color | UI color: link focus |
| link-shade-color | UI color: link shade (hover) |
| none | no style |
| red | text color |
| selection-color | UI color: link shade |
| small | smaller font size |
| static | default text color |
| u, underline | underlined text |
| white | text color |
| yellow | text color |
The UI colors are supported since 2.0.14 and can be used to match specific UI elements. Otherwise, they have no guaranteed appearance.
Since: PCC2 1.99.21
See also: RLink, RXml, Functions
(from int/if/richif.cc:276)
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
(from int/builtin.cc:1123)
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
(from int/if/richif.cc:420)
Race:Str (read-only)
Full name of this player.
See also: Player Properties
(from int/if/playerif.cc:204)
Race$:Int (read-only)
Player number.
See also: Player Properties
(from int/if/playerif.cc:210)
Race.Adj:Str (read-only)
Adjective name of this player.
See also: Player Properties
(from int/if/playerif.cc:196)
Race.Id:Int (read-only)
Race assigned to this player.
See also: Player Properties
(from int/if/playerif.cc:243)
Race.Mission:Int (read-only)
Special mission assigned to this player.
See also: Player Properties
(from int/if/playerif.cc:217)
Race.Short:Str (read-only)
Short name of this player.
See also: Player Properties
(from int/if/playerif.cc:249)
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
(from doc/interpreter_manual.txt:2284)
There are multiple items with this name:
Radius:Int (read/write)
Radius of drawing. Valid for circles, EMPTY for others.
See also: Drawing Properties
(from int/if/drawingif.cc:351)
Radius:Int (read-only)
Ion storm radius in ly.
See also: Storm Properties
(from int/if/ionif.cc:225)
Radius:Int (read-only)
Minefield radius in ly.
See also: Minefield Properties
(from int/if/mineif.cc:296)
Radius:Int (read-only)
Radius of Ufo in ly.
See also: Ufo Properties
(from int/if/ufoif.cc:308)
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
(from int/if/globalif.cc:1075)
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
(from int/if/globalif.cc:982)
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
(from int/statement.cc:2128)
There are multiple items with this name:
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
(from int/if/baseif.cc:863)
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
(from int/if/shipif.cc:215)
There are multiple items with this name:
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
(from resource/core.q:525)
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
(from resource/core.q:525)
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
(from int/builtin.cc:1068)
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
(from int/statement.cc:366)
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
(from int/statement.cc:2194)
There are multiple items with this name:
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
(from int/builtin.cc:1092)
Role:Str (read-only)
Role. One of "aggressor", "opponent". This value is typically not known for host-generated battles.
Since: PCC2 2.0.12
See also: Combat Participant Properties
(from int/if/vcrif.cc:932)
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
(from int/builtin.cc:1103)
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
(from int/if/listif.cc:181)
RunHook event:Hook
Run hook commands. Executes the commands registered for the event using On. The event is an identifier or ByName() expression. If no commands are registered for that event, nothing happens.
Since: PCC 1.0.9, PCC2 1.99.9
See also: Elementary Commands
(from int/statement.cc:2230)
SaveGame
Save current game.
See also: Global Commands
(from int/if/globalif.cc:1726)
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
(from int/if/mineif.cc:301)
There are multiple items with this name:
Score:Int (read-only)
This player's Tim-score.
See also: Player Properties
(from int/if/playerif.cc:281)
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
(from int/if/shipif.cc:569)
Score.Freighters:Int (read-only)
Number of freighters this player has, according to score.
See also: Player Properties
(from int/if/playerif.cc:295)
Seed:Int (read-only)
Random number seed. Valid only for classic combat, EMPTY for others.
See also: Combat Properties
(from int/if/vcrif.cc:957)
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
(from int/file.cc:1163)
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
(from int/statement.cc:2308)
Selection.Layer:Int (read/write)
Current selection layer. A number from 0 to 7.
See also: Global Properties
(from int/if/globalif.cc:424)
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
(from int/statement.cc:2443)
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
(from resource/core.q:486)
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
(from int/if/globalif.cc:1788)
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
(from int/if/globalif.cc:1852)
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
(from int/if/planetif.cc:266)
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
(from int/file.cc:462)
SetColonistTax n:Int
Set colonist tax.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Colonists.Tax, Planet Commands
(from int/if/planetif.cc:347)
SetColor c:Int
Set drawing color.
Since: PCC 1.0.14, PCC2 1.99.20
See also: Color (Drawing Property), Drawing Commands
(from int/if/drawingif.cc:74)
There are multiple items with this name:
SetComment s:Str
Set drawing comment.
Since: PCC 1.0.14, PCC2 1.99.20
See also: Comment (Drawing Property), Drawing Commands
(from int/if/drawingif.cc:60)
SetComment s:Str
Set planet comment.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Comment (Planet Property), Planet Commands
(from int/if/planetif.cc:359)
SetComment s:Str
Set ship comment.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Comment (Ship Property), Ship Commands
(from int/if/shipif.cc:94)
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
(from int/if/shipif.cc:123)
There are multiple items with this name:
SetFCode fc:Str
Set planet friendly code.
Since: PCC 1.0.5, PCC2 1.99.9
See also: FCode (Planet Property), Planet Commands
(from int/if/planetif.cc:376)
SetFCode fc:Str
Set ship friendly code.
Since: PCC 1.0.5, PCC2 1.99.9
See also: FCode (Ship Property), Ship Commands
(from int/if/shipif.cc:111)
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
(from int/if/shipif.cc:515)
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
(from resource/core.q:458)
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
(from int/file.cc:488)
There are multiple items with this name:
SetMission number:Int
Set starbase mission.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Planet Commands
(from int/if/baseif.cc:876)
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
(from int/if/shipif.cc:159)
SetName n:Str
Set ship name.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Name (Ship Property), Ship Commands
(from int/if/shipif.cc:147)
SetNativeTax n:Int
Set native tax.
Since: PCC 1.0.5, PCC2 1.99.9
See also: Natives.Tax, Planet Commands
(from int/if/planetif.cc:388)
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
(from int/if/shipif.cc:135)
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
(from int/file.cc:501)
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
(from int/if/baseif.cc:887)
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
(from int/if/shipif.cc:228)
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
(from int/file.cc:475)
Shape:Int (read/write)
Marker shape. Valid for markers, EMPTY for others.
See also: Drawing Properties
(from int/if/drawingif.cc:362)
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
(from int/statement.cc:2263)
Shield:Int (read-only)
Initial shield level in percent.
See also: Combat Participant Properties
(from int/if/vcrif.cc:775)
There are multiple items with this name:
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
(from doc/interpreter_manual.txt:2104)
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
(from int/if/shipif.cc:51)
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
(from doc/interpreter_manual.txt:2292)
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
(from doc/interpreter_manual.txt:2248)
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
(from int/if/globalif.cc:700)
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
(from resource/core.q:669)
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
(from doc/interpreter_manual.txt:2154)
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
(from doc/interpreter_manual.txt:2211)
Ships:Int (read-only)
Number of ships this player has, according to score.
See also: Player Properties
(from int/if/playerif.cc:275)
Ships.Capital:Int (read-only)
Number of capital ships this player has, according to score.
See also: Player Properties
(from int/if/playerif.cc:289)
Ships.Freighters:Int (read-only)
Total number of freighters (from this player's score information).
See also: Global Properties
(from int/if/playerif.cc:306)
Ships.Total:Int (read-only)
Total number of ships (from this player's score information).
See also: Global Properties
(from int/if/playerif.cc:301)
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
(from int/if/baseif.cc:350)
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
(from int/if/baseif.cc:323)
Shipyard.Id:Int (read-only)
Id of ship being worked on by starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:335)
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
(from int/if/baseif.cc:340)
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
(from int/builtin.cc:1134)
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
(from int/file.cc:213)
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
(from int/if/hullif.cc:219)
There are multiple items with this name:
Speed:Str (read-only)
Ion storm speed, as human-readable string.
See also: Storm Properties
(from int/if/ionif.cc:235)
Speed:Str (read-only)
Speed, as human-readable string. If the hyperdrive is active, reports "Hyperdrive", otherwise "Warp x".
See also: Ship Properties
(from int/if/shipif.cc:1450)
Speed:Str (read-only)
Speed, as human-readable string.
See also: Ufo Properties
(from int/if/ufoif.cc:321)
There are multiple items with this name:
Speed$:Int (read-only)
Ion storm speed (warp factor).
See also: Storm Properties
(from int/if/ionif.cc:230)
Speed$:Int (read/write)
Speed (warp factor).
See also: SetSpeed (Ship Command), Ship Properties
(from int/if/shipif.cc:1443)
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
(from int/if/specif.cc:730)
Speed$:Int (read-only)
Speed (warp factor).
See also: Ufo Properties
(from int/if/ufoif.cc:313)
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
(from int/builtin.cc:1145)
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
(from doc/interpreter_manual.txt:2235)
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
(from int/statement.cc:2269)
There are multiple items with this name:
Status:Str (read-only)
Ion storm status, as human-readable string.
See also: Storm Properties
(from int/if/ionif.cc:247)
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
(from int/if/vcrif.cc:854)
There are multiple items with this name:
Status$:Bool (read-only)
Ion storm status.
See also: Storm Properties
(from int/if/ionif.cc:240)
Status$:Int (read-only)
Battle result, from the point-of-view of this unit. This is an integer:
See also: Combat Participant Properties
(from int/if/vcrif.cc:871)
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
(from int/statement.cc:388)
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
(from int/if/baseif.cc:393)
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
(from int/if/baseif.cc:381)
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
(from int/if/baseif.cc:369)
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
(from int/if/baseif.cc:375)
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
(from int/if/baseif.cc:387)
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
(from int/if/ionif.cc:31)
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
(from int/builtin.cc:1164)
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
(from int/builtin.cc:1177)
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
(from int/builtin.cc:1194)
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
(from int/statement.cc:2651)
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
(from int/statement.cc:2503)
Supplies:Int (read-only)
Supplies on this planet.
See also: Planet Properties
(from int/if/planetif.cc:1341)
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
(from int/intglobal.cc:66)
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
(from int/if/guiif.cc:1265)
System.ExitRace
Leave current race. Saves the game and returns to the game selection menu.
Since: PCC2 1.99.10
See also: Global Commands
(from int/if/guiif.cc:1251)
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
(from int/if/guiif.cc:2116)
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
(from int/if/globalif.cc:360)
System.GameType:Str (read-only)
Registration flag. One of "Shareware" or "Registered".
See also: Global Properties
(from int/if/globalif.cc:517)
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
(from int/if/globalif.cc:511)
System.Host:Str (read-only)
Name of Host program. Values in use so far:
See also: Global Properties
(from int/if/globalif.cc:460)
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
(from int/if/globalif.cc:476)
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
(from int/if/globalif.cc:496)
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
(from int/if/globalif.cc:431)
System.Local:Str (read-only)
Local file format. Reports the file format PCC uses to store your player files:
See also: Global Properties
(from int/if/globalif.cc:329)
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
(from int/if/plugif.cc:97)
System.Program:Str (read-only)
Name of the program executing the script. Values in use so far:
See also: Global Properties
(from int/if/globalif.cc:439)
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
(from int/if/globalif.cc:523)
System.RegStr1:Str (read-only)
Your registration key. This is the first line (name or registration number) of the key.
See also: Global Properties
(from int/if/globalif.cc:536)
System.RegStr2:Str (read-only)
Your registration key. This is the second line (registration number or date) of the key.
See also: Global Properties
(from int/if/globalif.cc:542)
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
(from int/if/globalif.cc:347)
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
(from int/if/globalif.cc:401)
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
(from int/if/globalif.cc:126)
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
(from int/if/globalif.cc:447)
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
(from int/if/globalif.cc:453)
Tag:Int (read/write)
Marker tag. Usually an integer created with Atom().
See also: Drawing Properties
(from int/if/drawingif.cc:373)
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
(from int/builtin.cc:1205)
There are multiple items with this name:
Task:Bool (read-only)
True if this planet has an Auto Task.
See also: Planet Properties
(from int/if/planetif.cc:1346)
Task:Bool (read-only)
True if this ship has an auto task.
See also: Ship Properties
(from int/if/shipif.cc:1463)
Task.Base:Bool (read-only)
True if this planet's starbase has an Auto Task.
See also: Planet Properties
(from int/if/planetif.cc:1351)
Team:Int (read-only)
Team this player is in.
See also: Player Properties
(from int/if/playerif.cc:257)
Tech:Int (read-only)
Tech level of this component.
See also: Beam Properties, Engine Properties, Hull Properties, Torpedo Properties
(from int/if/specif.cc:610)
There are multiple items with this name:
Tech.Beam:Int (read-only)
Beam tech level on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:225)
Tech.Beam:Int (read-only)
Tech level of this component.
See also: Beam Properties
(from int/if/specif.cc:610)
There are multiple items with this name:
Tech.Engine:Int (read-only)
Engine tech level on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:295)
Tech.Engine:Int (read-only)
Tech level of this component.
See also: Engine Properties
(from int/if/specif.cc:610)
There are multiple items with this name:
Tech.Hull:Int (read-only)
Hull tech level on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:300)
Tech.Hull:Int (read-only)
Hull tech level.
See also: Hull Properties, Ship Properties
(from int/if/specif.cc:616)
There are multiple items with this name:
Tech.Torpedo:Int (read-only)
Torpedo tech level on starbase. EMPTY if no base.
See also: Planet Properties
(from int/if/baseif.cc:363)
Tech.Torpedo:Int (read-only)
Tech level of this component.
See also: Torpedo Properties
(from int/if/specif.cc:610)
Temp:Int (read-only)
Temperature class, human-readable.
See also: Planet Properties
(from int/if/planetif.cc:1361)
Temp$:Int (read-only)
Temperature, numeric value.
See also: Planet Properties
(from int/if/planetif.cc:1356)
Text:Str() (read-only)
Message text, line by line.
See also: Incoming Message Properties
(from int/if/msgif.cc:222)
Torp:Str (read-only)
Torpedo type, full name.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1498)
Torp$:Int (read-only)
Torpedo type.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1468)
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
(from int/if/shipif.cc:1473)
Torp.LCount:Int (read-only)
Number of torpedo launchers on this ship.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1485)
Torp.LMax:Int (read-only)
Maximum number of torpedo launchers on this ship.
See also: Hull Properties, Ship Properties
(from int/if/hullif.cc:252)
Torp.Short:Str (read-only)
Torpedo type, short name.
See also: Combat Participant Properties, Ship Properties
(from int/if/shipif.cc:1490)
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
(from int/if/specif.cc:40)
Total.Capital:Int (read-only)
Total number of capital ships (from this player's score information).
See also: Global Properties
(from int/if/playerif.cc:311)
Transfer.Ship:Bool (read-only)
True if cargo is being transported to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1574)
Transfer.Ship.Colonists:Int (read-only)
Number of colonists being transferred to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1506)
Transfer.Ship.D:Int (read-only)
Amount of Duranium being transferred to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1514)
Transfer.Ship.Id:Int (read-only)
Id of cargo transfer target ship.
See also: Ship Properties
(from int/if/shipif.cc:1522)
Transfer.Ship.M:Int (read-only)
Amount of Molybdenum being transferred to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1530)
Transfer.Ship.N:Int (read-only)
Amount of Neutronium being transferred to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1538)
Transfer.Ship.Name:Str (read-only)
Name of cargo transfer target ship.
See also: Ship Properties
(from int/if/shipif.cc:1546)
Transfer.Ship.Supplies:Int (read-only)
Amount of Supplies being transferred to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1566)
Transfer.Ship.T:Int (read-only)
Amount of Tritanium being transferred to another ship.
See also: Ship Properties
(from int/if/shipif.cc:1558)
Transfer.Unload:Bool (read-only)
True if cargo is being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1652)
Transfer.Unload.Colonists:Int (read-only)
Number of colonists being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1582)
Transfer.Unload.D:Int (read-only)
Amount of Duranium being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1590)
Transfer.Unload.Id:Int (read-only)
Id of planet cargo is being unloaded to. 0 for jettison.
See also: Ship Properties
(from int/if/shipif.cc:1598)
Transfer.Unload.M:Int (read-only)
Amount of Molybdenum being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1606)
Transfer.Unload.N:Int (read-only)
Amount of Neutronium being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1614)
Transfer.Unload.Name:Int (read-only)
Name of planet cargo is being unloaded to. "Jettison" for jettison.
See also: Ship Properties
(from int/if/shipif.cc:1622)
Transfer.Unload.Supplies:Int (read-only)
Amount of Supplies being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1644)
Transfer.Unload.T:Int (read-only)
Amount of Tritanium being unloaded to a planet or deep space.
See also: Ship Properties
(from int/if/shipif.cc:1636)
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
(from int/if/globalif.cc:1058)
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
(from int/builtin.cc:1218)
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
(from int/if/globalif.cc:949)
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
(from int/statement.cc:2780)
Turn:Int (read-only)
Turn number.
See also: Global Properties
(from int/if/globalif.cc:548)
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
(from int/if/globalif.cc:575)
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
(from int/if/globalif.cc:556)
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
(from int/if/globalif.cc:565)
There are multiple items with this name:
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
(from int/file.cc:226)
Type:Str (read-only)
Type of drawing.
See also: Type$ (Drawing Property), Drawing Properties
(from int/if/drawingif.cc:380)
Type:Str (read-only)
Minefield type, human-readable. One of "Web Mines" or "Mines".
See also: Minefield Properties
(from int/if/mineif.cc:317)
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
(from int/if/planetif.cc:1376)
Type:Str (read-only)
Classification of ship. Possible values are:
See also: Ship Properties
(from int/if/shipif.cc:1669)
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
(from int/if/ufoif.cc:329)
Type:Str (read-only)
Classification of this unit. Possible values are:
See also: Combat Participant Properties
(from int/if/vcrif.cc:782)
There are multiple items with this name:
Type$:Int (read-only)
Type of drawing.
| Type$ | Type |
|---|---|
| 0 | Line |
| 1 | Rectangle |
| 2 | Circle |
| 3 | Marker |
See also: Drawing Properties
(from int/if/drawingif.cc:394)
Type$:Bool (read-only)
True if this is a web mine field.
See also: Minefield Properties
(from int/if/mineif.cc:312)
Type$:Int (read-only)
Unit type identification value.
Valid only for classic combat, EMPTY for others.
See also: Combat Properties
(from int/if/vcrif.cc:977)
There are multiple items with this name:
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
(from int/if/planetif.cc:1369)
Type.Short:Str (read-only)
Classification of ship, short. This is the first letter of the Type, see there.
See also: Ship Properties
(from int/if/shipif.cc:1660)
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
(from int/if/vcrif.cc:791)
UCase(s:Str):Str
Convert string to upper case. Returns the string with all ASCII characters converted to lower-case.
If the parameter is EMPTY, returns EMPTY.
Since: PCC2 2.0.8
See also: LCase, Elementary Functions
(from int/builtin.cc:1229)
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
(from int/if/guiif.cc:604)
UI.Directory:Str (read/write)
Current directory. This is the default directory for operations like UI.FileWindow.
See also: Global Variables
(from resource/core.q:1194)
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
(from int/if/guiif.cc:693)
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
(from int/if/guiif.cc:265)
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
(from int/if/guiif.cc:795)
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
(from int/if/guiif.cc:822)
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
(from int/if/guiif.cc:1227)
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
(from int/if/guiif.cc:329)
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
(from int/if/guiif.cc:487)
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
(from int/if/guiif.cc:424)
UI.KeymapInfo
Open keymap debugger for current keymap.
Since: PCC2 1.99.10
See also: Global Commands
(from int/if/guiif.cc:1211)
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
(from int/if/guiif.cc:1049)
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
(from int/if/guiif.cc:993)
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
(from int/if/guiif.cc:908)
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
(from int/if/guiif.cc:715)
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
(from int/if/guiif.cc:885)
UI.PlanetInfo pid:Int
Open planet information for planet pid.
Since: PCC2 1.99.10
See also: Global Commands
(from int/if/guiif.cc:1194)
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
(from int/if/guiif.cc:868)
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
(from resource/core.q:1200)
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
(from resource/core.q:1185)
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
(from int/if/globalif.cc:137)
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
(from int/if/guiif.cc:1110)
UI.SelectionManager
Open selection manager.
Since: PCC2 1.99.10
See also: Global Commands
(from int/if/guiif.cc:1181)
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
(from int/if/guiif.cc:236)
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
(from int/if/globalif.cc:144)
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
(from int/if/ufoif.cc:32)
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
(from int/if/vcrif.cc:1012)
Units:Int (read-only)
Number of mine units.
See also: Minefield Properties
(from int/if/mineif.cc:323)
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
(from doc/interpreter_manual.txt:2275)
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
(from int/if/objif.cc:110)
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
(from doc/interpreter_manual.txt:2076)
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
(from doc/interpreter_manual.txt:2085)
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
(from int/statement.cc:2875)
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
(from int/builtin.cc:1240)
Value:Any (read/write)
The value of this hash element.
See also: Hash Element Properties
(from int/hash.cc:178)
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
(from int/if/vcrif.cc:34)
Visible.Planet:Int (read-only)
Distance from which Ufo can be seen from a planet, in ly.
See also: Ufo Properties
(from int/if/ufoif.cc:336)
Visible.Ship:Int (read-only)
Distance from which Ufo can be seen from a ship, in ly.
See also: Ufo Properties
(from int/if/ufoif.cc:341)
Voltage:Int (read-only)
Ion storm voltage, in MeV.
See also: Storm Properties
(from int/if/ionif.cc:252)
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
(from resource/core.q:245)
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
(from int/if/shipif.cc:1720)
Waypoint.DX:Int (read-only)
X distance to waypoint.
See also: Ship Properties
(from int/if/shipif.cc:1690)
Waypoint.DY:Int (read-only)
Y distance to waypoint.
See also: Ship Properties
(from int/if/shipif.cc:1695)
Waypoint.Dist:Num (read-only)
Distance to waypoint, in ly. This can be a fractional number.
See also: Ship Properties
(from int/if/shipif.cc:1681)
Waypoint.Planet:Int (read-only)
Id of planet at waypoint.
See also: PlanetAt(), Ship Properties
(from int/if/shipif.cc:1700)
Waypoint.X:Int (read-only)
X location of waypoint.
See also: Ship Properties
(from int/if/shipif.cc:1710)
Waypoint.Y:Int (read-only)
Y location of waypoint.
See also: Ship Properties
(from int/if/shipif.cc:1715)
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
(from int/statement.cc:2933)
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
(from int/if/msgif.cc:355)
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
(from int/builtin.cc:1249)