Roblox UtilitiesDevlHub Roblox Documentation

Class

RunService

NotCreatableServiceNotReplicated
Inherits
Instance › Object
Memory category
Instances

Service responsible for all runtime activity and progression of time.

RunService contains methods and events for time management as well as for managing the context in which an experience or script is running. Methods like IsClient(), IsServer(), and 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 the engine's frame‑by‑frame loop, such as PreRender, PreAnimation, PreSimulation, PostSimulation, and Heartbeat. Selecting the proper event to use for any case is important, so you should read Task Scheduler to make an informed decision.

Context Test Results#
Environment Class.RunService:IsStudio()|IsStudio Class.RunService:IsClient()|IsClient Class.RunService:IsServer()|IsServer Class.RunService:IsEdit()|IsEdit Class.RunService:IsRunning()|IsRunning Class.RunService:IsRunMode()|IsRunMode
Live (Client) false true false true false
Live (Server) false false true true false
Edit true true true true false false
Collaborative Edit true true false true false false
Run Mode true false true true true
Play Mode (Client) true true false true false
Play Mode (Server) true false true true false
Team Test (Client) true true false true false
Team Test (Server) true false true true false
Luau Execution false false true false false

Properties 1#

RunStateRunStateThe current run state of the game's simulation.Read: PluginSecurityWrite: PluginSecurityReadSafeNotReplicated

RunState: RunState#

NotReplicatedRead: PluginSecurityWrite: PluginSecurityReadSafe

An RunState value that reflects whether the game's simulation is stopped, running, or paused. Reading reports the current state; setting it transitions the simulation, equivalent to RunService:Run(), RunService:Pause(), and RunService:Stop() for the corresponding states. Defaults to RunState.Stopped. Setting this property requires Plugin security.

The state reported here backs the context methods on RunService: it is Running when IsRunning() returns true, and Stopped when IsEdit() returns true.

Methods 17#

BindToAnimationBinds a custom function to be called at a fixed frequency before Animators update when fixed simulation is enabled, or immediately before BindToSimulation callbacks otherwise.
BindToRenderStepGiven a string name of a function and a priority, this method binds the function to RunService.PreRender.
BindToSimulationBinds a custom function to be called at a fixed frequency which is independent of the frame rate.
GetPredictionStatusChecks the PredictionStatus of a specific context instance, useful for debugging scripts affecting multiple instances where some might be predicted and others might not.
IsClientReturns whether the current environment is running on the client.Safe
IsEditReturns whether the current environment is in Edit mode.PluginSecurity securitySafe
IsResimulatingReturns whether the client is currently in a resimulation step after a misprediction in the server authority model.Safe
IsRunModeReturns whether a Run playtest has been initiated in Studio.Safe
IsRunningReturns whether the experience is currently running.
IsServerReturns whether the current environment is running on the server.Safe
IsStudioReturns whether the current environment is running in Studio.Safe
PausePauses the experience's simulation if it is running, suspending physics and scripts.PluginSecurity security
ResetResets the current game to a waypoint set when RunService:Run() was called.PluginSecurity securityDeprecated
RunRuns the game's simulation, running physics and scripts.PluginSecurity security
SetPredictionModeSets the prediction mode for an Instance to an PredictionMode value.
StopStops the experience's simulation if it is running.PluginSecurity security
UnbindFromRenderStepUnbinds a function that was bound to the render loop using RunService:BindToRenderStep().

BindToAnimation(function: Function, frequency: StepFrequency = Hz30, priority: int = 2000): RBXScriptConnection#

BindToAnimation() binds a custom function to be called at a fixed frequency which is independent of the frame rate. When Workspace.UseFixedSimulation is enabled, these functions are invoked before Animators update, making this the fixed-frequency counterpart to PreAnimation. When fixed simulation is disabled, they instead run immediately before BindToSimulation() callbacks, so no pre-animation ordering should be assumed. In the server authority model, bound functions will also get called when the client needs to resimulate.

Like BindToSimulation(), the bound function is meant for physics controllers and prediction, so an error will trigger if you read or write from unsynchronized properties or call an unsynchronized method. This error is meant to help guide you in writing a pure, synchronized simulation.

To synchronize inaccessible properties, you should store the relevant data in attributes and update the relevant property in PostSimulation or RenderStepped by reading from attributes. This will leverage attribute synchronization to keep the property fully synchronized through the rollback mechanism.

