This is an in-game script for the programmable block that coordinates your ship's turrets to aim at targets or at any point in space.

It lets you control multiple turrets at once or it can automatically control turrets to shoot at targets. This script works with both turret blocks and custom-built rotor-based turrets. It also works with gravity-based weapons like custom missile launchers.

This script is best used with the BlueG Radar mod, although it works without it (with some limitations) if you want to stay vanilla.

You can also instead use this modified version of the BlueG Radar mod, which ignores ship debris (grids without reactors/batteries/spaceballs) to reduce detection clutter.

You'll need the following things (make sure that you own all the blocks):

• 1 programmable block with the script loaded
  
• 1 timer block set to run the programmable block and to trigger itself (not start itself).
  
• a text or LCD panel called “Text panel GFCS”
  
• any number of turret blocks or rotor turrets (any combination)
  
• any number of “director turrets” (see the section on director turrets)

And the BlueG Radar components (not strictly necessary for all script features, but highly recommended):

• 1 antenna
  
• 1 beacon with [radar] in its name
  
• up to 20 sensors. The first sensor should have [radarg] in its name, the second sensor should have [radarg1], the third [radarg2] and so on up to [radarg19] for the 20th sensor. Each sensor will detect one extra target.

You may also place any number of Super Sensors in addition to or instead of BlueG Radar sensors. Simply call each sensor "Super Sensor". Note however that the sensors will detect the pivot point of a ship rather than the center of mass.

To run the script, trigger the timer block. To stop the script, turn off the PB or the timer block.


The script can work without the BlueG Radar mod, but its functionality will be limited:

1. turrets will NOT be able to autonomously find and aim at targets, or converge at the right distance.
   
