egosoft.com

readme wrote: What's the script for?

As the name suggests, the script allows you to exchange freight between ships owned by the player. The player no longer needs to be in either of the ships or even in the same sector to transfer freight from one ship to another.

Attention: Executing this order on a ship cancels all other orders. So you have to issue new orders to your ship afterwards.




What does it do?

As stated, it transfers freight from one player owned ship to any other player owned ship within transporter range. Therefore both ships have to be in space and in the same sector. Naturally at least one of the ships has to be equipped with a transporter device. If you are transferring shields, they will be installed on the targeted ship automatically if they are better than the currently installed shields. Weapons will not be automatically installed. They just get transferred into the cargo hold of the target ship and have to be installed manually via the ships menu, if desired.




What can't it do?

Because of limitations of the script editor, you cannot choose a docked ship as a target, so both ships have to be in space to make the transport work. If a ship is docked, the command is not available. It is not possible to transfer ship upgrades or extensions (like the transporter device itself, freight scanner, or anything else like this). If the player ship is one of the two ships involved in the exchange, then it is possible to transfer command extensions using this command.
The script editor doesn't know if the command was executed successfully, so you always get the "Command Accepted" message when the command is run, but this doesn't necessarily mean that the freight really got transferred. If the transport failed for any reason, you will get an error message written to the player log (see Error messages). If the script successfully transferred the freight, no message is written (there's already enough spam within the log book). Another limitation of the script is that it can't check if there is a third ship equipped with a transporter device in range, so at least one of the ships taking part in the transfer has to be equipped with a transporter device. Otherwise, the transport will fail and an error message will show up in your log.



What won't it do?

There are some fictional and logical limitations to the script.
As stated already, to transport the freight there has to be a transporter device installed in one of the ships involved.
The transfer will only be successful within the normal transporter range of the transporter device. The range is five km, and both ships must be within the same sector. If the ships are flying around when you try to transport cargo, it might occur that they leave transporter range, so it's best to stop them before you command them to exchange their cargo.
Only player owned ships can be targeted for transport.
Negative amounts of freight are not allowed. If you want to transfer a ware back, you must execute the command from the other ship.
You cannot transfer freight to the same ship.
To keep it simple (I'm not a good scripter, this is just the result of playing around to get familiar with the script editor ) the script will only transfer the exact amount of goods given during the command routine. If this is not possible for any reason (cargo limitations or not enough wares), no freight will be transferred and an error message will be created. This is true even if the transport of a smaller amount of wares would have been possible.
The script will not transfer any freight which is currently installed on the source ship (e.g shields and lasers). So you'll have to uninstall them first if you want to transport them. ATTENTION: Missiles are handled differently, they will always get transfered even if they are the currently selected missile. Keep this in mind, or else the source ship may suddenly have no more missiles installed.
Finally, even if it would be possible, the script will not tranfer wares to "non-ships" like Squash Mines, Navigation Relay Satellites, Advanced Satellites, Lasertowers, and Fighterdrones. (ATTENTION: In modifed universes, targets might exist which are not specifically excluded by the script routine and so freight might get transfered without the chance to transport it back. This could cause the loss of the freight. The script should be adjusted for these mods or used with caution.)



Error Messages

As said, every failed attempt to transfer freight creates an error message in the player log. Here is an overview of the possible messages and their meaning (though I hope they are self explanatory in most cases)

- "ships are the same." - The source ship is identical to the targeted ship.
- "ships are in different sectors." - The source ship is not in the same sector as the targeted ship. This might be caused by movement of both ships (docking somewhere or jumping away) or you might have accidentally switched to another sector in the galaxy map.
- "ships are not in transporter range of each other." - The ships are within the same sector, but the distance between them is bigger than 5km.
- "transporter device needed." - At least one of the ships must have a transporter device installed.
- "not enough freight to transfer." - The specified amount of goods is higher than the amount of this ware in the cargo hold. This may mean that you are trying to transfer installed equipment (e.g. shields or lasers). - See: 4. What won't it do?
- "not enough free cargo space." - The target ship has insufficient room in its cargo hold. This might mean that you are trying to transfer too much freight or it might mean that the target ship is not capable of carrying the freight's transport class.
- "negative amount." - The amount of freight you are trying to transfer is 0 or below, which is pretty senseless To transport freight from the target ship to the source ship, just execute the command from the other ship.
- "target is not a ship." - The target is not a real ship (like Navigation Satellites, Lasertowers, Squash Mines or Fighterdrones). ATTENTION: Modified universes may define other objects as player owned, which might not be recognized as invalid targets by the script. The command might then be executed and the freight may get lost.



How to use it

After installing the script, you will see on every player owned ship a new command "Transfer freight ..." in the "Special..." command category.
After selecting the command, choose the ware you want to transfer from the cargo hold of the executing ship. Then enter the amount of goods you want to transfer (only positive integers will work). Next, the galaxy map opens and you select the target ship to transfer the wares to. Hit enter to confirm your inputs or "Esc" to cancel the command. After you choose the target ship and confirm your selection by hitting enter you're brought back to the ship command menu. The freight Should be transferred. If not, an error message should be shown in your player log (see 5. Error Messages)



How to use it (fast)

Step -> What to do

1 -> Select command
2 -> Choose freight
3 -> Enter amount
4 -> Select target ship
5 -> done

VincentTH wrote: It would be much better that the 1 of the 2 ships for which the command was issued to, start with a "follow" order. For now, it must be done by hand first, before the exchange command can be issued.
My 2 cents.

Carl Sumner wrote:I suspect that the script language does not allow access to ships in stations, though.

VincentTH wrote:moggy2,

I tried it but give up, as it simply does not work for me. I have mentioned the reason for it above.

VincentTH wrote:The command "Ship A follows ship B" would not cut it, because if B is stationary, A would not move. Only a script (or the player fliying ship A) knows how to place ship A within 5km of ship B.

Burianek wrote:when you issue a follow command, all of the follower ships will form up in the formation set in the command console of the lead ship. That's how that works.

moggy2 wrote:another thought.

When you don't have a transporter device available the command still appears, but greyed out. It would be nice if it just dissappeared instead.

• - required wares not present = command not displayed at all
  - required wares present but 'situation' ship is in isn't correct (wrong item targeted, no homebase set, etc.) = command displayed greyed out
  - required wares present and ship is in correct 'situation' = command is useable and active