NameTypeDefaultDescription
functionFunctionThe function to call. This function will be passed one parameter called deltaTime, which shows the elapsed time since the callback's previous invocation.
frequencyStepFrequencyHz30Optional StepFrequency value indicating the frequency at which to call the bound function. Defaults to StepFrequency.Hz30.
priorityint2000Optional priority of the binding as an integer; it determines the order in which bound functions are called within a simulation step. Lower numbers are called first. If two bindings have the same priority, the order between them is unspecified. Defaults to 2000.
Returns

BindToRenderStep(name: string, priority: int, function: Function): ()#

The BindToRenderStep() function binds a custom function to be called at a specific time during the render step. There are three main arguments: 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.

Luau
local RunService = game:GetService("RunService")

local function functionToBind() end

-- Bind the function above to the binding named "tempBinding"
RunService:BindToRenderStep("tempBinding", 1, functionToBind)
-- Unbind the function bound to "tempBinding"
RunService:UnbindFromRenderStep("tempBinding")
Priority#

The priority of the binding is an integer; it 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 engine will randomly pick one to run first. The default 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 RenderPriority, remember to use .Value at the end of the desired enum. RunService:BindToRenderStep() will not work if just the enum is used on its own.

Luau
local RunService = game:GetService("RunService")

local function beforeCamera(delta)
	-- Code in here will run before the default camera script
end

RunService:BindToRenderStep("Before camera", Enum.RenderPriority.Camera.Value - 1, beforeCamera)
Custom Function and Delta Time#

The last argument (function) is the custom function to call. This function will be passed one parameter called deltaTime which 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 takes too long, the experience visuals will be choppy.

NameTypeDefaultDescription
namestringLabel for the binding which can be used with Unbind if the binding is no longer needed.
priorityintPriority of the binding as an integer; it 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 engine will randomly pick one to run first.
functionFunctionThe custom function being bound.
Returns
  • ()

BindToSimulation(function: Function, frequency: StepFrequency = Hz30, priority: int = 2000): RBXScriptConnection#

BindToSimulation() binds a custom function to be called at a fixed frequency which is independent of the frame rate. In the server authority model, bound functions will also get called when the client needs to resimulate. This method is only available when Workspace.UseFixedSimulation is enabled.

Note that since the bound function is meant for physics controllers and prediction, an error will trigger if you read or write from unsynchronized properties or call an unsynchronized method. This error is meant to help guide you in writing a pure, synchronized simulation.

To synchronize inaccessible properties, you should store the relevant data in attributes and update the relevant property in PostSimulation or RenderStepped by reading from attributes. This will leverage attribute synchronization to keep the property fully synchronized through the rollback mechanism.

NameTypeDefaultDescription
functionFunctionThe function to call. This function will be passed one parameter called deltaTime which shows how much time passed between the beginning of the previous simulation step and the beginning of the current simulation step.
frequencyStepFrequencyHz30Optional StepFrequency value indicating the frequency at which to call the bound function. If not provided, the default frequency will be used.
priorityint2000Optional priority of the binding as an integer; it determines the order in which bound functions are called within a simulation step. Lower numbers are called first. If two bindings have the same priority, the order between them is unspecified. Defaults to 2000.
Returns

GetPredictionStatus(context: Instance): PredictionStatus#

Clients can use this method to check the PredictionStatus of a specific context instance, useful for debugging scripts affecting multiple instances (vehicle controllers, custom physics, etc.) where some might be predicted and others might not. This method is also useful for debugging and observing the effects of PredictionMode.Automatic prediction mode.

NameTypeDefaultDescription
contextInstanceThe Instance for which to check prediction status.
Returns

IsClient(): boolean#

Safe

If the code that invoked this method is running in a client context (in a LocalScript, in a ModuleScript required by a LocalScript, or in a Script with RunContext set to RunContext.Client), this method will return true. In all other cases, this method will return false.

If this method returns true, the current environment can access client‑only features like RunService.PreRender or Players.LocalPlayer.

Returns
  • boolean — Whether the current environment is running the client.

IsEdit(): boolean#

PluginSecurity securitySafe

This method returns whether the current environment is in "edit" mode, for example in Studio when the experience is not running.

IsEdit() will return the inverse of IsRunning(), except when the simulation has been paused, in which case both methods will return false.

Returns
  • boolean — Whether the current environment is in "edit" mode.

IsResimulating(): boolean#

Safe

Returns true if the engine is currently replaying simulation steps after detecting a misprediction in the server authority model; returns false otherwise. When the server's authoritative state diverges from the client's predicted state, the client rolls back and rapidly resimulates all affected steps within a single frame. During that resimulation pass, BindToSimulation() callbacks and property-changed signals fire again for each replayed step, which can cause unwanted side effects such as duplicate sound playback or redundant network requests.

