Welcome to my guide on working with PIDs.

Who are you?

I'm just an average FtD player with a few years of experience under my belt. I find that I spend a lot of time on the FtD Discord server ( https://discord.gg/fromthedepths ) helping people with PIDs, so it's time to just settle down and make an easy-to-use guide for PID beginners.

What is the purpose of this guide?

I want to teach you to visualize how a PID works without needing to know any math, complicated terminology, or reading walls of text.

What is a PID controller?

PID stands for Proportional Integral Derivative. Don't worry about what any of that means, because the only important thing to understand is the underlying concept of what it does, which you should by the end of this guide.

Why use PID?

A PID will help you accomplish smooth movement with your craft, whether it's a large battleship, small flyer, hovercraft, spaceship, or anything in between and will help your craft compensate when taking damage. It also gives you visual feedback on what is happening to your craft, which will help you diagnose movement issues.

Why not use an Automated Control Block (ACB)?

ACBs certainly have their purposes and are quite handy. But, when it comes to controlling your craft's movement, they are a very coarse tool and will not generally be able to provide the kind of smooth operation that a PID will.

Why not use a breadboard?

Woah there, fella. This is a beginner's guide to PIDs. Though a breadboard is the ultimate in space-efficient and robust control of a vehicle, if you don't have a basic understanding of how to set up a PID, then the breadboard will be even more difficult to understand, since there is no visual feedback.

There are actually two different PID controllers in the game (not including the breadboard):



This PID is interested in doing one thing: exactly what you told it to do. It will not listen to the AI or your manual inputs. This PID can be placed anywhere inside the craft.

When would you want this?

• To create a craft that stays at a specific altitude under the water, on the water, in the air, or maintain a particular orientation, such as remaining level at all times. This is incredibly useful when making airships and naval vessels.

When would you not want this?

• When your AI needs to change altitude or have complete control over pitch and roll to do its job. Such as a bomber jet that needs to control it's pitch, roll, and change altitude during the bombing run.

This PID is interested in letting the AI tell it the target "set point" and must be connected to the AI mainframe. For example, the AI wants to change altitude from 50m to 100m. The PID will attempt to make the correction that the AI gave it.

When would you want this?

• To allow the AI to decide the best way of getting from point A to point B (for better or worse). Should be considered a requirement for 6-axis movement.

When would you not want this?

• When the AI is too stupid to do the task correctly or the particular AI you've selected doesn't understand how to accomplish the movement you want.

PID controllers need to be tuned to the specific environment in which they operate. That is to say, the physics of the game mode will heavily impact how they behave.

For this guide we will be using the Neter 2019 settings, located in the game options.




Some (simple) definitions of terminology you will see me use:

• Oversaturation: When the PID demands a correction that the control surface, jet engine, propeller, etc, cannot accomplish in the time and/or strength that it wants and fails to do what you want.
  
• Oscillation: When the correction/vehicle is rapidly bouncing back and forth and cannot achieve stability/smooth movement.

There will be sections below describing how to fix these problems.


I just want to mention that this guide is a WORK IN PROGRESS and I am nowhere near done with it.

Go ahead and place a General purpose PID down in game. While hovering over the PID, press the Q key to open the interface, which will look like this:

*add AI PID picture*



The input tells the PID what it supposed to be paying attention to.

• No Input - Makes the PID idle, since there's nothing to see.
  
• Altitude Above Mean Sea Level - The PID will only look at the distance away from the average sea level compared to your craft. This will level out choppy waves to one single value, essentially, a completely flat sea level. Useful for high altitude craft, like airships, jets, spaceships, etc that are far enough in the air that running into mountains or waves is impossible.
  
• Altitude Above Terrain - The PID will watch how far above the terrain it is. It will ignore water completely and you may find yourself near the ocean floor. Mainly used for submarines.
  
• Altitude Above Terrain or Waves - The PID will pay attention to the closest surface below the craft, whether it's water or terrain. Useful for low-altitude airships, planes, and hovercraft.
  
• Altitude Above Waves - How far above/below the current wave the craft is. Useful for small and medium boats that need to stay on top of a rough sea. Very large ships are rarely bothered by such things.
  
• Roll - The PID pays attention to how far left and right the craft is tilting.
  
• Pitch - The PID pays attention to how far up and down the front and rear of the craft is tilted.
  
• Yaw - The PID pays attention to what direction the vehicle is pointing, usually looking for a waypoint.

The output tells the PID what it is allowed to control if it needs to take action. This should usually match what the PID is listening to in the Input.

• None - Tell the PID it's not allowed to control anything.
  
• Propulsion Roll - Lets the PID use propulsion on the left and right sides of the craft to control rolling.
  
• Propulsion Pitch - Lets the PID use propulsion on the front and back of the craft to control the pitch.
  
• Propulsion Vertical (Altitude) - The PID will use propulsion systems that are responsible for moving the craft up and down.
  
• Airpump Fraction Control - Tells the PID to use airpumps, specifically, to control the altitude or orientation of the craft. This one is typically used to keep a boat floating at a certain height above the sea line.
  
