18 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Stats

Inherits from: Instance → Object

Stats is a service that provides real-time performance information about the current running game instance. Its primary purpose is to provide an end point to measure where resources are being consumed, as well as how much memory is being consumed overall.

The service also stores a tree of StatsItem objects which can have their values read by plugins.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Properties

Name	Type / Returns	Description
Stats.ContactsCount	int	A measurement of how many parts are currently in contact with one another.
Stats.DataReceiveKbps	float	In a networked game, this describes roughly how many kilobytes of data are being received by the current instance, per second.
Stats.DataSendKbps	float	In a networked game, this describes roughly how many kilobytes of data are being sent by the current instance, per second.
Stats.FrameTime	float	A measurement of how long it takes for the engine to process all tasks required to render a frame.
Stats.HeartbeatTime	float	A measurement of the total amount of time it takes for the server to update its task scheduler jobs in seconds.
Stats.HeartbeatTimeMs	float	A measurement of the total amount of time it takes long it takes for Roblox to update all of its task scheduler jobs, in milliseconds.
Stats.InstanceCount	int	A measurement of how many `Instance` are currently in memory.
Stats.MemoryTrackingEnabled	boolean	An indication of whether memory tracking is enabled. This is guaranteed to be unchanged until the next time the Client is started.
Stats.MovingPrimitivesCount	int	A measurement of how many physically simulated components are currently moving in the game world.
Stats.PhysicsReceiveKbps	float	In a networked game, this describes roughly how many kilobytes of physics data are being received by the current instance, per second.
Stats.PhysicsSendKbps	float	In a networked game, this describes roughly how many kilobytes of physics data are being sent by the current instance, per second.
Stats.PhysicsStepTime	float	A measurement of how long it takes for the physics engine to update its current state.
Stats.PhysicsStepTimeMs	float	A measurement of how long it takes for the physics engine to update its current state, in milliseconds. If this value is high, then it means the game instance is under stress from the physics simulations taking place.
Stats.PrimitivesCount	int	A measurement of how many physically simulated components currently exist in the game world.
Stats.RenderCPUFrameTime	float	A measurement of how long it takes for the CPU to process all of its rendering tasks for a frame.
Stats.RenderGPUFrameTime	float	A measurement of how long it takes for the GPU to process all of its tasks required to render a frame.
Stats.SceneDrawcallCount	int	A measurement of the number of draw calls made by the game's current scene.
Stats.SceneTriangleCount	int	A measurement of the number of triangles rendered by the game's current scene.
Stats.ShadowsDrawcallCount	int	A measurement of the number of draw calls being made for shadows by the game's current scene.
Stats.ShadowsTriangleCount	int	A measurement of the number of triangles rendered as shadows in the game's current scene.
Stats.UI2DDrawcallCount	int	A measurement of the number of 2D draw calls made for UI elements in the game's current scene.
Stats.UI2DTriangleCount	int	A measurement of the number of triangles that are being rendered for 2D UI elements in the game's current scene.
Stats.UI3DDrawcallCount	int	A measurement of the number of 3D draw calls made for UI elements in the game's current scene.
Stats.UI3DTriangleCount	int	A measurement of the number of triangles being rendered for 3D UI elements in the game's current scene.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Stats.ContactsCount

This property describes how many parts are currently in contact with each other, such that one of the two parts are being physically simulated, and thus can be recognized by the BasePart:GetTouchingParts() method.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.DataReceiveKbps

In a networked game, this property describes roughly how many kilobytes of data are being received by the current instance, per second. If from the server's perspective, this represents the total amount of data being received from the clients connected to the server. If from a client's perspective, this represents the total amount of data being received from the server.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.DataSendKbps

In a networked game, this property describes roughly how many kilobytes of data are being sent by the current instance, per second. If from the server's perspective, this represents the total amount of data being sent to the clients connected to the server. If from a client's perspective, this represents the total amount of data being sent to the server.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.FrameTime

This property is only available in client scripts and is a measurement of how long it took to render the most-recent frame in seconds. Divide 1 by this value to calculate an FPS value for the frame time. High frame times are indicative of performance problems on the device. Consider using the MicroProfiler to troubleshoot.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.HeartbeatTime

This property is a measurement of the total amount of time it takes for the server to update its task scheduler jobs in seconds. If this value is high, examine server compute.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.HeartbeatTimeMs

Deprecated. Use Stats.HeartbeatTime instead.

