Planet Commands

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.

  Autobuild

Performs a standard auto build, like [A] on a build screen. Fails if you don't own the planet.

  BuildBase
  BuildBase flag

If the flag is true or not specified, attempts to build a starbase. If the flag is false, cancels a pending starbase build order. Fails if you don't own the planet, don't have the required resources, or there already is a base.

  BuildDefense amount, flag
  BuildFactories amount, flag
  BuildMines amount, flag
  BuildBaseDefense amount, flag

Build 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.

Optionally, you can specify the flag "n", as in

  BuildMines 100, "n"

Instead of failing when you can not build that many structures, this will build (resp. scrap) as many as possible, and set the variable `Build.Remainder' to the number of structures that could not be built. If the above command is able to build only 75 mines, `Build.Remainder' will be set to 25. When 100 mines can be built, `Build.Remainder' will be zero.

Compare `CargoTransfer'.

  BuildDefenseWait amount
  BuildFactoriesWait amount
  BuildMinesWait amount
  BuildBaseDefenseWait amount

Build the specified number of structures. When not all the requested structures can be built at once, these routines wait accordingly (until the appropriate resources or colonist population is available).

See also `BuildFactories' and friends. These commands are actually library commands.

  BuildHulls type, amount, flags
  BuildEngines type, amount, flags
  BuildBeams type, amount, flags
  BuildLaunchers type, amount, flags

Build the specified amounts of the specified starship part and place it in starbase storage. Parts are destroyed/sold if amount is negative. Fails if you do not have a starbase at the current planet, do not have the required resources, or if the requested amount cannot be bought or scrapped.

The tech level is raised automatically if required. When scrapping parts, you can only destroy parts bought this turn, and you cannot destroy parts currently in use for the ship build order (see `BuildShip').

The type specifies what type to build:

• a hull Id (1..105) for `BuildHulls'. You cannot build all hulls;
• an engine number (1..9) for `BuildEngines';
• a beam number (1..10) for `BuildBeams';
• a torpedo system number (1..10) for `BuildLaunchers'.

The amount is the number of items to buy, or negative to scrap them.

The flags parameter is optional. When it is given as "n", this function does not fail if it cannot build or scrap the requested amount. Instead, it performs the operation as far as possible, and sets `Build.Remainder' to the number of parts not built.

For example,

  BuildBeams 8, 10

builds ten Phasers (type 8) if possible. If money suffices only for three of them, it fails. Likewise,

  BuildBeams 8, 10, "n"

tries to build these ten Phasers, but sets `Build.Remainder' to the number of Phasers not built (7 in this case). Finally,

  BuildBeams 8, -Storage.Beams(8), "n"

scraps all unused Phasers (with the usual restriction that you cannot scrap things built in earlier turns).

  BuildShip hull, engine, bt, bc, tt, tc
  BuildShip 0

When used with the first form, attempts to build the specified ship. The first two arguments are mandatory, the rest is optional. They have the following meanings:

• hull is the numeric hull Id (e.g., 61=Emerald: `Hull(61).Name = "EMERALD CLASS BATTLECRUISER"'), 1 to 105. You can find out these numbers by looking at the ship specification window, or with CCSHIPS;
• engine is the engine number (1 to 9), where 1 is StarDrive 1, and 9 is Transwarp Drive;
• bt is the beam type (1..10), bc is the beam count. If these arguments are zero, or you don't specify a beam type, the ship is built without beam weapons. As a shorthand, if bc is -1 or not specified (EMPTY), the maximum possible value is used;
• tt is the torpedo launcher type (1..10), tc is the launcher count. The same as for beams also holds here.

Engine and fighter bay count are computed internally, you have no choice there anyway. Parts from storage are automatically used.

If one of the mandatory arguments is EMPTY, nothing happens. This command has the same function as the build screen: it automatically builds necessary parts and upgrades tech levels. It fails if you don't have a starbase, you're lacking resources, or can't upgrade your tech levels, or the specified parameters are out of range (building a freighter with weapons is rejected).

Caveat emptor: if you only specify hull and engine for a battleship, the ship is built without weapons.

`BuildShip 0' cancels a pending build order.

  BuildTorps type, amount, flags
  BuildFighters amount, flags

Build the specified amounts of torpedoes or fighters, or scraps them if amount is negative. Fails if you do not have a starbase at the current planet, do not have the required resources, or if the requested amount cannot does not fit on the target or can't be scrapped.

For `BuildTorps', type is a number between 1 and 10 designating the torpedo type (same as the index to the `Torpedo()' function).

The flags are optional and can contain:

• "n": if the requested amount can't be built or scrapped, do as many as possible and store the remaining amount in `Build.Remainder'.
• a ship Id: store the new amount on the specified ship, not in the base's storage.