• Hydrofoil Angle Control - Lets the PID use hydrofoils on the craft to control the altitude or pitch of the craft. This is usually used on faster boats or subs to maintain a certain pitch.
  
• A,B,C,etc - These are complex controller settings and are generally not needed for most applications.

Note: There is no Yaw output in a GP PID which must be controlled through an AI PID.

Turn the PID on or off without changing other settings. Default uses a general PID setting which will fail you more often than not.

Enables or disables a set point. In a GP PID this overrides the default value of 0. In an AI PID, this overrides whatever the AI is trying to tell it to do.

For example, you are building an airship, have the PID set to control Propulsion vertical, and would like it to maintain an altitude of 100m. Enable the fake set point and change the value to "100." This value can also be negative to control things like keeping submarines a set distance under the water line.

Applies an adjustment to the current set point. Typically used to modify the way an AI PID wants to position itself relative to a target. This is a bit beyond the scope of this guide, so leave this at default settings.

Gain - The intensity of the correction. Typical values are between 0.1 and 0.01.

Imagine you are driving your car and approaching a curve in the roadway. A high gain is like making the turn by jerking the wheel very hard and a low gain is like turning the wheel a little bit at a time, but both will ease up as you nearly finish your turn. High gain runs the risk of wild oscillations, low gain risks never making the correction "in time."

Why would you want a high gain?

• You will want to do this when a correction must be very responsive. For example, a hovercraft on the ocean that is just barely skimming the water's surface cannot waste time climbing a big wave. If it does not get above the wave quickly it will go under the water and sink, so this must be a stiff correction.
  
• Some systems will need stiff responses, such as air and helium pumps, because it takes time for them to fill or drain a volume of space. Adding a slow gain to an already slow-responding system makes it very hard for it to ever make the needed correction.

Why would you want a low gain?

• Stability. You will find that the lowest gain you can get away with is usually the most stable for your craft, particularly when it starts taking damage.
  
• High powered control systems, like jets, do not need to instantly use full throttle to make small adjustments.

Integral - How much time the PID has to do its job before going to more drastic measures. Typical values can range from a few seconds to half a minute or more, but there are exceptions too. Basically, the longer it's taking to correct the problem, the harder and harder it will work to make it happen.

Back to the car example: You are currently driving around a curve in the road. You turn the wheel to match how the road is turning, but you realize you're not turning quick enough, so you turn harder and harder to avoid flying off the road.

Why would you want to give a craft more time to make a correction?

• Stability. Not giving a craft enough time to make a correction is almost as bad as giving the PID to much gain. If your craft has very strong thrusters a quick response can cause the craft to overshoot the correction and not give the derivative enough chance to stop it (leading to oscillation).
  
• You have a big, lumbering, ship. A huge aircraft carrier cannot turn on a dime, so asking the PID to do it to quickly is not ideal and will lead to unnecessary oversteering.
  
• The correction isn't a priority and you want other corrections to come first on the control surface. For example, you have a huge airship that is taking damage and multiple jet engines are simultaneously controlling altitude, pitch, roll, etc. Does it matter if the altitude drops from 300 to 250 before recovering or is it more important to correct the roll so that it doesn't tip over and fall out of the sky?

Why would you want to have less time for the correction?

• You have a fast and agile fighter or low-flying thrustercraft that must maintain altitude or it will crash into the ground. Or the hovercraft example I gave above, which would crash into a large wave if it had a sluggish response.

Derivative - How far in the future you want the AI to look to see if the correction is still needed. Typical values are in the neighborhood of 1 second.

Why would you want a short derivative?

• Your craft is making powerful changes in orientation, altitude, etc. Your PID only needs to look tenths of a second in the future, because a lot of change is happening in a very short amount of time. Longer derivatives will cause instability and oscillation.

Why would you want a long derivative?

• Your craft is slow and corrections come over longer periods of time. Imagine running with very heavy weights in a backpack on your back. It will take you time to work your way up to full speed and, once at full speed, you will need some time to come to a complete stop, aka, Inertia. Large airships, as an example, take time to get up in the air and are slow to, well, slow down. Short derivatives are meaningless to this craft and it will tend to bob up and down or rock side to side.

Returning to the car example: Imagine doing a lane change, but instead of stopping when your car is in the center of the next lane, you don't try to turn the wheel straight until your tires go over the white line at the edge of the road. Then you turn the wheel back to keep from going off the road, but don't stop until you reach the double yellow line. Your car will act like a ping-pong ball bouncing between the lane lines. The derivative sees the line coming and starts easing off the steering wheel so you stop at the center of the lane instead of overshooting it.

*videos or pictures w/ examples added later*

Chances are that your craft is unstable because you built it that way. Understanding how your propulsion systems interact with your craft's center of mass is vitally important to making it stable.



Download this Craft

In this example, you can see clearly that all control surfaces (jets, in this case) are perfectly in-line with their corresponding axis. This creates extremely stable flight.

• Red - Controlling the Yaw axis. If this was above/below the center of mass, this would not only yaw, but unintentionally impart roll.
  
• Green - Controlling the Pitch axis. If this was to the left/right of the center of mass, this would not only pitch, but also cause rolling.
  
• Blue - Controlling the Roll Axis. If this was in front/behind the center of mass, this would cause the craft to pitch too.
  
• Pink - Controlling the Y-axis (Vertical). If this was in front/behind the center of mass, this would cause pitching. If this was left/right of the center of mass, it would cause rolling.

Important things to take into consideration:

• All control surfaces act as levers around the center of mass (fulcrum or pivot point). This means that the further away a yaw/pitch/roll control surface is from the center of mass, the more torque it generates. The reverse is true too, so putting yaw/pitch/roll control surface very close to the center of mass is not very effective. This is called the control authority of the system.
  
• Control surfaces very close or directly in-line with the center of mass put force directly in the x-axis (left/right), y-axis (up/down), and z-axis (forwards/backwards).
  
• It is OK to put control surfaces not directly in-line with their axis, but you must put other control surfaces to counteract their misapplied force. For example, if you put small jets in the front right corner of the example above, you should also put some in the back left corner.
  
• If you have control surfaces acting against an important vertical propulsion system (like downward facing jets controlling roll/pitch in an airship), make sure that you give the craft enough vertical force reserve to overcome a strong and sustained correction. You can test this by setting the pitch/roll control surfaces to maximum and ensure it can't push the ship down.
  
• Remember that your propulsion systems will take damage during combat. If the ship is important, make sure to give it plenty of redundancy. Your vertical systems, for example, shouldn't be at 90% to keep your ship in the air before combat even starts. One jet getting destroyed shouldn't plummet you into the ocean.

Alright, now that we know what the PID is trying to do, we must give it something to control.

Place a jet engine in the game, look at it, and press Q to open its settings:



Enable the "Strafe and Hover" and "Adv Settings."

As you move the sliders in this section it is going to be a value between -1 and 1. This is a decimal representation of the percentage of thrust dedicated to responding to a particular input. Thus, a 1 value will be 100% thrust and a .5 value will be 50% thrust dedicated to that input.



In this example, the large jet engine is properly placed under the center of mass and is waiting for a command to go up. It has 100% (1.0) of it's maximum output available to do this task, of which, it is currectly using 94% (0.94).

You may set the jet engine to respond with 100% power from multiple different inputs, but it will never exceed 100% total thrust. If it gets a 100% command to roll and a 100% command to pitch down, then it will result in the engine going to full power, but not accomplishing the task (and would show up as an oversaturation in the associated PID).

Generally, if you have a propulsion system responding to different inputs, try to keep the total value at 1.0. For example, an engine in the front corner of the craft may be assigned .34 to up/down, .33 to roll, .33 to pitch.

Power Scale is simply a multiplier across the entire engine. 1.0 representing 100% power available and 0.50 dividing all the output values in half.

We will start with the problem of oversaturation.

• Insufficient Thrust - The propulsion system simply cannot provide the thrust necessary to do what you ask. Usually occurs when trying to keep a heavy object in the air or heavy boat above water.
  
• Insufficient Power Generation - The propulsion systems are not getting enough energy to operate correctly and thus, cannot provide maximum output. Typically occurs when engine systems run out of fuel or damaged during battle.
  
• Insufficient Time - The integral time is to short and the propulsion system cannot make the correction in time. This can be an issue with the turning radius of the AI, an indication that you need more thrust in a particular direction, or give the integral a more realistic setting.
  
• Insufficient Task Dedication - The propulsion system's thrust is being split among to many different tasks, such as a jet being assigned to control pitch, roll, and hover at the same time and cannot accomplish all of them.

tl;dr:

• Add more jets, propellers, control surfaces, etc to make the correction easier to do.
  
• Give the integral more time to do the task, if possible.

* add video examples *

* clear video examples to be added *

Quick tips, for now:

• Turn down the gain and/or reduce power from the thruster(s) the PID is controlling.
  
• Give the Integral more time, if possible.
  
• For nimble craft, lower the derivative.
  
• For sluggish craft, increase the derivative.

Here are some videos that helped me understand PID systems when I first started working with them:

Part 1:
https://youtu.be/wkfEZmsQqiA
Part 2:
https://youtu.be/NVLXCwc8HzM
Part 3:
https://youtu.be/7dUVdrs1e18
Part 4:
https://youtu.be/sFOEsA0Irjs
There's plenty more in that series, but most of it is far to technical for what we want.

And here's the wiki, in case you really want to get deep in the weeds: https://en.wikipedia.org/wiki/PID_controller

Please keep in mind that I whipped this guide together in short notice and I'm sure there's other and better ways to describe, define, visualize, etc, what is in here. I will continue to make improvements, don't worry.

If you're an expert on the topic of PIDs and there's something which I missed or I have a major error, then please don't post it here, because I won't frequently check the comments. The best way to get in touch with me is a direct message in Discord (Midnight Dreary#9425) or @ me on the official FtD server (link at the top of the guide).