Returns
  • boolean — Whether the engine is currently resimulating.

IsRunMode(): boolean#

Safe

This method returns whether a Run playtest has been initiated in Studio. It 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. Note that Studio only enters "run" mode when a Run playtest (without the user's player character) is initiated. Also note that this method will return false if the simulation was started using RunService:Run().

Returns
  • boolean — Whether a Run playtest has been initiated in Studio.

IsRunning(): boolean#

Returns whether the experience is currently running. IsRunning() will always return the inverse of IsEdit() except when the simulation has been paused, in which case both methods will return false.

Returns
  • boolean — Whether the experience is currently running.

IsServer(): boolean#

Safe

This method 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 with RunContext set to RunContext.Server or RunContext.Legacy, or in a ModuleScript required by a Script), this method will return true. In all other cases, this method will return false.

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

Returns
  • boolean — Whether the current environment is running on the server.

IsStudio(): boolean#

Safe

This method returns whether the current environment is running in Studio. It can be used to wrap code that should only execute when testing in Studio.

Returns
  • boolean — Whether the current environment is running in Studio.

Pause(): ()#

PluginSecurity security

This method pauses the experience's simulation if it is running, suspending physics and scripts. When the simulation is paused, IsRunning() will return false.

Returns
  • ()

Reset(): ()#

DeprecatedPluginSecurity securityDeprecated

Deprecated. This item is deprecated and should not be used in new work.

The Reset function resets the current game to a waypoint set when Run was called. This method should only be used after Run was called.

Returns
  • ()

Run(): ()#

PluginSecurity security

This method runs the experience's simulation (physics and scripts). When the simulation is running, IsRunning() will return true. However, IsRunMode() will only return true if the simulation was started using the Run button in Studio.

Returns
  • ()

SetPredictionMode(context: Instance, mode: PredictionMode): ()#

Sets the prediction mode for an Instance (context) to an PredictionMode value. Mismatches between the physics properties or attributes for predicted instances will cause a rollback and resimulation on the client. Can only be called on the client.

NameTypeDefaultDescription
contextInstanceThe Instance for which to set the prediction mode.
modePredictionModeThe PredictionMode to set for the context instance.
Returns
  • ()

Stop(): ()#

PluginSecurity security

This method stops the experience's simulation if it is running. When the simulation is stopped, IsRunning() will return false and IsEdit() will return true.

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

Returns
  • ()

UnbindFromRenderStep(name: string): ()#

Given a name of a function sent to BindToRenderStep(), this method will unbind the function from being called during PreRender. 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 takes no action and continues without raising an error.

NameTypeDefaultDescription
namestringThe name of the function being unbound.
Returns
  • ()

Events 9#

HeartbeatFires every frame, after the physics simulation has completed.
MispredictionIn the server authority model, fires during prediction when the engine detects that the client has diverged from the server's authoritative state. Intended for plugin-based debugging.
PostSimulationFires every frame, after the physics simulation has completed.
PreAnimationFires every frame, prior to the physics simulation but after rendering.
PreRenderFires every frame, prior to the frame being rendered.
PreSimulationFires every frame, prior to the physics simulation.
RenderSteppedFires every frame, prior to the frame being rendered.
RollbackIn the server authority model, this fires after rolling back the predicted state due to a misprediction, but before resimulation begins.
SteppedFires every frame, prior to the physics simulation.

Heartbeat(deltaTime: double)#

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

This event is when most scripts run. It occurs at the end of each frame and it's also when any waiting scripts are executed, such as those scheduled with the task library. Heartbeat is commonly used for periodic tasks, such as updating core game systems like health regeneration.

Following this step, the engine sends property updates and events to the server or clients which are later received as part of the replication receive step.

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

Misprediction(time: double, instances: Array, stats: Dictionary)#

With server authority enabled, the Misprediction event fires when a received server state differs from the predicted state.

Use this event to build debugging tools that inspect misprediction data programmatically. For example, a plugin could listen for this event and track which instances are frequently mispredicting, what properties are diverging, and by how much.

Instances Array#

Each entry in the instances array is a table with the following structure:

Field Type Description
Instance Instance The instance that was mispredicted.
Properties dictionary? Properties that were mispredicted. Each key is a property name mapping to a table with the client's Predicted and owner's/server's Authoritative values as captured on the step when the client first mispredicted the owner's value. Only present if there are property mismatches.
Attributes dictionary? Attributes that were mispredicted. Each key is a property name mapping to a table with the client's Predicted and owner's/server's Authoritative values as captured on the step when the client first mispredicted the owner's value. Only present if there are attribute mismatches.
Stats Dictionary#

