RunService

Show Deprecated
Not Creatable
Service
Not Replicated

RunService contains methods and events for time-management as well as for managing the context in which a game or script is running. Methods like IsClient, IsServer, IsStudio, can help you determine under what context code is running. These methods are useful for ModuleScripts that may be required by both client and server scripts. Furthermore, IsStudio can be used to add special behaviors for in-studio testing.

RunService also houses events that allow your code to adhere to Roblox's frame-by-frame loop, such as Stepped, Heartbeat and RenderStepped. Selecting the proper event to use for any case is important, so you should read Task Scheduler to make an informed decision.

Code Samples

RunService Stepped

1local RunService = game:GetService("RunService")
2
3local PART_START_POS = Vector3.new(0, 10, 0)
4local PART_SPEED = Vector3.new(10, 0, 0)
5
6-- Create a Part with a BodyPosition
7local part = Instance.new("Part")
8part.CFrame = CFrame.new(PART_START_POS)
9
10local bp = Instance.new("BodyPosition")
11bp.Parent = part
12bp.Position = PART_START_POS
13part.Parent = workspace
14
15local function onStep(_currentTime, deltaTime)
16 -- Move the part the distance it is meant to move
17 -- in the last `deltaTime` seconds
18 bp.Position = bp.Position + PART_SPEED * deltaTime
19
20 -- Here's the math behind this:
21 -- speed = displacement / time
22 -- displacement = speed * time
23end
24
25RunService.Stepped:Connect(onStep)

Summary

Properties

READ ONLY
NOT REPLICATED

Events


Fires every frame after the physics simulation has completed.


Fires every frame prior to the frame being rendered.

Stepped(time: number, deltaTime: number): RBXScriptSignal  

Fires every frame prior to the physics simulation.

Methods

BindToRenderStep(name: string, priority: number, function: function): nil  

Given a string name of a function and a priority, this method binds the function to RunService.RenderStepped.


Returns whether the current environment is running on the client.


Returns whether the current environment is in Edit mode.


Returns whether the 'Run' button has been pressed to run the simulation in Roblox Studio.


Returns whether the game is currently running.


Returns whether the current environment is running on the server.


Returns whether the current environment is running in Roblox Studio.

Pause(): nil  

Pauses the game's simulation if it is running, suspending physics and scripts.

Run(): nil  

Runs the game's simulation, running physics and scripts.

Stop(): nil  

Ends the game's simulation if it is running.


Unbinds a function that was bound to the render loop using RunService:BindToRenderStep().

Properties

ClientGitHash

Read Only
Not Replicated

Events

Heartbeat

The Heartbeat event fires every frame, after the physics simulation has completed. The step argument indicates the time that has elapsed since the previous frame.

As Heartbeat fires every frame, it runs on a variable frequency. This means the rate will vary depending on the performance of the machine. If the game is running at 40 FPS, then Heartbeat will fire 40 times per second and the step argument will be roughly 1/40th of a second.

The step argument can be used to account for the variable frequency of this event, for example:


1local RunService = game:GetService("RunService")
2
3local RATE_PER_SECOND = 2
4
5RunService.Heartbeat:Connect(function(step)
6 local increment = RATE_PER_SECOND * step
7end)
8

There is no guarantee that functions connected to this event will fire at the exact same time, or in any specific order. For an alternative where the priority can be specified, see RunService:BindToRenderStep().

Parameters

deltaTime: number

The time (in seconds) that has elapsed since the previous frame.


Code Samples

Printing Heartbeat Frequency

1local RunService = game:GetService("RunService")
2
3local LOOP_COUNT = 5
4local count = 0
5
6local connection
7
8function onHeartbeat(step)
9 if count < LOOP_COUNT then
10 count = count + 1
11 print("Time between each loop: " .. step)
12 else
13 connection:Disconnect()
14 end
15end
16
17connection = RunService.Heartbeat:Connect(onHeartbeat)

PostSimulation

Parameters

deltaTime: number

PreAnimation

Parameters

deltaTime: number

PreRender

Parameters

deltaTime: number

PreSimulation

Parameters

deltaTime: number

RenderStepped

The RenderStepped event fires every frame, prior to the frame being rendered. The step argument indicates the time that has elapsed since the previous frame.