2. turrets will NOT be able to calculate the lead necessary to hit moving targets (although there's a workaround; see below)

As for #1, you'll have to manually aim the turrets by controlling the director, and you'll have to supply the script with the correct distance to the target (convergence). To do so, place a text panel called “Text panel convergence” anywhere on the ship and type the distance in meters into the public text. You can edit this as the script is running (you'll get this information from the HUD, presumably).

You can use my own Easy Convergence Editor script to easily edit the number with the press of a button.

As for #2, the script can actually track the movement of the director to calculate the target's speed. Note that this will only be accurate if the convergence provided is correct. If you want to use this feature, you can enable it at the top of the script. Look for this line:


and change false to true. Keep in mind that you'll really want to temporarily disable lead calculation if there are no target that the turrets should lead (you can do so by using the Auto Lead toggle. See the “extra features” section).

If you use this feature, I highly recommend using a rotor director instead of a turret block director as it has better accuracy.

The director turret is a turret used to aim all other turrets. The script mirrors the movement of all other turrets to match the movement of the director. You may have multiple directors, although only one can be used at the same time. By default, controlling a director will shift control of the turrets to that director. Also by default (if you're using the BlueG Radar), the turrets will aim at the center of mass of the target you're pointing at; to target a specific area of a ship, disable Auto Aim (see the additional features section).

A director turret can be a custom rotor turret or a single turret block (such as the vanilla Gatling Turret).



A rotor-based director must have a remote control block (to tell the script the orientation of the director) called “Director Remote Control”.

Additionally, you may place these blocks:

- a horizontal rotor called “Director RotorX”
- a vertical rotor called “Director RotorY”

If these blocks are found on the director, the rotors will be locked in place (turned on) while the remote is not controlled and unlocked (turned off) while it's not controlled. You'll also probably want a camera to point the director where you want.

If you want to have multiple directors, add the number after “Director”. For example, the second director would have these blocks: “Director2 Remote Control”, “Director2 RotorX”, and “Director2 RotorY”.



Turret block directors should simply be named “Director”. If you want to have multiple directors, name them “Director2”, “Director3”, and so on.

Known issue: turret block directors may have accuracy issues at high elevations (pointed high up).

If you wish not to use any director, go to the top of the script, look for this line, and replace false with true:

Each turret is identified by a letter and a number (like A1, D4 or G7). This is to make it easy to choose and edit settings for multiple turrets (as described in the next section). Like directors, turrets can also be rotor-based or consisting of a single turret block.
Turrets with the same design should have the same letter (but different numbers).



Rotor-based turret “A1” should have the following blocks:

• “Turret A1 Remote Control” (exactly 1 remote control block)
  
• “Turret A1 RotorX” (up to 1 horizontal rotor)
  
• “Turret A1 RotorY” (any number of vertical rotors)
  
• “Turret A1 Gun” (any number of gun blocks)

For turrets with different identifiers (like A2 or B1), change the names accordingly (like “Turret B1 Remote Control”).

Like on the director, the remote control should be placed according to the orientation of the turret. You may have no RotorX or RotorY blocks, if you just want the script to turn the turret on one axis, as well as no guns (so you can use this script for gunless turrets, like spotlights). You may use Digi's Conveyor Hinges instead of any rotor.

By default, the script will turn each vertical rotor (RotorY) clockwise if the turret's aim is too low, and counter-clockwise otherwise. If you want to invert this behavior, simply add “Reverse” to the name of the rotor. For example “Turret A1 RotorY Reverse”.

Additionally you may use these blocks (again, replace the identifier as necessary):

• any number of sensors called “Turret A1 Sensor”
  
• any number of pistons called “Turret A1 PistonX”
  
• any number of pistons called “Turret A1 PistonY”

If at least one sensor detects something, the script will turn the turret's guns off. This will prevent the turret from firing into your own ship. Adjust the sensors' detection settings as necessary, but you don't have to set them to trigger anything (the script will do it).

Pistons can be used as an optional replacement for rotors. Adding “Reverse” still works to invert the direction of movement.



For single turrets, simply name them “Turret ”+identifier. For example, “Turret A” or “Turret D”. Single turrets don't need to have a number, although you can still add it if you want.

Known issue: single block turret can shoot into your own ship. Unfortunately this is something I can't fix unless Keen updates the API (currently scripts can't check if there's something in front of a turret).

This text panel is used to tell the script which turrets to control and which settings to use for each of them. By default, its name should be "Text panel GFCS". You can use an LCD panel instead of a text panel.

Multiple turrets with the same letter (A1, A2, A3) form a turret group. You can pick settings for one turret group by typing into the text panel a line with these values (separating each value with a comma):

<turret group letter>, <projectile velocity>, <range>, <horizontal rotor speed>, <vertical rotor speed>

For example

A, 300, 800, 4, 4

This line tells the script to look for all “A” turrets, turn them with rotor speeds of 4, calculate the lead accounting for a projectile velocity of 300m/s, and turn off the guns if the target is out of gun range (800 meters).

To set up multiple turret groups, type the settings for each group in a new line.

If the turrets in the group have a projectile that accelerates (like any custom gravity weapon), then replace the projectile with these values, separated to forward slashes: <initial velocity>/<final velocity>/<acceleration>

Here's an example for a weapon whose projectiles accelerate from 0 m/s to 104 m/s (the maximum without speed mods) at a rate of 30 m/s^2:

B, 0/104/30, 2000, 2, 2

See the FAQ/Troubleshooting section if you want to find out the projectile speed or range of a weapon.

At the top of the script you can customize many settings by editing some values. Here's what each setting does.



vanilla_tracking
This is exclusively if you're using this script without the BlueG Radar and you also want turrets to lead targets. Set it to true to have the script track the director's movement to calculate the target's speed. For this to be accurate, the distance to the target (convergence) must also be accurately set.

only_shoot_in_range
This is only used for Auto Fire mode. If true, it will prevent the guns from firing if the target is out of the turret's range.

defaultconvergence
This is the distance that the turrets will aim at (in front of the director) if no target is found. You can adjust this in real time by placing a text or LCD panel called "Text panel convergence" and typing the number in its public text.

no_director
Set this to false if you want to use the script without a director (the script won't complain that there's no director and instead will default to Auto Target).

switch_to_controlled
This is only used if you have more than one director. If true, the script will automatically switch to a director if it sees that it's being controlled. If no director is controlled, the script will default to the first director found.

idle_if_no_targets
This is only used while Auto Target is on. If set to true, all rotor turrets will idle if no target is detected (all rotors will return to zero degrees or between the minimum and maximum angle if set). If false, they will stop wherever they are.


These are the default values for the toggle timers (see the next section) in case a timer is not found. If you want some of these settings always on or off, set them here and don't place any timer blocks. "True" means "on" and "false" means "off".



These are the names that the blocks should have. You may edit them as you wish.


These are the advanced settings with their default values:


write_override_info is for remote fire direction (see the relative section of this guide). When set to false, the script will read and use the coordinates from the override text panel; when set to true, the script will write the coordinates instead.

turret_threshold indicates the minimum angle for a target to be considered in front of a turret. By default, the script will turn off a turrets' guns if they are not on target. This has the side effect of interrupting the gun's firing sound effect. To prevent it, set this to 180 or more.

director_threshold is the same thing, but for the director. It's the minimum angle for a target to be considered in front of the director.

frequency is how many times per second (up to 60) the script will adjust the turrets' aim.

lists_size is how many instances of the target's speed and acceleration are recorded and averaged. The script detects speed and acceleration 60 times per second, so 10 = 1/6th of a second.

lists_size_vanilla is the same as lists_size, but it overrides it if vanilla tracking is active. Manual tracking requires a lot more smoothing (120 = last 2 seconds) to produce usable tracking data.

lock_director: when set to true, the script will lock the rotors of each rotor director that's not being controlled.

moving_ship: the script will track the ship's own speed in order to calculate lead (since that speed will carry over to any projectile that leaves the ship). If you're using this script on a stationary platform, feel free to disable this (but you can also leave it on).

To toggle some script settings in real time (without constantly opening the PB editor), you can place timer blocks that will act as toggles for those settings if you turn them on or off. They don't have to trigger anything. Name the timers like this:

• "Timer Block Auto Lead": turn it on/off to toggle target lead calculation.
  
• "Timer Block Auto Target": when it's on, turrets will automatically aim at the closest target. The director is ignored.
  
• "Timer Block Auto Aim": when it's on, turrets will aim at the center of mass of the target you're aiming at (useful for small and fast moving target). This is aim assist for the director.
  
• "Timer Block Auto Fire": when it's on, turrets will fire automatically if there's a target.
  
• "Timer Block Fire All": like Auto Fire, except the turrets will fire even if there's no target.
  
• "Timer Block Idle": when it's on, all rotor turrets will ignore the director and all targets, and rotors will be turned to zero degrees.

If a block isn't found, the script will use the default mode for each setting:
Auto Lead: on
Auto Target: off
Auto Aim: on
Auto Fire: off
Fire All: off
Idle: off


The script will read from all text panels whose names contain "Text panel GFCS" (the default name). If you place multiple panels that match that name, the script will read from all of them.

Additionally, the script will ignore text panels that are off. This lets you switch turret groups on and off on the fly if you set up separate panels. This also lets you switch control of turret groups between multiple programmable blocks on the same ship that run separate copies of this script.


You can place text panels with the following names. They will display useful information:

• "Text panel warnings" - will tell you if a turret is missing some blocks
  
• "Text panel status" - lots of information on the script's status (turrets found, directors found, timer toggle settings, and lots more)
  
• "Text panel position" - the target's position (GPS coordinates)
  
• "Text panel speed" - the target's speed (along each axis and overall)
  
• "Text panel acceleration" - the target's acceleration (along each axis and overall)
  
• "Text panel your speed" - the current speed of your own ship

Currently only one director can be used at the same time to control all the turrets. If you want to be able to control multiple turret groups with multiple directors, place a secondary GFCS system (with its own programmable block, timer block and GFCS text panel). For this you'll have to edit the name of the text panel and of the secondary director series in the script settings.

You can then control which director controls which turrets by editing the turret groups on the GFCS text panels or by turning text panels on or off.

You can set the target of your ship's turrets even when you're far away from the ship. There are two ways:


On your ship you can place a text panel called "Text panel override" with the target's coordinates. This information will be used by the script instead of what the director and sensors detect. This way, by accessing the text panel from a separate ship (via an antenna) you can set a ship's target from far away. This is useful if you have the coordinates of a stationary target (like a planetary installation) and you want to hit it without relying on the main ship's director and/or sensors.

The text panel's public text should be formatted like this (three lines):


For example:



This method does the same thing, except it lets you send the coordinates directly to the main ship (without going through the antenna and terminal) and in real time.

This is possible thanks to a bug with merge blocks and rotors that lets the programmable block access blocks on separate grids after they've been unmerged (via a merge block) or detached (via a rotor block). This way, the programmable block on your main ship can read information from a text panel located directly on the spotting ship. You won't have to place the text panel on the main ship and access it via an antenna. Here's how to set it up:

1. Make sure that your spotting ship is attached via a merge block or rotor to your main ship. Make sure your spotting ship has a text panel called "Text panel override" and that it's turned on.
   
2. Run the script by triggering the timer block. If the script was already running, open the PB's code editor and hit "Remember and exit".
   
3. Unmerge/detach the spotting ship, fly it wherever, and type the target's coordinates into the text panel's public text.
   
4. The script on the main ship should read the coordinates from that text panel and aim the turrets accordingly. To fire the guns, turn off a timer block called “Timer Block Fire All” (place it on the ship before unmerging and before starting the main ship's script)

Notes and tips:

• (Very important!) The PB won't be able to remotely access blocks anymore if you cut/paste the spotting ship, if you save and reload, or if you reset the programmable block ("Remember and exit") after the ship has been unmerged/detached.
  
  
• Instead of a text panel you can simply place the BlueG sensors onto the spotting ship. The main ship's script will read from them. Remember that you'll also need to place a beacon with [radar] in the name.
  
  
• You can also place all of the GFCS components onto the spotting ship and set "write_override_info" to true in the script's advanced settings, and the script on the spotting ship will write the information onto the "Text panel override" instead of reading from it. (If the spotting ship has no turrets, simply leave the GFCS text panel blank. Also it's best to run the spotting ship's script after the ship has been unmerged)
  
  
• You only need to send the coordinates to the ship. The main ship's own script will calculate the speed and acceleration by itself if the override coordinates change over time.

A: Make sure all blocks are set to the same ownership.

A: To properly aim the director, it's necessary to look through a camera mounted in front of it. If your camera is shifted from the director, the aim will be shifted as well (even though the crosshair looks on target).

A: The script turns off the guns if they're off target or out of range. Unfortunately, this has the side effect of interrupting the guns' sound effects. At the top of the script there are settings to prevent the guns from turning off (turret_threshold and only_shoot_in_range)

A: Option 1: check the weapon mod page.
Option 2: use trial and error.
Option 3: Go to the mod page, copy the id number of the mod that's in the URL (something like 12345678), go to C:\Users\<username>\AppData\Roaming\SpaceEngineers\Mods, look for the sbm file with that number, open it in 7zip/WinZip/WinRar, open the Data folder, and look for Ammos.sbc. Open it using any text editor like Notepad and look for the line with <DesiredSpeed>. That's the projectile velocity. By the way, <MaxTrajectory> is the range.
Vanilla gatling weapons have a velocity of 300 m/s and a range of 800 m.

A: Yes. You can place turrets (both AI turrets and rotor turrets) in any location and at any angle. Just make sure that the orientation of the remote control block matches the turret's own orientation. You may want to add "Reverse" to the name of a RotorX or RotorY if you see it's turning the wrong way.

A: It's hard to calculate where a modded turret is pointing, since the pivot point may not match the turret block's center location. You can manually fix this issue by adding <N> to the director's name, where N is around -1 to +1 meters or so (above or below the block's center), depending on the turret model. Try different values, like <-1.5> or <0.5>.