hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-23 22:11:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

rules

Browse source
This commit is contained in:
Joe 2026-02-02 12:08:47 -06:00
parent a9b4f8e83b
commit e6efc04756
8494 changed files with 495610 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

842
.cursor/rules/roblox/reference/engine/classes/RunService.yaml Normal file
View file

@ -0,0 +1,842 @@
# 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: []