Move debugging into a Debugging and Optimization section, and document the Inspector's Performance tab

docs/user-manual/scripting/debugging/browser-dev-tools.md → docs/user-manual/debugging/browser-dev-tools.md

@@ -11,11 +11,11 @@ Chrome, Firefox and other browsers have Developer Tools integrated directly into
 
 In order to debug your scripts, select the Sources tab in Developer Tools (Chrome). Open the 'navigator' by clicking the icon in the top left corner of the Sources pane. You should see something similar to what is shown below:
 
-![Debugger](/img/user-manual/scripting/debugging/chrome-debugger.png)
+![Debugger](/img/user-manual/debugging/chrome-debugger.png)
 
 In Firefox it looks like this:
 
-![Firefox](/img/user-manual/scripting/debugging/firefox-debugger.png)
+![Firefox](/img/user-manual/debugging/firefox-debugger.png)
 
 The navigator lists all of the scripts currently running in the active tab, including any PlayCanvas scripts that you have written. Find one of your scripts in the navigator and select it to open the source code. You are now able to set breakpoints and debug.
 

docs/user-manual/scripting/debugging/index.md → docs/user-manual/debugging/index.md

@@ -1,9 +1,9 @@
 ---
 title: Debugging
-description: Tools and techniques for finding and fixing bugs in your PlayCanvas scripts using browser developer tools.
+description: Tools and techniques for finding and fixing bugs in PlayCanvas applications, with logging, the browser developer tools, the Inspector and debug drawing.
 ---
 
-Debugging is essential for identifying and fixing issues in your PlayCanvas scripts. When your code doesn't behave as expected, these tools and techniques will help you quickly find and resolve problems.
+Debugging is essential for identifying and fixing issues in your PlayCanvas application, in its scripts as well as in what it renders and loads. When it doesn't behave as expected, these tools and techniques will help you quickly find and resolve problems. To find out why it runs slowly, see [Which Tool to Use](/user-manual/optimization/#which-tool-to-use).
 
 ## Debugging Techniques
 
@@ -24,3 +24,9 @@ Use breakpoints, step-through debugging, and performance profiling to deeply ins
 Look inside the running application: its entities and components, cameras, assets and GPU resources, the passes of each frame, and the draws of a pass one at a time.
 
 **[Learn the Inspector →](./inspector.md)**
+
+### Debug Drawing
+
+Draw lines, shapes and textures over the scene to see what your code computes, such as bounds and directions, or the content of a render target and the depth of the scene.
+
+**[Learn Debug Drawing →](/user-manual/graphics/debug-drawing/)**

docs/user-manual/scripting/debugging/inspector.md → docs/user-manual/debugging/inspector.md

@@ -1,18 +1,19 @@
 ---
 title: Inspector
-description: Inspect a running PlayCanvas application in a debug panel - its entities, cameras, assets, frame graph, GPU resources, scripts and shaders - and step through the draws of a frame.
+description: Inspect a running PlayCanvas application in a debug panel - its entities, cameras, assets, frame graph, GPU resources, scripts and shaders - step through the draws of a frame, and record its performance.
 ---
 
 The Inspector is a debug panel for a running PlayCanvas application. It docks over the canvas and shows the application's scene, GPU resources and rendered frames as they are now, with the properties of whatever you select updating live below.
 
-<img loading="lazy" alt="The Inspector panel docked beside a running application, with an entity selected in the hierarchy" width="800" src="/img/user-manual/scripting/debugging/inspector/inspector.png" />
+<img loading="lazy" alt="The Inspector panel docked beside a running application, with an entity selected in the hierarchy" width="800" src="/img/user-manual/debugging/inspector/inspector.png" />
 
 Use it to answer questions such as:
 
 - Why does an entity not show up, and what are its components set to right now?
 - Which material and shader does a mesh draw with, and which textures does it use?
 - What does a frame render, in which passes and in what order?
 - Where does the video memory go?