The HeartbeatTimeMs property is a measurement of the total amount of time it takes long it takes for Roblox to update all of its task scheduler jobs, in milliseconds. If this value is high, then it means one of the tasks are hogging up a lot of resources.

Field	Value
type	float
tags	["ReadOnly","NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.InstanceCount

InstanceCount is a read-only measurement of how many Instance are currently in memory. This includes the DataModel, its descendants, as well as any object created with Instance.new() which is still present in memory.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.MemoryTrackingEnabled

If MemoryTrackingEnabled returns false, any API that returns category-based memory usage such as Stats:GetMemoryUsageMbForTag() or Stats:GetMemoryUsageMbAllCategories() will return 0 and emit a warning. Therefore, usage of category-based memory usage API should be conditional on MemoryTrackingEnabled returning true. The value of MemoryTrackingEnabled will not change from one experience to the next; it will only potentially change after restarting the Roblox client application.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.MovingPrimitivesCount

A measurement of how many physically simulated components are currently moving in the game world.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.PhysicsReceiveKbps

PhysicsReceiveKbps is a measurement of roughly how many kilobytes of physics data are being received by the current instance, per second.If from the server's perspective, this represents the total amount of physics data being received from the clients connected to the server.If from a client's perspective, this represents the total amount of physics data being received from the server.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.PhysicsSendKbps

PhysicsSendKbps describes roughly how many kilobytes of physics data are being sent by the current instance, per second. If from the server's perspective, this represents the total amount of physics data being sent to the clients connected to the server. If from a client's perspective, this represents the total amount of physics data being sent to the server.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.PhysicsStepTime

This property is a measurement of how long it takes for the physics engine to update its current state. If this value is high, it means the game instance is under stress from the physics simulations taking place.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.PhysicsStepTimeMs

Deprecated. Use Stats.PhysicsStepTime instead.

A measurement of how long it takes for the physics engine to update its current state, in milliseconds. If this value is high, then it means the game instance is under stress from the physics simulations taking place.

Field	Value
type	float
tags	["ReadOnly","NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.PrimitivesCount

A measurement of how many physically simulated components currently exist in the game world.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.RenderCPUFrameTime

This property is a measurement of how long it takes for the CPU to process all of its rendering tasks for a frame.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.RenderGPUFrameTime

This property is a measurement of how long it takes for the GPU to process all of its tasks required to render a frame.

Field	Value
type	float
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.SceneDrawcallCount

This property is a measurement of the number of draw calls made by the game's current scene. A draw call is a single rendering operation, such as drawing a mesh. A high draw call count could mean a scene is too complex or unoptimized, which can lead to performance issues.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.SceneTriangleCount

This property is a measurement of the number of triangles rendered by the game's current scene. A count of triangles rendered is useful when trying to estimate the complexity and performance of a scene.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.ShadowsDrawcallCount

This property is a measurement of the number of draw calls being made for shadows by the game's current scene. A high count means more shadows are being created by the amount of rendered objects in a scene.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.ShadowsTriangleCount

This property is a measurement of the number of triangles rendered as shadows in the game's current scene. A high count means there are a lot of triangles used to cast shadows, which can hinder performance.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.UI2DDrawcallCount

This property is a measurement of the number of 2D draw calls made for UI elements in the game's current scene. A high count can mean there are a lot of 2D UI elements being used.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.UI2DTriangleCount

This property is a measurement of the number of triangles that are being rendered for 2D UI elements in the game's current scene. A high count can mean there are many or complex 2D UI elements used, which can contribute to performance loss in regards to rendering.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.UI3DDrawcallCount

This property is a measurement of the number of 3D draw calls made for UI elements in the game's current scene. A high count could indicate a high amount of 3D objects being used within UI, potentially hurting performance; however, it is very unlikely you would see a significant count since UI elements are typically 2D.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Stats.UI3DTriangleCount

This property is a measurement of the number of triangles being rendered for 3D UI elements in the game's current scene; however, it is very unlikely you would see a significant count since UI elements are typically 2D.

Field	Value
type	int
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}

Methods

Name	Type / Returns	Description
Stats:GetHarmonyQualityLevel	int	Internal-only. Returns the engine's current dynamic-quality level as a score normalized from `0` to `100`.
Stats:GetMemoryCategoryNames	Array	Internal-only. Returns an array of the names of every developer memory category the engine tracks.
Stats:GetMemoryUsageMbAllCategories	Array	Returns the number of megabytes that are being consumed by all available categories, or an empty array if `MemoryTrackingEnabled` is `false`.
Stats:GetMemoryUsageMbForTag	float	Returns the number of megabytes that are being consumed in the specified `DeveloperMemoryTag` category, or `0` if `MemoryTrackingEnabled` is `false`.
Stats:GetTotalMemoryUsageMb	float	Returns the total amount of memory being consumed by the current game session, in megabytes.
Stats:ResetHarmonyMemoryTarget	()	Internal-only. Restores the performance-control system's memory budget to the values in effect before `Stats:SetHarmonyMemoryTarget()` was called.
Stats:SetHarmonyMemoryTarget	()	Internal-only. Overrides the performance-control system's memory budget with a target value, in megabytes, for testing.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

Stats:GetHarmonyQualityLevel

Requires the InternalTest security capability; not callable from ordinary scripts. Returns the current quality level selected by the engine's dynamic performance-control system, expressed as a score normalized between 0 (the lowest-quality configuration) and 100 (the highest). The score reflects how the system is currently balancing visual quality against resource usage such as memory and frame time.

Returns

Type	Description
int	The current dynamic-quality level, normalized from `0` (lowest quality) to `100` (highest quality).

Field	Value
security	None
thread safety	Unsafe
capabilities	["InternalTest"]

Stats:GetMemoryCategoryNames

Requires the InternalTest security capability; not callable from ordinary scripts. Returns an array of strings containing the name of every memory category the engine tracks, in category-index order. The entries correspond one-to-one with the measurements returned by Stats:GetMemoryUsageMbAllCategories(), so the two arrays can be read together to label each per-category memory value.

Returns

Type	Description
Array	An array of strings, one per tracked memory category, ordered to match the values returned by `Stats:GetMemoryUsageMbAllCategories()`.

Field	Value
security	None
thread safety	Unsafe
capabilities	["InternalTest"]

Stats:GetMemoryUsageMbAllCategories

Returns the number of megabytes that are being consumed by all available categories. If MemoryTrackingEnabled is false, calling GetMemoryUsageMbAllCategories() will return an empty array and emit a warning to the console.

Returns

Type	Description
Array	An array of numbers in which each entry is the memory, in megabytes, consumed by one memory category, ordered to match the categories returned by `Stats:GetMemoryCategoryNames()`. Returns an empty array if `MemoryTrackingEnabled` is `false`.

Field	Value
security	None
thread safety	Unsafe
capabilities	["InternalTest"]

Stats:GetMemoryUsageMbForTag

Returns the number of megabytes that are being consumed in the specified DeveloperMemoryTag category. If MemoryTrackingEnabled is false, calling GetMemoryUsageMbForTag() will return 0 and emit a warning to the console.

Parameters

Name	Type	Default	Description
tag	DeveloperMemoryTag		The `DeveloperMemoryTag` memory category to measure.

Returns

Type	Description
float	The memory, in megabytes, consumed by the given `DeveloperMemoryTag` category, or `0` if `MemoryTrackingEnabled` is `false`.

Field	Value
security	None
thread safety	Unsafe

Stats:GetTotalMemoryUsageMb

Returns the total amount of memory being consumed by the current game session, in megabytes.

This method gets memory usage from the operating system, which may exclude memory that has been paged out to disk. As such, the return value tends to differ significantly from the sum of usage for all DeveloperMemoryTags. The return value should be very similar to memory usage for Roblox in the Windows Task Manager or macOS Activity Monitor.

Returns

Type	Description
float	The total memory, in megabytes, used by the current game session, as reported by the operating system.

Field	Value
security	None
thread safety	Unsafe

Stats:ResetHarmonyMemoryTarget

Requires the InternalTest security capability; not callable from ordinary scripts. Reverts the artificial memory budget applied by Stats:SetHarmonyMemoryTarget(), restoring the memory-override enable state and limit that were captured before the first call to SetHarmonyMemoryTarget(). After this call, the performance-control system resumes using the device's real available memory when making dynamic-quality decisions.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["InternalTest"]

Stats:SetHarmonyMemoryTarget

Requires the InternalTest security capability; not callable from ordinary scripts. Forces the engine's dynamic performance-control system to operate against an artificial memory budget of targetMB megabytes instead of the device's real available memory, making it behave as though only that much memory is available. This lets you test how dynamic quality and memory reclamation respond under a chosen level of memory pressure. The first call records the pre-override settings so that a later call to Stats:ResetHarmonyMemoryTarget() can restore them.

Parameters

Name	Type	Default	Description
targetMB	int		The memory budget to impose on the performance-control system, in megabytes.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["InternalTest"]

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.