# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: RunService type: class memory_category: Instances summary: | Service responsible for all runtime activity and progression of time. description: | `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 `Class.RunService:IsClient()|IsClient()`, `Class.RunService:IsServer()|IsServer()`, and `Class.RunService:IsStudio()|IsStudio()` can help you determine under what context code is running. These methods are useful for `Class.ModuleScript|ModuleScripts` that may be required by both client and server scripts. Furthermore, `Class.RunService:IsStudio()|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 `Class.RunService.PreRender|PreRender`, `Class.RunService.PreAnimation|PreAnimation`, `Class.RunService.PreSimulation|PreSimulation`, `Class.RunService.PostSimulation|PostSimulation`, and `Class.RunService.Heartbeat|Heartbeat`. Selecting the proper event to use for any case is important, so you should read [Task Scheduler](../../../performance-optimization/microprofiler/task-scheduler.md) 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
code_samples: [] inherits: - Instance descendants: [] tags: - NotCreatable - Service - NotReplicated deprecation_message: '' properties: - name: RunService.ClientGitHash summary: '' description: '' code_samples: [] type: string tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: RobloxScriptSecurity write: RobloxScriptSecurity thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Basic - name: RunService.RunState summary: '' description: '' code_samples: [] type: RunState tags: - NotReplicated deprecation_message: '' security: read: PluginSecurity write: PluginSecurity thread_safety: ReadSafe category: Data serialization: can_load: false can_save: false capabilities: - Basic methods: - name: RunService:BindToRenderStep summary: | Given a string name of a function and a priority, this method binds the function to `Class.RunService.PreRender`. description: | 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 `Class.RunService:UnbindFromRenderStep()` if the binding is no longer needed. ```lua 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 `Enum.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 `.Value` at the end of the desired enum. `Class.RunService:BindToRenderStep()` will not work if just the enum is used on its own. ```lua 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. code_samples: - RunService-BindToRenderStep - runservice-custom-function - runservice-unbindfromrenderstep parameters: - name: name type: string default: summary: | Label for the binding which can be used with `Class.RunService.Unbind|Unbind` if the binding is no longer needed. - name: priority type: int default: summary: | Priority 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. - name: function type: Function default: summary: | The custom function being bound. returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Basic - name: RunService:BindToSimulation summary: | Binds a custom function to be called at a fixed frequency which is independent of the frame rate. description: | `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 `Class.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](../../../studio/properties.md#instance-attributes) and update the relevant property in `Class.RunService.PostSimulation|PostSimulation` or `Class.RunService.RenderStepped|RenderStepped` by reading from attributes. This will leverage attribute synchronization to keep the property fully synchronized through the rollback mechanism. code_samples: - RunService-BindToSimulation parameters: - name: function type: Function default: summary: | The 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. - name: frequency type: StepFrequency default: Hz60 summary: | Optional `Enum.StepFrequency` value indicating the frequency at which to call the bound function. If not provided, the default frequency will be used. returns: - type: RBXScriptConnection summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Basic - name: RunService:GetPredictionStatus summary: | Checks the `Enum.PredictionStatus` of a specific context instance, useful for debugging scripts affecting multiple instances where some might be predicted and others might not. description: | Clients can use this method to check the `Enum.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 `Enum.PredictionMode.Automatic` prediction mode. code_samples: [] parameters: - name: context type: Instance default: summary: | The `Class.Instance` for which to check prediction status. returns: - type: PredictionStatus summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Basic - name: RunService:IsClient summary: | Returns whether the current environment is running on the client. description: | If the code that invoked this method is running in a client context (in a `Class.LocalScript`, in a `Class.ModuleScript` required by a `Class.LocalScript`, or in a `Class.Script` with `Class.BaseScript.RunContext|RunContext` set to `Enum.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 `Class.RunService.PreRender` or `Class.Players.LocalPlayer`. code_samples: [] parameters: [] returns: - type: boolean summary: | Whether the current environment is running the client. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Basic - name: RunService:IsEdit summary: | Returns whether the current environment is in `Edit` mode. description: | 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 `Class.RunService:IsRunning()|IsRunning()`, except when the simulation has been paused, in which case both methods will return `false`. code_samples: [] parameters: [] returns: - type: boolean summary: | Whether the current environment is in "edit" mode. tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Safe capabilities: - Basic - name: RunService:IsRunMode summary: | Returns whether a **Run** playtest has been initiated in Studio. description: | 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 `Class.RunService:Run()`. code_samples: [] parameters: [] returns: - type: boolean summary: | Whether a **Run** playtest has been initiated in Studio. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Basic - name: RunService:IsRunning summary: | Returns whether the experience is currently running. description: | Returns whether the experience is currently running. `IsRunning()` will always return the inverse of `Class.RunService:IsEdit()|IsEdit()` except when the simulation has been paused, in which case both methods will return `false`. code_samples: [] parameters: [] returns: - type: boolean summary: | Whether the experience is currently running. tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Basic - name: RunService:IsServer summary: | Returns whether the current environment is running on the server. description: | 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 `Class.Script` with `Class.BaseScript.RunContext|RunContext` set to `Enum.RunContext.Server` or `Enum.RunContext.Legacy`, or in a `Class.ModuleScript` required by a `Class.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 `Class.ServerStorage` or `Class.ServerScriptService`. code_samples: [] parameters: [] returns: - type: boolean summary: | Whether the current environment is running on the server. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Basic - name: RunService:IsStudio summary: | Returns whether the current environment is running in Studio. description: | 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. code_samples: [] parameters: [] returns: - type: boolean summary: | Whether the current environment is running in Studio. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Basic - name: RunService:Pause summary: | Pauses the experience's simulation if it is running, suspending physics and scripts. description: | This method pauses the experience's simulation if it is running, suspending physics and scripts. When the simulation is paused, `Class.RunService:IsRunning()|IsRunning()` will return `false`. code_samples: [] parameters: [] returns: - type: () summary: '' tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Unsafe capabilities: - Basic - name: RunService:Reset summary: | Resets the current game to a waypoint set when `Class.RunService:Run()` was called. description: | 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. code_samples: [] parameters: [] returns: - type: () summary: '' tags: - Deprecated deprecation_message: | This item is deprecated and should not be used in new work. security: PluginSecurity thread_safety: Unsafe capabilities: - Basic - name: RunService:Run summary: | Runs the game's simulation, running physics and scripts. description: | This method runs the experience's simulation (physics and scripts). When the simulation is running, `Class.RunService:IsRunning()|IsRunning()` will return `true`. However, `Class.RunService:IsRunMode()|IsRunMode()` will only return `true` if the simulation was started using the **Run** button in Studio. code_samples: [] parameters: [] returns: - type: () summary: '' tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Unsafe capabilities: - Basic - name: RunService:SetPredictionMode summary: | Sets the prediction mode for an `Class.Instance` to an `Enum.PredictionMode` value. description: | Sets the prediction mode for an `Class.Instance` (`context`) to an `Enum.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. code_samples: [] parameters: - name: context type: Instance default: summary: | The `Class.Instance` for which to set the prediction mode. - name: mode type: PredictionMode default: summary: | The `Enum.PredictionMode` to set for the context instance. returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Basic - name: RunService:Stop summary: | Stops the experience's simulation if it is running. description: | This method stops the experience's simulation if it is running. When the simulation is stopped, `Class.RunService:IsRunning()|IsRunning()` will return `false` and `Class.RunService:IsEdit()|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. code_samples: [] parameters: [] returns: - type: () summary: '' tags: [] deprecation_message: '' security: PluginSecurity thread_safety: Unsafe capabilities: - Basic - name: RunService:UnbindFromRenderStep summary: | Unbinds a function that was bound to the render loop using `Class.RunService:BindToRenderStep()`. description: | Given a name of a function sent to `Class.RunService:BindToRenderStep()|BindToRenderStep()`, this method will unbind the function from being called during `Class.RunService.PreRender|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. code_samples: [] parameters: - name: name type: string default: summary: | The name of the function being unbound. returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Basic events: - name: RunService.Heartbeat summary: | Fires every frame, after the physics simulation has completed. description: | 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 `Library.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](../../../projects/client-server.md#replication) receive step. code_samples: [] parameters: - name: deltaTime type: double default: summary: | The time (in seconds) that has elapsed since the previous frame. tags: [] deprecation_message: '' security: None capabilities: - Basic - name: RunService.PostSimulation summary: | Fires every frame, after the physics simulation has completed. description: | 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 `Class.RunService.Heartbeat|Heartbeat` event. code_samples: [] parameters: - name: deltaTimeSim type: double default: summary: | The time (in seconds) that the current frame has stepped the physics simulation, not accounting for physics throttling. tags: [] deprecation_message: '' security: None capabilities: - Basic - name: RunService.PreAnimation summary: | Fires every frame, prior to the physics simulation but after rendering. description: | 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 `Class.RunService.PreSimulation|PreSimulation` event. code_samples: [] parameters: - name: deltaTimeSim type: double default: summary: | The time (in seconds) that the current frame has stepped animations. tags: [] deprecation_message: '' security: None capabilities: - Basic - name: RunService.PreRender summary: | Fires every frame, prior to the frame being rendered. description: | The `PreRender` event (replacement for `Class.RunService.RenderStepped|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 `Class.LocalScript`, in a `Class.ModuleScript` required by a `Class.LocalScript`, or in a `Class.Script` with `Class.BaseScript.RunContext|RunContext` set to `Enum.RunContext.Client`. Following the `PreRender` phase, the simulation phase begins with the `Class.RunService.PreAnimation|PreAnimation` event. code_samples: [] parameters: - name: deltaTimeRender type: double default: summary: | The time (in seconds) that has elapsed since the previous frame. tags: [] deprecation_message: '' security: None capabilities: - Basic - name: RunService.PreSimulation summary: | Fires every frame, prior to the physics simulation. description: | The `PreSimulation` event (replacement for `Class.RunService.Stepped|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 `Class.RunService.PostSimulation|PostSimulation` event is fired. code_samples: [] parameters: - name: deltaTimeSim type: double default: summary: | The time (in seconds) that the current frame will step the physics simulation, not accounting for physics throttling. tags: [] deprecation_message: '' security: None capabilities: - Basic - name: RunService.RenderStepped summary: | Fires every frame, prior to the frame being rendered. description: | Fires every frame, prior to the frame being rendered. ##### Migration Note This event has been superseded by `Class.RunService.PreRender|PreRender` which should be used for new work. code_samples: [] parameters: - name: deltaTime type: double default: summary: | The time (in seconds) that has elapsed since the previous frame. tags: [] deprecation_message: '' security: None capabilities: - Basic - name: RunService.Stepped summary: | Fires every frame, prior to the physics simulation. description: | Fires every frame, prior to the physics simulation. ##### Migration Note This event has been superseded by `Class.RunService.PreSimulation|PreSimulation` which should be used for new work. code_samples: [] parameters: - name: time type: double default: summary: | The duration (in seconds) that `Class.RunService` has been running for. - name: deltaTime type: double default: summary: | The time (in seconds) that has elapsed since the previous frame. tags: [] deprecation_message: '' security: None capabilities: - Basic callbacks: []