RenderStepped does not run in parallel to Roblox's rendering tasks and code connected to RenderStepped must be executed prior to the frame being rendered. This can lead to significant performance issues if RenderStepped is used inappropriately. To avoid this, only use RenderStepped for code that works with the camera or character. Otherwise, RunService.Heartbeat should be used.

As RenderStepped fires every frame, it runs on a variable frequency. This means the rate will vary depending on the performance of the machine. If the game is running at 40 FPS, then RenderStepped will fire 40 times per second and the step argument will be roughly 1/40th of a second.

The step argument can be used to account for the variable frequency of this event, for example:


1local RunService = game:GetService("RunService")
2
3local RATE_PER_SECOND = 2
4
5RunService.RenderStepped:Connect(function(step)
6 local increment = RATE_PER_SECOND * step
7end)
8

There is no guarantee that functions connected to this event will fire at the exact same time, or in any specific order. For an alternative where the priority can be specified, see RunService:BindToRenderStep().

As RenderStepped is client-side only, it can be used in a LocalScript or a ModuleScript required by a LocalScript.

Parameters

deltaTime: number

The time (in seconds) that has elapsed since the previous frame.


Code Samples

Spin GuiObject

1local RunService = game:GetService("RunService")
2
3local guiObject = script.Parent
4
5local degreesPerSecond = 180
6
7local function onRenderStep(deltaTime)
8 local deltaRotation = deltaTime * degreesPerSecond
9 guiObject.Rotation = guiObject.Rotation + deltaRotation
10end
11
12RunService.RenderStepped:Connect(onRenderStep)

Stepped

The Stepped event fires every frame prior to the physics simulation. The step argument indicates the time that has elapsed since the previous frame.

As Stepped fires every frame, it runs on a variable frequency. This means the rate will vary depending on the performance of the machine. If the game is running at 40 FPS, then Stepped will fire 40 times per second and the step argument will be roughly 1/40th of a second.

The step argument can be used to account for the variable frequency of this event, for example:


1local RunService = game:GetService("RunService")
2
3local RATE_PER_SECOND = 2
4
5RunService.Stepped:Connect(function(time, step)
6 local increment = RATE_PER_SECOND * step
7end)
8

There is no guarantee that functions connected to this event will fire at the exact same time, or in any specific order. For an alternative where the priority can be specified, see RunService:BindToRenderStep().

Parameters

time: number

The duration (in seconds) that RunService has been running for.

deltaTime: number

The time (in seconds) that has elapsed since the previous frame.


Code Samples

Using the Stepped Event

1local RunService = game:GetService("RunService")
2
3local function onStepped()
4 print("Stepped")
5end
6
7RunService.Stepped:Connect(onStepped)

Methods

BindToRenderStep

The BindToRenderStep function binds a custom function to be called at a specific time during the render step. There are three main arguments for BindToRenderStep: name, priority, and what function to call.

As it is linked to the client's rendering process, BindToRenderStep can only be called on the client.

Name

The name parameter is a label for the binding, and can be used with RunService:UnbindFromRenderStep() if the binding is no longer needed.


1local RunService = game:GetService("RunService")
2
3local function functionToBind() end
4
5-- Bind the function above to the binding named "tempBinding"
6RunService:BindToRenderStep("tempBinding", 1, functionToBind)
7-- Unbind the function bound to "tempBinding"
8RunService:UnbindFromRenderStep("tempBinding")
9

Priority

The priority of the binding is an integer, and determines when during the render step to call the custom function. The lower this number, the sooner the custom function will be called. If two bindings have the same priority the Roblox engine will randomly pick one to run first. The default Roblox control scripts run with these specific priorities:

  • Player Input: 100
  • Camera Controls: 200 For convenience, the RenderPriority enum can be used to determine the integer value to set a binding. For example, to make a binding right before the default camera update, simply subtract 1 from the camera priority level.

When using Enum.RenderPriority, remember to use InlineCode.Value at the end of the desired enum. BindToRenderStep will not work if just the enum on its own is used.


