Class
ScriptProfilerService
NotCreatableService
A service that captures sampling-based profiles of Luau script execution on the server or on a client.
ScriptProfilerService provides a scripting interface to Roblox's Luau script
profiler, which periodically samples running Luau threads to attribute CPU
time to the functions that consume it.
Profiling is controlled independently for the server and for individual
clients: ServerStart() and
ServerStop() govern server-side
scripts, while ClientStart() and
ClientStop() govern a given
player's client. Calling
ServerRequestData() or
ClientRequestData() collects
a snapshot of the profiling results, which is delivered asynchronously through
the OnNewData event as a JSON string.
That string can be turned into a structured Luau table with
DeserializeJSON().
This service powers the Script Profiler in the in-experience Developer Console.
Methods 7#
| ClientRequestData | Requests the current script profiling data from the specified player's client.PluginSecurity security |
| ClientStart | Begins Luau script profiling for the specified player's client.PluginSecurity security |
| ClientStop | Stops Luau script profiling for the specified player's client.PluginSecurity security |
| DeserializeJSON | Parses a script-profiling JSON string into a structured Luau table.PluginSecurity securityCustomLuaState |
| ServerRequestData | Requests the current script profiling data from the server.PluginSecurity security |
| ServerStart | Begins Luau script profiling on the server.PluginSecurity security |
| ServerStop | Stops Luau script profiling on the server.PluginSecurity security |
ClientRequestData(player: Player): ()#
PluginSecurity security
Requests a snapshot of the profiling data collected for the given player's
client. The data is not returned directly; instead it is delivered
asynchronously through the
OnNewData event as a JSON string.
When called on the server this replicates a data request to the target
client, and when called on the client it gathers the local player's
profiling data directly. On a client the player argument must be the
local player.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The Player whose client should report its profiling data. When
called on a client, this must be the local player. |
Returns
()
ClientStart(player: Player, frequency: int?): ()#
PluginSecurity security
Begins profiling the Luau scripts running on the given player's client.
The profiler periodically samples running Luau threads at frequency
samples per second; if frequency is omitted it defaults to 1000, and a
value outside the range [1, 10000] raises an error.
When called on the server this replicates a request to the target client
to start profiling, and when called on the client it starts sampling the
local player's scripts directly. On a client the player argument must be
the local player.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The Player whose client should start profiling. When called on
a client, this must be the local player. | |
frequency | int? | Optional sampling frequency in samples per second. Defaults to 1000
and must be within the range [1, 10000]. |
Returns
()
ClientStop(player: Player): ()#
PluginSecurity security
Stops profiling the Luau scripts running on the given player's client.
When called on the server this replicates a request to the target client
to stop profiling, and when called on the client it stops sampling the
local player's scripts directly. On a client the player argument must be
the local player.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The Player whose client should stop profiling. When called on
a client, this must be the local player. |
Returns
()
DeserializeJSON(jsonString: string?): Dictionary#
CustomLuaStatePluginSecurity security
Converts the raw JSON produced by the profiler into a Luau table so the results can be inspected programmatically rather than parsed by hand. The returned table mirrors the profiling session, exposing entries such as its version, session start and end times, categories, call nodes, and function metadata.
An empty or non-object input yields no data.
| Name | Type | Default | Description |
|---|---|---|---|
jsonString | string? | The profiling data encoded as a JSON string, such as the value
delivered by OnNewData. |
Returns
Dictionary— A dictionary representing the parsed profiling data, including the session's categories, call nodes, and function metadata.
ServerRequestData(): ()#
PluginSecurity security
Requests a snapshot of the profiling data collected on the server. The
data is not returned directly; instead it is delivered asynchronously
through the OnNewData event as a
JSON string, with no associated player.
Returns
()
ServerStart(frequency: int?): ()#
PluginSecurity security
Begins profiling the Luau scripts running on the server. The profiler
periodically samples running Luau threads at frequency samples per
second; if frequency is omitted it defaults to 1000, and a value
outside the range [1, 10000] raises an error.
| Name | Type | Default | Description |
|---|---|---|---|
frequency | int? | Optional sampling frequency in samples per second. Defaults to 1000
and must be within the range [1, 10000]. |
Returns
()
ServerStop(): ()#
PluginSecurity security
Stops profiling the Luau scripts running on the server.
Returns
()
Events 1#
| OnNewData | Fires when a new profiling data snapshot becomes available after a data request.PluginSecurity security |
OnNewData(player: Player, jsonString: string)#
PluginSecurity security
Fires when a new profiling snapshot becomes available, in response to
ClientRequestData() or
ServerRequestData(). The
data is delivered as a JSON string in jsonString; pass it to
DeserializeJSON() to
obtain a structured table. player identifies the client the data came
from, or is nil when the data was collected on the server.
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