+- Which frames are slow, and what holds them back?
 
 The Inspector only reads the application. The changes it makes are the ones you ask for: turning entities on and off, pausing and stepping the application, and view-only overrides (render modes, wireframe and a flown or orbited camera), which it removes when it closes.
 
@@ -56,6 +57,7 @@ app.root.addChild(entity);
 | `toggleKey` | `` 'Backquote' `` | The key that shows and hides the panel. |
 | `pauseKey` | `'F9'` | The key that pauses and resumes the application. |
 | `stepKey` | `'F10'` | The key that advances one frame while paused. |
+| `record` | `false` | Whether to start recording frames on the Performance tab. Created before the application's first frame, the Inspector records its start too, see [Recording the Start of the Application](/user-manual/optimization/inspector-performance/#recording-the-start-of-the-application). |
 | `storageKey` | `'pc-inspector'` | The local storage key the panel's settings are kept under, such as the active tab and the panel width. `null` keeps nothing. |
 
 ## The Toolbar
@@ -82,6 +84,7 @@ Each tab lists one kind of object, and the property view below it shows the sele
 | **Cameras** | The cameras in render order, with where each draws. A render mode shows the scene's material inputs instead of the final image, such as albedo, world normals or lighting, for one camera or all of them, and the scene can be drawn in wireframe. |
 | **Assets** | Every asset in the registry, with its file, its load state and what uses it. |
 | **Frame graph** | The passes that rendered the last frame, in order, with the layers, draws and render targets of each. **GPU timings** shows the time each pass takes on the GPU where the device can measure it, **Freeze** keeps showing the current frame while the application runs on, and **Preview** draws the selected pass's render target over the view. |
+| **Performance** | Records the frames of the application and charts their frame, CPU, GPU and script times, what loaded, memory and resources over time, with each frame on a timeline of its own. See [Inspector Performance](/user-manual/optimization/inspector-performance/). |
 | **Render targets** | The render targets on the device, with the passes that rendered into them and a live preview of a chosen attachment. |
 | **Textures** | The textures on the device, largest first, with a live preview and a choice of channels to show. |
 | **Meshes** | The meshes of the application, largest first, with their geometry and what uses them. |
@@ -91,7 +94,7 @@ Each tab lists one kind of object, and the property view below it shows the sele
 | **Shaders** | The compiled shaders, with their sources. |
 | **Physics** | The rigid bodies and joints of the physics world, and an option to draw the world over the scene. |
 
-<img loading="lazy" alt="The Frame graph tab, with the forward pass selected and its render target previewed over the view" width="800" src="/img/user-manual/scripting/debugging/inspector/frame-graph.png" />
+<img loading="lazy" alt="The Frame graph tab, with the forward pass selected and its render target previewed over the view" width="800" src="/img/user-manual/debugging/inspector/frame-graph.png" />
 
 ## Stepping Through a Frame
 
@@ -102,7 +105,7 @@ The Frame graph tab can draw a frame one draw call at a time, to see how the ima
 3. Press the Up and Down arrow keys to step back and forward one draw at a time. The property view lists the drawn mesh instances with the current one highlighted, the view outlines it, and the status bar shows its number, such as *draw 8 of 12 · World opaque*. Expand an entry to see more about it, such as its mesh and material.
 4. Turn off **Debug frame** to draw the full frame again.
 
-<img loading="lazy" alt="Stepping through the draws of the World layer one at a time" width="800" src="/img/user-manual/scripting/debugging/inspector/debug-frame.webp" />
+<img loading="lazy" alt="Stepping through the draws of the World layer one at a time" width="800" src="/img/user-manual/debugging/inspector/debug-frame.webp" />
 
 :::note
 Stepping through draws needs the debug build of the engine, and the option is disabled with other builds. Bundlers such as Vite pick the debug build in development through the `development` export condition of the `playcanvas` package.

docs/user-manual/getting-started/migrating-from-unity.md

