Skip to main content

PID

The PID class simulates a PID controller. PID is an acronym for proportional, integral, derivative. PIDs are input feedback loops that try to reach a specific goal by measuring the difference between the input and the desired value, and then returning a new desired input.

A common example is a car's cruise control, which would give a PID the current speed and the desired speed, and the PID controller would return the desired throttle input to reach the desired speed.

Functions​

new​

</>
PID.new(
min: number,--

Minimum value the PID can output

max: number,--

Maximum value the PID can output

kp: number,--

Proportional gain coefficient (P)

ki: number,--

Integral gain coefficient (I)

kd: number--

Derivative gain coefficient (D)

) → PID

Constructs a new PID.

local pid = PID.new(0, 1, 0.1, 0, 0)

Reset​

</>
PID:Reset() → ()

Resets the PID to a zero start state.

Calculate​

</>
PID:Calculate(
setpoint: number,--

The desired point to reach

processVariable: number,--

The measured value of the system to compare against the setpoint

deltaTime: number--

Delta time. This is the time between each PID calculation

) → output: number

Calculates the new output based on the setpoint and input. For example, if the PID was being used for a car's throttle control where the throttle can be in the range of [0, 1], then the PID calculation might look like the following: 

local cruisePID = PID.new(0, 1, ...)
local desiredSpeed = 50

RunService.Heartbeat:Connect(function(dt)
	local throttle = cruisePID:Calculate(desiredSpeed, car.CurrentSpeed, dt)
	car:SetThrottle(throttle)
end)

Debug​

</>
PID:Debug(
name: string,--

Folder name

parent: Instance?--

Folder parent

) → ()

Creates a folder that contains attributes that can be used to tune the PID during runtime within the explorer.

Studio Only

This will only create the folder in Studio. In a real game server, this function will do nothing.

Destroy​

</>
PID:Destroy() → ()

Destroys the PID. This is only necessary if calling PID:Debug.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new PID.\n\n```lua\nlocal pid = PID.new(0, 1, 0.1, 0, 0)\n```",
            "params": [
                {
                    "name": "min",
                    "desc": "Minimum value the PID can output",
                    "lua_type": "number"
                },
                {
                    "name": "max",
                    "desc": "Maximum value the PID can output",
                    "lua_type": "number"
                },
                {
                    "name": "kp",
                    "desc": "Proportional gain coefficient (P)",
                    "lua_type": "number"
                },
                {
                    "name": "ki",
                    "desc": "Integral gain coefficient (I)",
                    "lua_type": "number"
                },
                {
                    "name": "kd",
                    "desc": "Derivative gain coefficient (D)",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PID"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 38,
                "path": "modules/pid/init.luau"
            }
        },
        {
            "name": "Reset",
            "desc": "Resets the PID to a zero start state.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 53,
                "path": "modules/pid/init.luau"
            }
        },
        {
            "name": "Calculate",
            "desc": "Calculates the new output based on the setpoint and input. For example,\nif the PID was being used for a car's throttle control where the throttle\ncan be in the range of [0, 1], then the PID calculation might look like\nthe following:\n```lua\nlocal cruisePID = PID.new(0, 1, ...)\nlocal desiredSpeed = 50\n\nRunService.Heartbeat:Connect(function(dt)\n\tlocal throttle = cruisePID:Calculate(desiredSpeed, car.CurrentSpeed, dt)\n\tcar:SetThrottle(throttle)\nend)\n```",
            "params": [
                {
                    "name": "setpoint",
                    "desc": "The desired point to reach",
                    "lua_type": "number"
                },
                {
                    "name": "processVariable",
                    "desc": "The measured value of the system to compare against the setpoint",
                    "lua_type": "number"
                },
                {
                    "name": "deltaTime",
                    "desc": "Delta time. This is the time between each PID calculation",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "output: number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 78,
                "path": "modules/pid/init.luau"
            }
        },
        {
            "name": "Debug",
            "desc": "Creates a folder that contains attributes that can be used to\ntune the PID during runtime within the explorer.\n\n:::info Studio Only\nThis will only create the folder in Studio. In a real game server,\nthis function will do nothing.\n:::",
            "params": [
                {
                    "name": "name",
                    "desc": "Folder name",
                    "lua_type": "string"
                },
                {
                    "name": "parent",
                    "desc": "Folder parent",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 117,
                "path": "modules/pid/init.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the PID. This is only necessary if calling `PID:Debug`.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 186,
                "path": "modules/pid/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PID",
    "desc": "The PID class simulates a [PID controller](https://en.wikipedia.org/wiki/PID_controller). PID is an acronym\nfor _proportional, integral, derivative_. PIDs are input feedback loops that try to reach a specific\ngoal by measuring the difference between the input and the desired value, and then returning a new\ndesired input.\n\nA common example is a car's cruise control, which would give a PID the current speed\nand the desired speed, and the PID controller would return the desired throttle input to reach the\ndesired speed.",
    "source": {
        "line": 21,
        "path": "modules/pid/init.luau"
    }
}