Starship Commands

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.

  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.

  CargoUnload cargo, options

Unload the specified cargo amount to the planet this ship is orbiting. For a detailed description of the parameters, see `CargoTransfer'.

When the ship is not orbiting a planet, this command can be used to jettison cargo. To prevent accidental jettisoning, the options must contain the "J" option or the command will fail.

This command is equivalent to

  CargoUpload CMul(cargo, -1), options

  CargoUpload cargo, options

Load the specified cargo amount from the planet this ship is orbiting. For a detailed description of the parameters, see `CargoTransfer'.

When the ship is not orbiting a planet, this command can be used to get back cargo you jettisoned (using `CargoUnload' or the normal cargo transfer screen). The options string must contain the "J" option for this to work.

This command is equivalent to

  CargoUnload CMul(cargo, -1), options

or, when at a planet

  With Planet(Orbit) Do CargoTransfer Ship.Id, cargo, option

  CargoUploadWait cargo, options

This command is like `CargoUpload', but it will wait instead of failing when there is not enough cargo. For example, if you want your ship to carry 200 kt fuel, you can use

  CargoUploadWait "200n"

The ship will then load 200 kt fuel if available; if not, it will wait until you dump more fuel on the planet or mines provide it.

Note that this command will not prevent you from unloading cargo manually. If the above command loads 100 kt, you can use the normal cargo transfer to unload them again, and when the script runs next time, it will see these 100 kt and fetch them - continuing satisfied, because it loaded 200 kt total.

See `CargoUpload' for a description of the parameters. The second parameter is optional. 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).

  MoveTo x, y

Set the waypoint to (x,y), and suspend until you're there. That is, the code

  MoveTo 1240, 1500
  MoveTo 1400, 1520

will move the ship to (1240,1500) and then to (1400,1520). (Note: when you enter these commands at the console, they will attempt to run in parallel. This will not work because "MoveTo" obtains the "sXXX.waypoint" lock.)

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

  MoveTowards x, y

Set the waypoint to (x,y), and move one turn into that direction. This is equivalent to doing `SetWaypoint' and `WaitOneTurn' in a row. This command is intended to be used in auto tasks.

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

  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.

  SetComment comment

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

  SetEnemy player-number

Set this ship's primary enemy to the specified player number (0..11). Fails if you don't own the ship.

  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.

  SetFleet new-fleet

Sets the fleet this ship is member of. new-fleet can be one of the following:

• 0 - the ship is not member of any fleet;
• the ship's id - the ship is in a fleet alone;
• a fleet id - the ship becomes member of the specified fleet.

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.

 SetFleetName name

Set the name of the fleet this ship is member of. Fails if this ship is not member of a fleet.

This is a library routine.

  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.

  SetName new-name

Change this ship's name to the specified string.

  SetSpeed warp

Change this ship's warp factor to the specified value (0..9). There's no shortcut for the Hyperdrive like on the ship screen, to do that, use

  SetSpeed 2
  SetFCode "HYP"

Fails if you don't own the ship, the parameter is outside the allowed range, or the ship is member of a fleet.

  SetWaypoint x, y

Change the ship's waypoint to the specified coordinates. When playing on a wrapped map, this sets the waypoint to move the shortest possible way to the specified coordinates.

See also the `MoveTo' library command.

Fails if you don't own the ship, parameters are out of range, or the ship is member of a fleet.

  Unmark

Unmarks the current object, like `Mark 0'.