1local RunService = game:GetService("RunService")
2
3local function beforeCamera(delta)
4 -- Code in here will run before the default Roblox camera script
5end
6
7RunService:BindToRenderStep("Before camera", Enum.RenderPriority.Camera.Value - 1, beforeCamera)
8

Custom Function and Delta Time

The last argument of BindToRenderStep is the custom function to call. This function will be passed one parameter called deltaTime. DeltaTime shows how much time passed between the beginning of the previous render step and the beginning of the current render step.

All rendering updates will wait until the code in the render step finishes. Make sure that any code called by BindToRenderStep runs quickly and efficiently. If code in BindToRenderStep takes too long, then the game visuals will be choppy.

Parameters

name: string

The name parameter is a label for the binding, and can be used with RunService.Unbind if the binding is no longer needed.

priority: number

The priority of the binding is an integer, and determines when during the render step to call the custom function. The lower this number, the sooner the custom function will be called. If two bindings have the same priority the Roblox engine will randomly pick one to run first. The default Roblox control scripts run with these specific priorities:

  • Player Input: 100
  • Camera Controls: 200

For convenience, the RenderPriority enum can be used to determine the integer value to set a binding. For example, to make a binding right before the default camera update, simply subtract 1 from the camera priority level.

function: function

The custom function being bound.


Returns

None.

Code Samples

Frame Moving in Circle

1local RunService = game:GetService("RunService")
2
3-- How fast the frame ought to move
4local SPEED = 2
5
6local frame = script.Parent
7frame.AnchorPoint = Vector2.new(0.5, 0.5)
8
9-- A simple parametric equation of a circle
10-- centered at (0.5, 0.5) with radius (0.5)
11local function circle(t)
12 return 0.5 + math.cos(t) * 0.5, 0.5 + math.sin(t) * 0.5
13end
14
15-- Keep track of the current time
16local currentTime = 0
17local function onRenderStep(deltaTime)
18 -- Update the current time
19 currentTime = currentTime + deltaTime * SPEED
20 -- ...and the frame's position
21 local x, y = circle(currentTime)
22 frame.Position = UDim2.new(x, 0, y, 0)
23end
24
25-- This is just a visual effect, so use the "Last" priority
26RunService:BindToRenderStep("FrameCircle", Enum.RenderPriority.Last.Value, onRenderStep)
27--RunService.RenderStepped:Connect(onRenderStep) -- Also works, but not recommended
Bind and Unbind a Function

1local RunService = game:GetService("RunService")
2
3-- Step 1: Declare the function and a name
4local name = "Print Hello"
5local function printHello()
6 print("Hello")
7end
8
9-- Step 2: Bind the function
10RunService:BindToRenderStep(name, Enum.RenderPriority.First.Value, printHello)
11
12-- Step 3: Unbind the function
13local success, message = pcall(function()
14 RunService:UnbindFromRenderStep(name)
15end)
16
17if success then
18 print("Success: Function unbound!")
19else
20 print("An error occurred: " .. message)
21end
RunService Custom Function

1local RunService = game:GetService("RunService")
2
3local function checkDelta(deltaTime)
4 print("Time since last render step:", deltaTime)
5end
6
7RunService:BindToRenderStep("Check delta", Enum.RenderPriority.First.Value, checkDelta)

GetCoreScriptVersion

Roblox Script Security

Returns

GetRobloxClientChannel

Roblox Script Security

Returns

GetRobloxVersion

Roblox Script Security

Returns

IsClient

This function returns whether the current environment is running on the client.

If the code that invoked this method is running in a client context (in a LocalScript or a ModuleScript required by a LocalScript) then this method will return true. In all other cases, this function will return false.

If this function returns true, then the current environment can access client-only features like RunService.RenderStepped or Players.LocalPlayer.

RunService test function results

EnvironmentIsStudioIsClientIsServerIsEditIsRunningIsRunMode
Live Playerfalsetruefalse
Live Serverfalsefalsetrue
Edit Modetruetruetruetruefalsefalse
Edit Mode (Team Create)truetruefalsetruefalsefalse
Run Modetruetruetruefalsetruetrue
Play Mode (Client)truetruefalsefalsetruefalse
Play Mode (Server)truefalsetruefalsetruetrue
Team Test Playertruetruefalsefalsetruefalse
Legacy Play Mode †truetruetruefalsetruefalse
† 'Legacy Play Mode' refers to Play Mode with Accurate Play Solo disabled