@@ -52,7 +52,7 @@ The Launch Page stays connected to the Editor. Changes to entities, components,
 
 Scripts never run in the Editor's viewport, so there is nothing like Unity's `[ExecuteInEditMode]`: anything a script creates or changes appears only in the launched app.
 
-The Launch button's menu has options for testing: choose the graphics API, open the [Profiler](/user-manual/optimization/profiler/), [MiniStats](/user-manual/optimization/mini-stats/) or [Inspector](/user-manual/scripting/debugging/inspector/), and tick **Debug** to log the engine's warnings and errors to the console.
+The Launch button's menu has options for testing: choose the graphics API, open the [Profiler](/user-manual/optimization/profiler/), [MiniStats](/user-manual/optimization/mini-stats/) or [Inspector](/user-manual/debugging/inspector/), and tick **Debug** to log the engine's warnings and errors to the console.
 
 ### Navigating the Viewport {#navigating-the-viewport}
 
@@ -641,11 +641,11 @@ Your app runs in the browser, so you debug it with the browser's developer tools
 
 | Unity | PlayCanvas |
 | --- | --- |
-| Console window | The **Console** tab of the developer tools. See [Console Logging](/user-manual/scripting/debugging/console-logging/). |
-| Attaching Visual Studio or Rider | Breakpoints in the **Sources** tab of the developer tools. See [Browser Dev Tools](/user-manual/scripting/debugging/browser-dev-tools/). |
+| Console window | The **Console** tab of the developer tools. See [Console Logging](/user-manual/debugging/console-logging/). |
+| Attaching Visual Studio or Rider | Breakpoints in the **Sources** tab of the developer tools. See [Browser Dev Tools](/user-manual/debugging/browser-dev-tools/). |
 | `Debug.Break()` | A `debugger;` statement, which pauses the app while the developer tools are open |
 | Profiler | The [Profiler](/user-manual/optimization/profiler/) and [MiniStats](/user-manual/optimization/mini-stats/), from the Launch button's menu, and the **Performance** tab of the developer tools |
-| Frame Debugger | The [Inspector](/user-manual/scripting/debugging/inspector/), also from the Launch button's menu, which shows the render passes and draw calls of each frame, and [native GPU profilers](/user-manual/optimization/gpu-profiling/) |
+| Frame Debugger | The [Inspector](/user-manual/debugging/inspector/), also from the Launch button's menu, which shows the render passes and draw calls of each frame, and [native GPU profilers](/user-manual/optimization/gpu-profiling/) |
 | `Debug.DrawLine` and Gizmos | `this.app.drawLine()`, and [`WireRenderer`](/user-manual/graphics/debug-drawing/) for spheres, boxes and other shapes |
 
 ## Version Control and Collaboration {#version-control-and-collaboration}

docs/user-manual/getting-started/start-with-create-playcanvas.md