The stats dictionary contains the following fields:

Field Type Description
ResimulationTime number The time spent during resimulation (or the amount of time rolled back).
Code Sample#
NameTypeDefaultDescription
timedoubleThe time (in seconds) from the start of simulation at which the client's predicted state first diverged from the server's authoritative state.
instancesArrayAn array of tables, each describing an Instance that was mispredicted. See below for the structure of each entry.
statsDictionaryA dictionary of statistics about the misprediction. See below for the structure.

PostSimulation(deltaTimeSim: double)#

The PostSimulation event fires every frame, after the physics simulation has completed. The deltaTimeSim argument indicates the time that the current frame has stepped the physics simulation, not accounting for physics throttling. This may deviate from the actual time between frames in Studio edit mode or when framerate is very low.

This event is useful for making final adjustments to the outcome of the simulation. Following this phase, the engine triggers the Heartbeat event.

NameTypeDefaultDescription
deltaTimeSimdoubleThe time (in seconds) that the current frame has stepped the physics simulation, not accounting for physics throttling.

PreAnimation(deltaTimeSim: double)#

The PreAnimation event fires every frame, prior to the physics simulation but after rendering. The deltaTimeSim argument indicates the time that the current frame has stepped animations.

This event is useful for modifying animation objects, such as adjusting their speed or priority. Once the PreAnimation event is complete, the engine proceeds to run these animations, updating the joint transforms which will later be used to update objects during the physics simulation.

After animations are stepped, the engine triggers the PreSimulation event.

NameTypeDefaultDescription
deltaTimeSimdoubleThe time (in seconds) that the current frame has stepped animations.

PreRender(deltaTimeRender: double)#

The PreRender event (replacement for RenderStepped) fires every frame, prior to the frame being rendered. The deltaTimeRender argument indicates the time that has elapsed since the previous frame.

This event allows you to run code and update the world before it's drawn on a player's screen. This is useful for last‑minute adjustments such as changing object positions, updating animations, or preparing visual effects, but it should be used sparingly as the engine cannot start to render the frame until code running in this event has finished executing.

As PreRender is client-side, it can only be used in a LocalScript, in a ModuleScript required by a LocalScript, or in a Script with RunContext set to RunContext.Client.

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

PreSimulation(deltaTimeSim: double)#

The PreSimulation event (replacement for Stepped) fires every frame, prior to the physics simulation. The deltaTimeSim argument indicates the time that the current frame will step the physics simulation, not accounting for physics throttling. This may deviate from the actual time between frames in Studio edit mode or when framerate is very low.

This event is useful for adjusting properties like velocity or forces just before they're applied as part of the simulation. The simulation then runs, potentially multiple times, as the physics solver runs at a higher frequency than other engine systems. Once this is complete, the PostSimulation event is fired.

NameTypeDefaultDescription
deltaTimeSimdoubleThe time (in seconds) that the current frame will step the physics simulation, not accounting for physics throttling.

RenderStepped(deltaTime: double)#

Fires every frame, prior to the frame being rendered.

Migration Note#

This event has been superseded by PreRender which should be used for new work.

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

Rollback(time: double)#

When server authority is enabled, the Rollback event fires after the engine detects a misprediction and rolls back all eligible state (properties, attributes, and related physics and animation state), but before the engine resimulates the rolled-back steps.

Use this event to update state in your place that wouldn't otherwise be rolled back after a misprediction. For example, if you maintain gameplay state that can't be stored in a property or attribute with simulation access, you can listen for this event, compare the rolled-back-to step against your farthest-reached step, and rewind your custom state accordingly.

NameTypeDefaultDescription
timedoubleThe time (in seconds) that we are rolling back to.

Stepped(time: double, deltaTime: double)#

Fires every frame, prior to the physics simulation.

Migration Note#

This event has been superseded by PreSimulation which should be used for new work.

NameTypeDefaultDescription
timedoubleThe duration (in seconds) that RunService has been running for.
deltaTimedoubleThe time (in seconds) that has elapsed since the previous frame.

Inherited members#

Inherited from Instance 58
Properties (10)

Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId

Methods (39)

AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild

Events (9)

AncestryChanged, AttributeChanged, ChildAdded, childAdded, ChildRemoved, DescendantAdded, DescendantRemoving, Destroying, StyledPropertiesChanged

Inherited from Object 6
Properties (2)

ClassName, className

Methods (3)

GetPropertyChangedSignal, IsA, isA

Events (1)

Changed