See also:


Returns

Whether the current environment is running the client.

Code Samples

Run Context

1local RunService = game:GetService("RunService")
2
3if RunService:IsStudio() then
4 print("I am in Roblox Studio")
5else
6 print("I am in an online Roblox Server")
7end
8
9if RunService:IsRunMode() then
10 print("Running in Studio")
11end
12
13if RunService:IsClient() then
14 print("I am a client")
15else
16 print("I am not a client")
17end
18
19if RunService:IsServer() then
20 print("I am a server")
21else
22 print("I am not a server")
23end
24
25if RunService:IsRunning() then
26 print("The game is running")
27else
28 print("The game is stopped or paused")
29end

IsEdit

Plugin Security

This function returns whether the current environment is in 'Edit' mode. For example, Roblox Studio is in 'Edit Mode' when the game is not running.

IsEdit will return the inverse of RunService:IsRunning() with one exception, if the simulation has been 'paused' then both IsEdit and RunService:IsRunning() will return false.

See also:


Returns

Whether the current environment is in Edit mode.

IsRunMode

This function returns whether the 'Run' button has been pressed to run the simulation in Roblox Studio.

If the user has pressed 'Run', then this function will return true. This function will continue to return true if the simulation has been paused using the 'Pause' button. However, once it has been stopped using the 'Stop' button it will revert to returning false.

Roblox Studio only enters run mode when the 'Run' button is pressed, not the 'Play' button. This function will also return false if the simulation was started using RunService:Run() rather than the 'Run' button.

RunService test function results

See also:


Returns

Whether the 'Run' button has been pressed to run the simulation in Roblox Studio.

Code Samples

Run Context

1local RunService = game:GetService("RunService")
2
3if RunService:IsStudio() then
4 print("I am in Roblox Studio")
5else
6 print("I am in an online Roblox Server")
7end
8
9if RunService:IsRunMode() then
10 print("Running in Studio")
11end
12
13if RunService:IsClient() then
14 print("I am a client")
15else
16 print("I am not a client")
17end
18
19if RunService:IsServer() then
20 print("I am a server")
21else
22 print("I am not a server")
23end
24
25if RunService:IsRunning() then
26 print("The game is running")
27else
28 print("The game is stopped or paused")
29end

IsRunning

Returns whether the game is currently running

The game is considered running when it is not in edit mode in Roblox Studio. This means, if the simulation has been run using the 'Run' or 'Play' buttons the game is running.

IsRunning will always return the inverse of RunService:IsEdit() with one exception, if the simulation has been 'paused' then both RunService:IsEdit() and IsRunning will return false.

RunService test function results

See also:


Returns

Whether the game is currently running.

Code Samples

Run Context

1local RunService = game:GetService("RunService")
2
3if RunService:IsStudio() then
4 print("I am in Roblox Studio")
5else
6 print("I am in an online Roblox Server")
7end
8
9if RunService:IsRunMode() then
10 print("Running in Studio")
11end
12
13if RunService:IsClient() then
14 print("I am a client")
15else
16 print("I am not a client")
17end
18
19if RunService:IsServer() then
20 print("I am a server")
21else
22 print("I am not a server")
23end
24
25if RunService:IsRunning() then
26 print("The game is running")
27else
28 print("The game is stopped or paused")
29end

IsServer

This function returns whether the current environment is running on the server.

If the code that invoked this method is running in a server context (in a Script or a ModuleScript required by a Script) then this method will return true. In all other cases, this function will return false.

If this function returns true, then the current environment can access server-only features like ServerStorage or ServerScriptService.

See also:


Returns

Whether the current environment is running on the server.

Code Samples

Run Context

1local RunService = game:GetService("RunService")
2
3if RunService:IsStudio() then
4 print("I am in Roblox Studio")
5else
6 print("I am in an online Roblox Server")
7end
8
9if RunService:IsRunMode() then
10 print("Running in Studio")
11end
12
13if RunService:IsClient() then
14 print("I am a client")
15else
16 print("I am not a client")
17end
18
19if RunService:IsServer() then
20 print("I am a server")
21else
22 print("I am not a server")
23end
24
25if RunService:IsRunning() then
26 print("The game is running")
27else
28 print("The game is stopped or paused")
29end

