mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-23 14:01:37 +00:00
update rules
This commit is contained in:
Joe
parent
4c390fdd37
commit
d5522b2fef
8549 changed files with 11783 additions and 1888 deletions
217
.cursor/rules/roblox/en-us/studio/optimization/memory-usage.md
Normal file
217
.cursor/rules/roblox/en-us/studio/optimization/memory-usage.md
Normal file
|
|
@ -0,0 +1,217 @@
|
|||
---
|
||||
title: Memory usage
|
||||
description: Use Memory and Luau Heap tools within the Developer Console to monitor the memory usage of your experience.
|
||||
---
|
||||
|
||||
import OpeningSteps from '../../includes/developer-console/opening-developer-console.md'
|
||||
|
||||
Every building and scripting component that you add to your experience consumes memory. When memory usage reaches engine limits, the user's device or server may crash, so you need to actively monitor usage.
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/x1JgsC8c8VQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe><br />
|
||||
|
||||
The **Developer Console** provides two tools for monitoring memory usage:
|
||||
|
||||
- [Memory](#memory) — View real-time memory consumption by usage categories, including your custom components and the engine internal processes.
|
||||
|
||||
- [Luau heap](#luau-heap) — Create snapshots of heap memory, which refers to the memory allocation of your scripts. This tool provides several views to help you identify current memory allocation and issues from different perspectives, such as object types and engine classes. It also allows you to create multiple snapshots to compare differences in memory usage over time.
|
||||
|
||||
<OpeningSteps components={props.components}/>
|
||||
|
||||
## Memory
|
||||
|
||||
The **Memory** tool categorizes and displays real-time memory usage. It displays memory usage in MB of each category and generates a chart on usage change over time.
|
||||
|
||||
To view memory allocation:
|
||||
|
||||
1. Open the **Developer Console**.
|
||||
1. Expand the tools dropdown to select **Memory**.
|
||||
|
||||
<img src="../../assets/studio/console/Memory-Open.png" width="200" alt="Dropdown menu of all Developer Console tools with the Memory option highlighted for selection." />
|
||||
|
||||
1. Expand the client-server dropdown to select **Client** or **Server**.
|
||||
1. Browse the memory usage categories and items. If you want to see usage over time, expand the category to display a chart.
|
||||
|
||||
- **CoreMemory** — Memory usage by the core building processes of the engine, including networking, avatars, and GUI elements that you don't have direct control over.
|
||||
- **PlaceMemory** — Memory usage based on how you build your experience, including models, terrain, parts, scripts, and all other custom elements that you add to your experience.
|
||||
|
||||
<BaseAccordion>
|
||||
<AccordionSummary>
|
||||
<Typography variant="h6">PlaceMemory reference</Typography>
|
||||
</AccordionSummary>
|
||||
<AccordionDetails>
|
||||
<table size="small">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Category</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>**HttpCache**</td>
|
||||
<td>Assets (images, meshes, etc.) loaded from Roblox servers and now held in a cache in memory.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Instances**</td>
|
||||
<td>`Class.Instance|Instances` in the place.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Signals**</td>
|
||||
<td>Signals that fire between instances (an event firing on one instance to trigger an event on another instance).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**LuaHeap**</td>
|
||||
<td>Heap memory for both core scripts (scripts that ship with the Roblox client) and custom scripts.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Script**</td>
|
||||
<td>Luau scripts.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**PhysicsCollision**</td>
|
||||
<td>Collision data for physics simulations.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**PhysicsParts**</td>
|
||||
<td>Physics geometry and kinetics.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsSolidModels**</td>
|
||||
<td>Graphics data to render solid models.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsMeshParts**</td>
|
||||
<td>Graphics for `Class.MeshPart` objects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsParticles**</td>
|
||||
<td>Graphics for particle systems.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsParts**</td>
|
||||
<td>Graphics for parts.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsSpatialHash**</td>
|
||||
<td>General rendering.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsTerrain**</td>
|
||||
<td>Graphics for terrain.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsTexture**</td>
|
||||
<td>Texture memory.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**GraphicsTextureCharacter**</td>
|
||||
<td>Texture memory for characters.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Sounds**</td>
|
||||
<td>In-memory sounds.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**StreamingSounds**</td>
|
||||
<td>Streaming sounds.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**TerrainVoxels**</td>
|
||||
<td>Terrain voxels.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**TerrainPhysics**</td>
|
||||
<td>Terrain physics.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Gui**</td>
|
||||
<td>Memory used by common GUI elements.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Animation**</td>
|
||||
<td>Memory used for animation data, such as poses and `Class.KeyframeSequence` cached data for avatar animations.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>**Navigation**</td>
|
||||
<td>Memory used by supporting structures for `Class.PathfindingService`.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</AccordionDetails>
|
||||
</BaseAccordion>
|
||||
|
||||
- **UntrackedMemory** — Memory allocations that the system can't easily attribute to a particular source.
|
||||
- **PlaceScriptMemory** — Memory usage of your scripts with insights into how individual scripts and custom memory tags contribute to overall memory usage.
|
||||
- **CoreScriptMemory** — Memory usage by internal engine scripts that you don't have direct control over.
|
||||
|
||||
Among these categories, **PlaceMemory** and **PlaceScriptMemory** are the most important ones for performance optimization, because they help you understand how your building and scripting choices affect memory consumption and potential areas for optimization. For more insights into **PlaceScriptMemory**, use the [Luau heap](#luau-heap) tool to create snapshots and analyze memory allocation by different metrics.
|
||||
|
||||
<Alert severity="info">
|
||||
For more information on common memory usage problems and best practices, see [Performance Optimization](../../performance-optimization/improve.md#memory-usage).
|
||||
</Alert>
|
||||
|
||||
## Luau heap
|
||||
|
||||
The **Luau heap** tool allows you to create snapshots of the current allocation of heap memory, which refers to the memory Luau scripts use to store variables, tables, functions, and other runtime data structures. This tool provides several views to help you identify issues from different perspectives, such as object types and engine classes. It also allows you to create multiple snapshots to compare differences in memory usage over time.
|
||||
|
||||
### Create snapshots
|
||||
|
||||
To create a snapshot of your memory allocation:
|
||||
|
||||
1. Open the **Developer Console**.
|
||||
1. Expand the tools dropdown to select **LuauHeap**.
|
||||
|
||||
<img src="../../assets/studio/console/LuauHeap-Open.png" width="200" alt="Dropdown menu of all Developer Console tools with the LuauHeap option highlighted for selection." />
|
||||
|
||||
1. Expand the client-server dropdown to select **Client** or **Server**.
|
||||
1. Click the **Create Snapshot** button.
|
||||
|
||||
### Analyze memory usage
|
||||
|
||||
The tool provides many views into Luau memory usage:
|
||||
|
||||
- **Graph** — Shows an aggregated memory usage tree, with each node representing an object with memory allocated.
|
||||
- **Object Tags** — Shows memory sizes and counts by runtime types, such as `function`, `table`, and `thread`.
|
||||
- **Memory Categories** — Shows memory sizes and counts by engine-assigned memory categories. The engine assigns a memory category to an object at allocation time.
|
||||
- **Object Classes** — Shows memory sizes and counts by engine classes that your scripts use and store their instances, such as `EnumItem`, `Animation`, `CFrame`. Critically, this view does not show memory usage within the engine itself, only the Luau VM.
|
||||
- **Unique References** and **Unparented Instances** — Shows counts and total numbers of instances for **unique references** or **all remaining references** that don't have a parent in the data model and are only reachable by scripts. Also shows all paths that pin the instance object.
|
||||
|
||||
#### Graph
|
||||
|
||||
The **Graph** view is the most detailed and complex view among all Luau heap views. It shows an aggregated memory usage tree with each node representing an object with memory allocated. The tree shows how objects connect to each other and derives the shortest path between object references. It has the following columns of memory size:
|
||||
|
||||
- Size — The self memory usage plus the memory usage by contents within the data structure.
|
||||
- Self — The memory directly allocated for the data structure itself, excluding the memory usage by any content it contains.
|
||||
|
||||
<Alert severity="info">
|
||||
The graph view displays elements smaller than 2 KB as a single `…` node.
|
||||
</Alert>
|
||||
|
||||
<img src="../../assets/studio/console/Graph-View.jpeg" width="800" alt="An example Graph view" />
|
||||
|
||||
The root of the tree graph is `registry`, which stores all engine and Luau references, such as functions connected to signals or the task library, tables returned by module scripts, and global functions, tables and classes. It usually parents the following common entries:
|
||||
|
||||
- `Module @Path.To.Module` is the table returned by a module script.
|
||||
- `name:123 =Path.To.Module` is a function inside a specified script. Anonymous functions don't have names. The top level node often refers to the global script function. Example: `:1= Workspace.[Username].Animate`.
|
||||
- `upvalue` is a reference for captured functions. See [Capture local scope](../../luau/scope.md#capture) for more information.
|
||||
- `env` refers to the environment of a function. For most cases, it's a table representing the global scope of a script.
|
||||
- `globals` refers to the environment of a thread.
|
||||
- `[key]` represents objects that serve as table keys.
|
||||
- `array` represents an array.
|
||||
- `stack` refers to the array that stores all function locals.
|
||||
- `constants` represents all constant values that functions use.
|
||||
|
||||
#### Memory categories
|
||||
|
||||
The **Memory Categories** view shows memory sizes and counts by memory categories, which the engine assigns to objects at allocation time. By default, the memory category has the same name as the script, or you can assign custom memory category names using the `debug.setmemorycategory` function.
|
||||
|
||||
#### Unique references and unparented instances
|
||||
|
||||
The **Unique References** and **Unparented Instances** views are related. Both show memory usage of instances that don't have a parent in the data model and are only reachable by scripts, along with all paths that pin the instance object. If an instance is only referenced within Luau scripts, it appears under **Unique References**. Otherwise, it's also in use by Roblox systems and appears under **Unparented Instances**. Both views show two metrics:
|
||||
|
||||
- **Count** — The number of instances with the same name that are reachable from the same path, such as multiple instances named `Dragon` in the same table.
|
||||
- **Total Instances** — The total number of objects inside those roots, such as all parts, scripts, and sound objects that construct a `Dragon` instance.
|
||||
|
||||
<img src="../../assets/studio/console/Unique-Reference-View.jpeg" width="800" alt="An example Unique Reference view" />
|
||||
|
||||
These views are useful for identifying unnecessary connected instances, which you need to disconnect when you no longer need them. If you see many unexpected instances in this view, check out the paths holding them and evaluate whether they are necessary.
|
||||
169
.cursor/rules/roblox/en-us/studio/optimization/scriptprofiler.md
Normal file
169
.cursor/rules/roblox/en-us/studio/optimization/scriptprofiler.md
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
---
|
||||
title: Script Profiler
|
||||
description: Script Profiler is a tool within the Developer Console that records profiling sessions of all running scripts.
|
||||
---
|
||||
|
||||
**Script Profiler** is a tool within the [Developer Console](../../studio/developer-console.md) that allows you to record profiling sessions of all running scripts and view their CPU time costs with custom recording and display settings. It can record all types of function calls, including Luau functions, method calls, and property accesses. This tool is helpful for identifying scripts that take up the most CPU resources and slow down the performance.
|
||||
|
||||
<Alert severity="info">
|
||||
Script Profiler only records function calls that consume CPU resources, so it doesn't record threads that sleep or wait for results.
|
||||
</Alert>
|
||||
|
||||
## Record profiling sessions
|
||||
|
||||
Before recording, you need to select the recording environment from:
|
||||
|
||||
- **Client** (Default) — Records client-side scripts, including `Class.LocalScript|LocalScripts` and `Class.Script|Scripts` with `Class.BaseScript.RunContext|RunContext` set to `Enum.RunContext.Client|Client`.
|
||||
- **Server** — Records server-side scripts, including `Class.Script|Scripts` with `Class.BaseScript.RunContext|RunContext` set to `Enum.RunContext.Server|Server` or `Enum.RunContext.Legacy|Legacy`. Script Profiler clears all collected server-side data at the end of each session.
|
||||
|
||||
You can also set the following recording options:
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Behavior</th>
|
||||
<th>Options</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Frequency</td>
|
||||
<td>1000 times per second (1 KHz)<br></br>10,000 times per second (10 KHz)</td>
|
||||
<td>1 KHz</td>
|
||||
<td>The 10 KHz frequency has higher precision, as Script Profiler might not pick up API calls that execute more frequently than your selected frequency, but it also has a higher performance cost.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Session Length</td>
|
||||
<td>1-minute<br></br>5-minute<br></br>10-minute<br></br>Manual</td>
|
||||
<td>Manual</td>
|
||||
<td>The manual option requires you to stop recording manually.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Live Polling Behavior</td>
|
||||
<td>On<br></br>Off</td>
|
||||
<td>Off</td>
|
||||
<td>This behavior polls and refreshes profiling data each second during a profiling session.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
To record a new profiling session:
|
||||
|
||||
1. Open [Developer Console](../../studio/developer-console.md#opening-the-developer-console).
|
||||
2. Expand the tools dropdown to select **ScriptProfiler**.
|
||||
|
||||
<img src="../../assets/studio/console/ScriptProfiler-Open.png" width="200" alt="Dropdown menu of all Developer Console tools with the ScriptProfiler option highlighted for selection." />
|
||||
|
||||
3. Expand the client-server dropdown to select **Client** or **Server**.
|
||||
|
||||
<img src="../../assets/studio/console/Client-Server-Dropdown.png" width="600" alt="Dropdown menu with Client and Server options for selection." />
|
||||
4. (Optional) Check the **Live** checkbox to enable the live polling behavior.
|
||||
5. (Optional) Select **Freq** and **Time** to choose the recording frequency and session time length if you don't want to use the default values.
|
||||
6. Click **Start** to begin the profiling session. If you set a duration, Script Profiler displays a countdown timer with the remaining time in the session.
|
||||
7. Click **Stop** or wait until the recording finishes to display the profiling data.
|
||||
|
||||
## Read profiling data
|
||||
|
||||
After a session stops, Script Profiler generates a table showing how much time each function call costs in CPU time. The table sorts function calls from the most-time-spent to least-time-spent, and allows you to search for specific functions by their name. It provides the following two views:
|
||||
|
||||
- **Callgraph** (Default): Categorizes and displays function calls into a tree structure based on frame tasks. This view displays each task category as nodes under the same root and allows you to expand them to view functions. You can also hover over any node in the tree to view file and line information. For example, **Stepped/CameraInput/<anonymous>** might reveal `Players.[LocalPlayer].PlayerScripts.PlayerModule.CameraModule.CameraInput:125`.
|
||||
<img src="../../assets/studio/console/Callgraph.jpeg" width="800" alt="Example callgraph view of a profiling session." />
|
||||
- **Functions**: Lists all functions without categorizing them by tasks.
|
||||
<img src="../../assets/studio/console/Functions.jpeg" width="800" alt="Example functions view of a profiling session." />
|
||||
|
||||
You can also select from the following display options to tailor your debugging needs:
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Options</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Unit</td>
|
||||
<td>Milliseconds (ms)<br></br>Percentage (%)</td>
|
||||
<td>ms</td>
|
||||
<td>Displays time spent on each API call in milliseconds or percentages of the total recording session.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Average</td>
|
||||
<td>Off<br></br>1-second<br></br>1-minute<br></br>5-minute<br></br>10-minute</td>
|
||||
<td>Off</td>
|
||||
<td>Calculates the average time spent on each API call by the selected value. If you select an option that is longer than the session length, Script profiler extrapolates the session length to calculate the average. For example, you can select the 5-minute option for a 1-minute session to see the expected average value if you run the code for 5 minutes.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Export profiling data
|
||||
|
||||
Script Profiler allows you to export recorded profiling data as a JSON file. To export recorded data after a profiling session:
|
||||
|
||||
1. On the Script Profiler window, click **Export**.
|
||||
2. On the export window, select the profiling session that you want to export. Rename the default file name if you want to set a custom name.
|
||||
3. Click **Export** to save the JSON file.
|
||||
|
||||
<img src="../../assets/studio/console/Export-Window.jpeg" width="600" alt="Example export window." />
|
||||
|
||||
The exported JSON file includes the following fields:
|
||||
|
||||
- **Version**: The version number.
|
||||
- **SessionStartTime**: A timestamp in milliseconds that records the session start time.
|
||||
- **SessionEndTime**: A timestamp in milliseconds that records the session end time.
|
||||
- **Categories**: An array of frame task categories recorded in the profiling session. Each entry includes:
|
||||
- **Name**: The name of each frame task category.
|
||||
- **NodeId**: The unique identifier of a task category (node). It's a 1-based index into the `Nodes` array. For example, you can look up the node with the `NodeId` of `123` by retrieving the 123rd element in `Nodes`.
|
||||
- **Nodes**: An array of nodes recorded in the profiling session. Each entry includes:
|
||||
- **TotalDuration**: The amount of time that the node costs in CPU time in microseconds.
|
||||
- **FunctionIds**: An array of unique identifiers of functions.
|
||||
- **NodeIds**: An array of Node IDs.
|
||||
- **Functions**: An array of functions recorded in the profiling session.
|
||||
- **TotalDuration**: The amount of time that the function costs in CPU time in microseconds.
|
||||
- **Name**: The name of the function, if available.
|
||||
- **Source**: The source of the function, if available.
|
||||
- **Line**: The line number of the function, if available.
|
||||
- **Flags**: A bit field that indicates any specific function execution environment. Currently can have the following values:
|
||||
- `0`: The 0th bit represents `IsNative` for execution under Native CodeGen.
|
||||
- `1`: The 1 th bit represents `IsPlugin` for execution as part of a plugin.
|
||||
|
||||
```json title="Example Exported Profiling Data"
|
||||
{
|
||||
"Version":2,
|
||||
"SessionStartTime":1704850750514,
|
||||
"SessionEndTime":1704850751198,
|
||||
"Categories":
|
||||
[
|
||||
{"Name":"Parallel Luau","NodeId":4},
|
||||
{"Name":"Heartbeat","NodeId":1}
|
||||
],
|
||||
"Nodes":
|
||||
[
|
||||
{"TotalDuration":2530,"FunctionIds":[1],"NodeIds":[2]},
|
||||
{"TotalDuration":2530,"FunctionIds":[2,5],"NodeIds":[3,7]},
|
||||
{"TotalDuration":1267},
|
||||
{"TotalDuration":7746,"FunctionIds":[3],"NodeIds":[5]},
|
||||
{"TotalDuration":7746,"FunctionIds":[4],"NodeIds":[6]},
|
||||
{"TotalDuration":7746},
|
||||
{"TotalDuration":1263,"FunctionIds":[6],"NodeIds":[8]},
|
||||
{"TotalDuration":1263,"FunctionIds":[7],"NodeIds":[9]},
|
||||
{"TotalDuration":1263,"FunctionIds":[8],"NodeIds":[10]},
|
||||
{"TotalDuration":1263}
|
||||
],
|
||||
"Functions":
|
||||
[
|
||||
{"Name":"main","TotalDuration":2530},
|
||||
{"Source":"builtin_ManageCollaborators.rbxm.ManageCollaborators.Packages._Index.roblox_rodux-3.0.0.rodux.Store","Line":81,"TotalDuration":1267},
|
||||
{"Name":"Script","TotalDuration":7746},
|
||||
{"Source":"Workspace.Actor.Script","Line":1,"TotalDuration":7746},
|
||||
{"Source":"builtin_DeveloperInspector.rbxm.DeveloperInspector.Packages._Index.DeveloperFramework.DeveloperFramework.UI.Components.Grid","Line":221,"TotalDuration":1263},
|
||||
{"Source":"builtin_DeveloperInspector.rbxm.DeveloperInspector.Packages._Index.DeveloperFramework.DeveloperFramework.UI.Components.Grid","Name":"_update","Line":236,"TotalDuration":1263},
|
||||
{"Source":"builtin_DeveloperInspector.rbxm.DeveloperInspector.Packages._Index.DeveloperFramework.DeveloperFramework.UI.Components.Grid","Name":"_getRange","Line":277,"TotalDuration":1263},
|
||||
{"Source":"[C]","Name":"ScrollingFrame.CanvasPosition","TotalDuration":1263}
|
||||
]
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue