rojo/.cursor/rules/roblox/reference/engine/classes/RunService.yaml

# 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

  <table size="small">
    <thead>
      <tr>
        <th>Environment</th>
        <th><code>Class.RunService:IsStudio()|IsStudio</code></th>
        <th><code>Class.RunService:IsClient()|IsClient</code></th>
        <th><code>Class.RunService:IsServer()|IsServer</code></th>
        <th><code>Class.RunService:IsEdit()|IsEdit</code></th>
        <th><code>Class.RunService:IsRunning()|IsRunning</code></th>
        <th><code>Class.RunService:IsRunMode()|IsRunMode</code></th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Live (Client)</td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Live (Server)</td>
        <td><code>false</code></td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Edit</td>
        <td><code>true</code></td>
        <td><code>true</code></td>
        <td><code>true</code></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Collaborative Edit</td>
        <td><code>true</code></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Run Mode</td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>true</code></td>
      </tr>
      <tr>
        <td>Play Mode (Client)</td>
        <td><code>true</code></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Play Mode (Server)</td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Team Test (Client)</td>
        <td><code>true</code></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Team Test (Server)</td>
        <td><code>true</code></td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td></td>
        <td><code>true</code></td>
        <td><code>false</code></td>
      </tr>
      <tr>
        <td>Luau Execution</td>
        <td><code>false</code></td>
        <td><code>false</code></td>
        <td><code>true</code></td>
        <td></td>
        <td><code>false</code></td>
        <td><code>false</code></td>
      </tr>
    </tbody>
  </table>
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: []