IsStudio

This function returns whether the current environment is running in Roblox Studio.

This function will only return true when using Roblox Studio and can be used to add code to test your game within Studio.

See also:


Returns

Whether the current environment is running in Roblox Studio.

Code Samples

Run Context

1local RunService = game:GetService("RunService")
2
3if RunService:IsStudio() then
4 print("I am in Roblox Studio")
5else
6 print("I am in an online Roblox Server")
7end
8
9if RunService:IsRunMode() then
10 print("Running in Studio")
11end
12
13if RunService:IsClient() then
14 print("I am a client")
15else
16 print("I am not a client")
17end
18
19if RunService:IsServer() then
20 print("I am a server")
21else
22 print("I am not a server")
23end
24
25if RunService:IsRunning() then
26 print("The game is running")
27else
28 print("The game is stopped or paused")
29end

Pause

Plugin Security

This function pauses the games' simulation if it is running, suspending physics and scripts.

The simulation can be started using RunService:Run() or the 'Run' button in Roblox Studio. When the simulation is paused, RunService:IsRunning() will return false.

Pausing the simulation can be used to assist with debugging in Roblox Studio, it cannot be used in real game sessions.

See also:


Returns

Run

Plugin Security

This function runs the game's simulation, running physics and scripts.

When the simulation is running, RunService:IsRunning() will return true. However, RunService:IsRunMode() will only return true if the simulation was started using the 'Run' button in Roblox Studio. This means when this function is used to start the simulation, IsRunMode will return false even though the simulation is running.

The simulation can be paused using RunService:Pause() or the 'Pause' button in Roblox Studio. It can also be ended using RunService:Stop().

Running the simulation can be used to assist with debugging in Roblox Studio. Currently it is not possible to restore the game to the state it was in prior to running the simulation if the simulation was started using this function. If this is a problem, instead use the 'Run' button in Roblox Studio.

See also:


Returns

No return.

Set3dRenderingEnabled

Roblox Script Security

Parameters

enable: boolean

Returns

SetRobloxGuiFocused

Roblox Script Security

Parameters

focus: boolean

Returns

Stop

Plugin Security

This function ends the game's simulation if it is running.

The simulation can be started using RunService:Run() or the 'Run' button in Roblox Studio. When the simulation is stopped, RunService:IsRunning() will return false and RunService:IsEdit() will return true.

In contrast to the 'Stop' button in Roblox Studio, calling this function will not restore the game to the state it was in prior to the simulation being run. This means any changes made to the game by the physics simulation and scripts will persist after the simulation has ended.

See also:


Returns

UnbindFromRenderStep

Given a name of a function sent to BindToRenderStep, this method will unbind the function from being called during RenderStepped. This is used to unbind bound functions once they are no longer needed, or when they no longer need to fire every step.

If there is no bound function by the given name, this method raises an error. You can prevent such an error from being raised by using pcall. For example, if you bind a function named drawImage using BindToRenderStep, the following code would unbind the function, suppressing errors if there wasn't already a function with the name drawImage bound.


1local RunService = game:GetService("RunService")
2
3local success, message = pcall(function() RunService:UnbindFromRenderStep("drawImage") end)
4if success then
5 print("Success: Function unbound!")
6else
7 print("An error occurred: "..message)
8end
9```"
10

Parameters

name: string

The name of the function being unbound.


Returns

None.

Code Samples

Bind and Unbind a Function

1local RunService = game:GetService("RunService")
2
3-- Step 1: Declare the function and a name
4local name = "Print Hello"
5local function printHello()
6 print("Hello")
7end
8
9-- Step 2: Bind the function
10RunService:BindToRenderStep(name, Enum.RenderPriority.First.Value, printHello)
11
12-- Step 3: Unbind the function
13local success, message = pcall(function()
14 RunService:UnbindFromRenderStep(name)
15end)
16
17if success then
18 print("Success: Function unbound!")
19else
20 print("An error occurred: " .. message)
21end

setThrottleFramerateEnabled

Roblox Script Security

Parameters

enable: boolean

Returns