For example,

  BuildFighters 60, "n"

builds as many fighters as possible (at most 60 fit in the starbase).

  BuildTorps 10, 50, 150

builds 50 type-10 torpedoes and loads them on ship 150. The torpedo tech level is raised if needed.

  BuildTorps 10, 50, "n" & 150

does the same, but if you do not have the resources to build 50 torpedoes, or the ship has insufficient free cargo space, it will build less. When no torps are built, the tech level is not touched.

  CargoTransfer sid, cargo, options

Transfers the specified cargo to ship sid. cargo is a cargo set, it may also contain negative values to beam cargo the other way 'round.

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

• "O": use overload mode;
• "S": sell supplies on-the-fly, if possible (only possible if planet participates in transfer);
• "N": don't generate an error when the cargo can not completely be transferred. Instead, sets the variable Cargo.Remainder accordingly;
• "J": used with `CargoUnload' and `CargoUpload': permit use of jettison transporter;
• a ship id: use that ship as proxy.

For example,

  CargoTransfer 10, "300n"

transfers 300 kt Neutronium to ship 10. It will fail with an error ("Cargo transfer failed") 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 Planets rules do not allow asking foreign ships for stuff; the other ship must explicitly send it.

  CargoTransferWait sid, cargo, options

This command is like `CargoTransfer', but it will wait instead of failing when there is not enough cargo. See `CargoUploadWait' for more information and an example.

This library routine can be called from planets and ships. The third parameter is optional, see `CargoTransfer' for a description.

  EnqueueShip hull, engine, bt, bc, tt, tc

Can only be called on starbases. This routine attempts to build a ship of the specified type at this starbase (the last four arguments are optional). The meaning of the arguments is exactly the same as for `BuildShip', see there for an explanation. This function will suspend the script until the build order was successfully delivered (not performed!). Thus,

  EnqueueShip 15, 9
  EnqueueShip 1, 6, 2, -1

will first build a small freighter (type 15) with Transwarp Drives, then an outrider (type 1) with Tech 6 engines and X-Ray lasers.

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

  FixShip sid                        % starbase
  FixShip                            % ship

First version: Change the shipyard order of the starbase to repair the specified ship. Second version: order the starbase this ship is orbiting to repair the ship. The new order unconditionally overrides the old one. In the first version, if sid is zero, cancels any pending order. Fails if there is no starbase, or the rules forbid you to repair the specified ship.

  FixShipWait sid                    % starbase
  FixShipWait                        % ship

Like `FixShip', but waits until the order can be successfully given. For example, to repair many ships, one after the other, you can give multiple `FixShipWait' orders at the starbase or the ships.

This is a library routine.

  Mark
  Mark flag

Marks the current object if the flag is true or not specified, unmarks it otherwise (same as `Unmark' command).

  RecycleShip sid                    % starbase
  RecycleShip                        % ship

First version: Change the shipyard order of the starbase to recycle the specified ship. Second version: order the starbase this ship is orbiting to recycle the ship. The new order unconditionally overrides the old one. In the first version, if sid is zero, cancels any pending order. Fails if there is no starbase, or the rules forbid you to recycle the specified ship.

  RecycleShipWait sid                % starbase
  RecycleShipWait                    % ship

Like `RecycleShip', but waits until the order can be successfully given. For example, to recycle many ships, one after the other, you can give multiple `RecycleShipWait' orders at the starbase or the ships.

This is a library routine.

  SellSupplies count, flag

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.

Compare `CargoTransfer'.

  SetColonistTax rate
  SetNativeTax rate

Changes the tax rate. Fails if you don't own the planet, there are no natives (`SetNativeTax'), or the rate is out of range (0..100 allowed).

  SetComment comment

Changes the comment of the planet/ship. Note that you can also assign to the `Comment' property directly.

  SetFCode fc

Changes the friendly code. No validity checks: if the friendly code is invalid, PCC will still perform the change, but the Host will most likely refuse to accept it. Fails if you don't own the object.

Invalid friendly codes are those which contain high-ASCII characters (code >127); depending on the host version, some standard ASCII characters may be rejected as well.

  SetMission mission                 % starbase
  SetMission m, i, t                 % ship

Changes the mission of the current object to the specified value. For the ship version, the i and t parameters can be omitted or EMPTY.

Fails if you don't own the target object.

  SetTech slot, tech

Changes the tech level slot to tech. This requires a starbase and the appropriate resources to be present at the planet. The slot is a value between 1 and 4:

• 1: engine tech
• 2: hull tech
• 3: beam tech
• 4: torpedo tech

(same order as on starbase screen and tech upgrade window).

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.

  Unmark

Unmarks the current object, like `Mark 0'.