@ [skip|else] if [not]|while [not]| [RetVar/IF] = [RefObj]
turn turret [Var/Number]
to target [Var/Ship/Station]
: timeout= [Var/Number]
Turns the specified turret's camera to face [Var/Ship/Station]
This instruction is used to enforce a relationship between a turret's camera and its guns. The general structure of a script that will control a turret, is:
1. Obtain a target
2. Turn the turret to face the target
3. If FLRET_FIREFREE is returned when you turn the turret, then fire lasers on target .
4. Repeat from step 2 until one side cries “Hold, enough!”
It should be noted that the timeout time only indicates how much time the camera has to turn to face the target – not how long the instruction will actually take to execute.
In practise, the delay introduced by this instruction ranges in the 150-250ms range regardless of the timeout specified. This makes it very difficult (read impossible) to fire some weapons, such as mass drivers, at anywhere near their rated firing rate unless the turn-turret step is ignored.*
Other weapons, such as HEPT/PPC with 270ms re-fire delays can, with very careful timing, be fired
at close to their maximum re-fire capacity.
Returns FLRET_FIREFREE on success, FLRET_TIMEOUT if the timeout period elapses before the camera is able to turn to face the target, FLRET_INTERRUPTED if the script executing this instruction is interrupted, FLRET_NOCOMMANDS if an invalid turret is specified, or null
if any of the other arguments ( including [RefObj]
) are invalid.
This instruction can and will be temporarily frozen by the engine if it runs out of processing power. As a result, random turret scripts are frozen and stop firing.
* Having a script signed that ignores the “turn turret to target” step will be near to impossible. Regardless of the firing rate.