@@ -85,7 +85,7 @@ To publish an Editor project as a Web Lens instead, see [Snapchat Web Lenses](/u
 
 ## Debug with the Inspector
 
-The development server loads the [Inspector](/user-manual/scripting/debugging/inspector/) for the running application. Press the backquote key (`` ` ``) to show or hide it, <kbd>F9</kbd> to pause, and <kbd>F10</kbd> to step one frame. Production builds do not include the Inspector.
+The development server loads the [Inspector](/user-manual/debugging/inspector/) for the running application. Press the backquote key (`` ` ``) to show or hide it, <kbd>F9</kbd> to pause, and <kbd>F10</kbd> to step one frame. Production builds do not include the Inspector.
 
 ## Skip the Prompts
 

docs/user-manual/optimization/index.md

@@ -1,8 +1,26 @@
 ---
-title: Optimization
-description: Why and how to optimize load time, frame rate, CPU, GPU load, and memory in PlayCanvas applications.
+title: Debugging and Optimization
+description: Tools for finding bugs and performance problems in PlayCanvas applications, and why and how to optimize load time, frame rate, CPU and GPU load, and memory.
 ---
 
+This section covers the tools for looking inside a running PlayCanvas application, to find out why it does not behave as expected or does not perform as it should, and the ways of making it load and run faster.
+
+## Which Tool to Use {#which-tool-to-use}
+
+| To find out | Use |
+| ----------- | --- |
+| What your code does, and where it goes wrong | [Console Logging](/user-manual/debugging/console-logging/) and the [Browser Dev Tools](/user-manual/debugging/browser-dev-tools/) |
+| What the application holds: its entities and components, cameras, assets and GPU resources | The [Inspector](/user-manual/debugging/inspector/) |
+| How a frame renders, pass by pass and draw by draw | The Frame graph tab of the [Inspector](/user-manual/debugging/inspector/), and [stepping through a frame](/user-manual/debugging/inspector/#stepping-through-a-frame) |
+| What your code computes in the scene, such as bounds, directions or the content of a render target | [Debug Drawing](/user-manual/graphics/debug-drawing/) |
+| Whether the application keeps its frame rate as you use it | [MiniStats](/user-manual/optimization/mini-stats/) |
+| Which frames are slow, and what holds them back: the CPU, the GPU, scripts or loading | The [Performance tab of the Inspector](/user-manual/optimization/inspector-performance/) |
+| How long the application takes to start, and what loads when | The [Performance tab of the Inspector](/user-manual/optimization/inspector-performance/#recording-the-start-of-the-application), or the [Editor Profiler](/user-manual/optimization/profiler/) |
+| The statistics of the engine from code, for dashboards and automated comparisons | [Profiling with AppStats](/user-manual/optimization/app-stats/) |
+| What the GPU does within a frame, in detail | [GPU Profiling](/user-manual/optimization/gpu-profiling/) with the native GPU tools |
+
+## Optimization
+
 Optimization is a critical part of developing a PlayCanvas application. It can mean the difference between a great user experience and a terrible one.
 
 :::tip
@@ -20,17 +38,9 @@ Let's begin by establishing the key goals for optimization and highlight why eac
 | 🔋 Minimize CPU and GPU load | Just because your app maintains 60 frames per second does not mean your work is done. Reducing processor load preserves battery power and keeps devices running cool. |
 | 🧠 Minimize memory utilization | Browsers allocate a limited pool of memory to applications. Once this pool is exhausted, the tab will crash and reload. Your users will be upset! |
 
-## Measure Before Optimizing
-
-Choose a repeatable scene or interaction, record a baseline on the target device, then measure each change under the same conditions.
+### Measure Before Optimizing {#measure-before-optimizing}
 
-| Tool | Use it for |
-| ---- | ---------- |
-| [MiniStats](/user-manual/optimization/mini-stats/) | Watching frame time, CPU/GPU costs and GPU resource memory while interacting with the application. |
-| [Profiling with AppStats](/user-manual/optimization/app-stats/) | Reading public statistics from code and collecting reports for dashboards, agents and automated comparisons. |
-| [Editor Profiler](/user-manual/optimization/profiler/) | Inspecting the Editor Launch profiler, including asset loading and shader compilation timelines. |
-| [GPU Profiling](/user-manual/optimization/gpu-profiling/) | Capturing frames with native GPU tools for detailed rendering investigations. |
-| [Inspector](/user-manual/scripting/debugging/inspector/) | Finding where video memory goes, which passes and draws a frame makes, and what each mesh and material uses, in the running application. |
+Choose a repeatable scene or interaction, record a baseline on the target device, then measure each change under the same conditions, with the profiling tools in [Which Tool to Use](#which-tool-to-use). The [guidelines](/user-manual/optimization/guidelines/) and the pages after them describe what to change.
 
 :::ai
 Give an AI assistant a performance goal, repeatable scenario and baseline reports from **[AppStats](/user-manual/optimization/app-stats/#collecting-periodic-reports)**. It can combine these with MiniStats or browser evidence and propose one measurable change at a time. Use the **[Editor MCP Server](/user-manual/editor/mcp-server/)** to replay Editor input or follow **[Developing with AI](/user-manual/engine/developing-with-ai/)** for standalone projects.