
<img src="/img/tools/ACE/overview.jpg" title="Babylon.js Animation Curve Editor"/>

## Easily Create Animations

Introduced in Babylon.js 5.0, the Animation Curve Editor (ACE for short) is a powerful tool that allows you to create and modify animations in a simple, fun, and intuitive editor.

This document will walk you through the editor and all of its capabilities. If you're not already familiar with the Animation system in Babylon.js, you might want to brush up on it here: [Babylon Animation Documentation](/features/featuresDeepDive/animation)

To start, check out this awesome video overview of ACE.

<Youtube id="IRP5PVMxth0"/>

## How to access ACE

You can access ACE in 2 different ways:

The first method is to select an existing object in the inspector, find the 'Animations' portion of the properties window, and select the 'Edit' button.

<img src="/img/tools/ACE/object.jpg" title="Loading animation from an object."/>

The second method can happen if an animation exists in the scene separate from an object. This most often happens when loading an asset into the scene that has attached animations to it, such as in this playground:

<Playground id="#C21DGD#2" title="Loaded Animation Example" description="Simple example of animations loaded into a scene from a .glb file."/>

In this method you select an individual animation in the Inspector and then hit the 'Edit' Button in the properties window for that animation.

<img src="/img/tools/ACE/animation.jpg" title="Loading animation from an existing animation."/>

## Getting Familiar With The Layout

Let's start by familiarizing ourselves with different parts of ACE.

### Menu

<img src="/img/tools/ACE/menu.jpg" title="ACE Menu"/>

The Menu offers you the ability to create a new animation, load an animation from the snipper server or from a local file, save animation locally or to the snippet server, edit an animation, and change the playback framerate of an animation.

#### Creating a new animation

<img src="/img/tools/ACE/create.jpg" title="Create Button"/>

Pressing the Create tab will display a menu that allows you to create a new animation. 

<img src="/img/tools/ACE/createMenu.jpg" title="Create Menu"/>

- Display Name: You can enter a name for your new animation.
- Mode: This allows you to choose between a `List` of animatable properties OR specify a `Custom` attribute.
- Property: The list of available animatable properties if Mode is set to `List`, or a text field if Mode is set to `Custom`.
- Type: The type of underlying Babylon Property that will be animated.
- Loop Mode: The desired loop mode for the new animation, `Cylce`, `Relative`, or `Constant`.

#### Loading An Animation

<img src="/img/tools/ACE/load.jpg" title="Load Button"/>

Pressing the load tab will display a menu that allows you to load an animation from the Babylon.js snippet server or from a local file.

<img src="/img/tools/ACE/loadMenu.jpg" title="Load Menu"/>

#### Saving An Animation

<img src="/img/tools/ACE/save.jpg" title="Save Button"/>

Pressing the save tab will display a menu that allows you to save an animation to the Babylon.js snippet server or to a local file.

After saving to the snippet server, the assigned Snippet ID for your animation will be listed at the bottom of this menu.

<img src="/img/tools/ACE/saveMenu.jpg" title="Save Menu"/>

Also see [Using Saved Animations in the Playground](#using-saved-animations-in-the-playground)

#### Editing An Animation

<img src="/img/tools/ACE/edit.jpg" title="Edit Button"/>

Pressing the edit tab will display a list of all properties with animations applied to them. Note that if you have entered ACE by selecting the edit button of Babylon Object (Method 1 listed above), then this menu will display ALL properties of the selected object that have animations attached to them.

<img src="/img/tools/ACE/editMenu.jpg" title="Edit Menu"/>

#### Changing the Playback Framerate

<img src="/img/tools/ACE/fps.jpg" title="FPS Field"/>

The fps (frames per second) field allows you to specify the playback rate of the animations.

### Key Controls

<img src="/img/tools/ACE/keyControls.jpg" title="ACE Key Controls"/>

The Key Controls offer the ability to change the frame of a key, the value of a key, set a new key(s), reframe the keys, flatten the key's tangents, create linear tangents for a key, break a key's tangents, unify a key's tangents, and create a step tangent for a key.

#### Changing the Frame of a Key

<img src="/img/tools/ACE/keyFrame.jpg" title="Key Frame Field"/>

With a single key selected, this input box allows you to enter a new frame number for the selected key to occupy.

#### Changing the Value of a Key

<img src="/img/tools/ACE/keyValue.jpg" title="Key Value Field"/>

With a single key selected, this input box allows you to enter a new value for the selected key.

#### Create a New Key

<img src="/img/tools/ACE/newKey.jpg" title="New Key"/>

This button creates a new key at the location of the play head. If the animations being edited are connected to an object (entered ACE through method 1 above), the new key button will grab the existing value for that property from the object in the scene. For example, if you have loaded a sphere and are editing the Position Vector3 property of that object, when selecting the new key button, the x, y, and z values for the newly created keys will come from the sphere's current position in the connected Babylon scene. Otherwise if there is no connected object to the current animation, the value of the newly created key(s) will be zero.

#### Framing the Canvas

<img src="/img/tools/ACE/frameCanvas.jpg" title="Frame Cavnas"/>

The Frame Canvas button will resize the canvas to neatly fit all keys in the animation into the canvas size. This makes it much easier to see the animation in its entirety.

#### Flattening a Key's Tangents

<img src="/img/tools/ACE/flattenTangents.jpg" title="Flatten Tangents"/>

With a key(s) selected, the flatten tangents button will flatten the tangents coming into and going out of the key.

#### Creating Linear Key Tangents

<img src="/img/tools/ACE/linearTangents.jpg" title="Linear Tangents"/>

With a key(s) selected, the linear tangents button will create linear tangents coming into and going out of the key.

#### Breaking a Key's Tangents

<img src="/img/tools/ACE/brokenTangents.jpg" title="Broken Tangents"/>

With a key(s) selected, the break tangents button will separate the incoming and outgoing tangents of a key so they can be individually manipulated.

#### Unifying a Key's Tangents

<img src="/img/tools/ACE/unifyTangents.jpg" title="Unified Tangents"/>

With a key(s) selected, the unify tangents button will unite the incoming and outgoing tangents of a key so they can be manipulated together.

#### Stepping a Key's Tangents

<img src="/img/tools/ACE/stepTangents.jpg" title="Step Tangents"/>

With a key(s) selected, the step tangents button will create a flat incoming and outgoing tangent relative to the previous and following key. This is useful when blocking out positions or poses common in the animation process. You can think of stepped tangents as a series of static positions with no computer interpolation between them.

### Canvas

<img src="/img/tools/ACE/canvas.jpg" title="ACE Canvas"/>

The Canvas is the main `play` area in ACE. This is where you manipulate curves and keys to create the perfect animations.

Let's go over some handy things to know about how to work in the Canvas.

#### Working with Keys

The Canvas will display all curves for any property that is selected in the Edit Menu. In other words, selecting specific properties in the Edit Menu will isolate the canvas to showing only those selected properties.

You can select a key by either left clicking on a key or by clicking and dragging over a key.

You can also select multiple keys at one time by clicking and dragging across as many keys as you like.

All keys can be selected by using CTRL + A.

Once a key is selected, you can manipulate the tangent handles of the key by left clicking on one of the handles.

If you hold down the SHIFT key and left click on a key and drag your mouse vertically up and down, the key will be locked from moving horizontally. This allows you to easily change the value of a key without changing the frame the key occupies.

Similarly, if you hold down the SHIFT key and left click on a key and drag your mouse horizontally left and right, the key will be locked from moving vertically. This allows you to easily change the frame number that a key occupies without changing the value of the key.

#### Navigation

Holding down the ALT key and left clicking and dragging on the canvas will pan the canvas around. A middle mouse button can also be used to accomplish the same thing.

You can use the scroll wheel on your mouse to zoom in and out.

The Play Head hovers above the active frame number of the animation. New keys will be inserted in the animation curve at the location of the Play Head. The Play Head can be changed in a number of different ways, by left clicking and dragging it left or right, by manually typing a number in the playhead box, or by using the Play Controls.

### Play Controls

<img src="/img/tools/ACE/playControls.jpg" title="ACE Play Controls"/>

The play controls offer easy options to navigate through the timeline.

#### First and Last Frames

<img src="/img/tools/ACE/firstLast.jpg" title="First Last Frames"/>

The first and last frame buttons will move the Play Head to the first and last frames respectively.

#### Previous and Next Frames

<img src="/img/tools/ACE/previousNext.jpg" title="Previous Next Frames"/>

The previous and next frame buttons will move the Play Head to the previous or next frame respectively. You can also use the `left` and `right` arrow keys to advance forward or back one frame as well.

#### Previous and Next Keys

<img src="/img/tools/ACE/prevKeyNextKey.jpg" title="Previous Next Key"/>

The previous and next Key buttons will move the Play Head to the previous or next key respectively. You can also use the `up` and `down` arrow keys to advance forward or back one key as well.

#### Playing an Animation

<img src="/img/tools/ACE/playButtons.jpg" title="Play Buttons"/>

The play forward and backwards buttons will play the animation forward or backward respectively, at the specified framerate (fps) in the Edit Menu. The play buttons will play from the starting frame of the play range to the ending frame of the play range. You can also use the `spacebar` key to play the animation in the forward direction. There is no hotkey to play the animation in the reverse direction, because we are not animals.

### Play Range

<img src="/img/tools/ACE/playRange.jpg" title="ACE Play Range"/>

The Play Range represents the starting and ending frames when you use one of the play buttons. These buttons allow you to play a subset of an entire animation.

## Using Saved Animations in the Playground

It is very easy to load your saved GUIs into your Babylon.js Scene and modify them. Here are a few handy examples:

### Load From The Snippet Server
You can load an animation into your Babylon scene from the snippet server like this:

```javascript
let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, segments: 32}, scene);
let animations = await BABYLON.Animation.CreateFromSnippetAsync('YOUR SNIPPET ID');
sphere.animations = animations;
scene.beginAnimation(sphere, 0, 100, true);
```

<Playground id="#YAWBMY" title="Loaded Animation From Snippet" description="Simple example of loading an animation from the snippet server."/>

### Load From .JSON Object
You can load an Animation into your Babylon scene from a saved .JSON object like this:

```javascript
let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, segments: 32}, scene);
let animations = await BABYLON.Animation.ParseFromFileAsync(null, "https://doc.babylonjs.com/examples/animations.json");
sphere.animations = animations;
scene.beginAnimation(sphere, 0, 100, true);
```

<Playground id="#YAWBMY#7" title="Loaded Animation From .JSON" description="Simple example of loading an animation from a saved .JSON object."/>

### The Magic Loop
As with all Babylon tools, if you've loaded an animation from the snippet server into your scene and then use the GUI Editor to edit that animation. Once you save a new version of that animation, the tool will automatically change the snippet server load line to use your newly created Snippet ID! If you haven't tried this out, you need to, it's awesome!

## Creating Animations With ACE

Now that you've learned all about ACE, let's take a quick minute to go over the most common flow of how to use this awesome tool to create animations for an object in your Babylon.js scene.

Let's start with the basic [playground.](https://playground.babylonjs.com/)

- Step 1 - Open the Inspector
- Step 2 - Select an object in the Inspector that you'd like to animate. Let's use the sphere for this example.
- Step 3 - Scroll down in the properties window of the Inspector until you find the Animation group. Click the `Edit` button.
- Step 4 - With ACE loaded, press the `Add New Animation` button.
- Step 5 - Fill out the Display Name and choose what property you'd like to animate. Set the loop mode to your preference.
- Step 6 - Make an animation.
- Step 7 - Save your animation to the Snippet Server.
- Step 8 - Copy your snippet ID number.
- Step 9 - Go back to the playground and write the code to [load your snippet-saved animation](#load-from-the-snippet-server) when the scene starts.
- Step 10 - Select the sphere from the Inspector, open your animation in ACE, edit or change your animation, save to the snippet server. The line of code that loads the animation is automatically updated for you!

So there you have it, the 10 quick steps for the common way to animate an object in Babylon.js using ACE. One final important note: the Animation system in Babylon.js is very advanced. An animation can exist attached to an object, attached to an animation group, or just exist by itself. If you want to create a new animation using ACE, you have to create an animation that is attached to an object. In other words, you cannot create a standalone animation, or an animation attached to an animation group through ACE.



## Introduction to the Inspector

## Part 1: Introduction and Scene Explorer

<Youtube id="Xxqas3_b0mE"/>

In the first video of the "Intro to the Inspector" series, Jason walks you through how to get started with the Inspector and gives you an overview of the power of the Scene Explorer Window.

## Part 2: The Inspector Window

<Youtube id="WZzMcKw2qAY"/>

In the second video of the "Intro to the Inspector" series, David walks you through the 4 tabs of the Inspector Window.

## Part 3: Scene Properties

<Youtube id="p8cZIP5Sdrc"/>

In the third video of the "Intro to the Inspector" series, Patrick walks you through Scene Properties, including post processing options for all materials in the scene.

## Part 4: Camera Properties

<Youtube id="YaSscG5PBf0"/>

In the fourth video of the "Intro to the Inspector" series, Nick walks you through the Camera Properties and shows you some handy controls of the Arc Rotate Camera.

## Part 5: Material and Texture Properties

<Youtube id="7t9kRCzTP8M"/>

In the fifth video of the "Intro to the Inspector" series, David walks you through the Material and Texture Properties and shows you some handy tips for debugging materials, including the powerful "split" tool.

## Part 6: Mesh Properties

<Youtube id="BD7eqdhOe8M"/>

In the sixth video of the "Intro to the Inspector" series, Nick walks you through the Mesh Properties and shows you some quick ways to see advanced details about the meshes in your scene.

## Part 7: Animation Properties

<Youtube id="1-YRcs-M81w"/>

In the seventh video of the "Intro to the Inspector" series, Trevor walks you through the Animation Properties, showing you how to access different animations in your asset and how to visualize skeletons.

## Part 8: Render Pipeline

<Youtube id="imNGaP3VogU"/>

In the eighth video of the "Intro to the Inspector" series, Patrick walks you through using render pipelines, taking advantage of post-process effects to create stunning images. 

## Part 9: The Tools Tab

<Youtube id="omSoLMpxUfY"/>

In the ninth video of the "Intro to the Inspector" series, Saurabh walks you through using the Tools Tab to export screenshots, video, and even "cut and paste code" that you can easily add to your own projects.

## Part 10: Control the Inspector Via Code

<Youtube id="1Y7Mwjfxbm8"/>

In the tenth video of the "Intro to the Inspector" series, Saurabh walks you through how to open up the inspector via code, including how to customize it to your own needs.


## Creating Particles The Easy Way

Babylon.js has a feature-rich, powerful particle system. Babylon.js 4.2 introduced a new tool to make it simple and easy to leverage this powerful system. The Babylon.js Particle Editor. Built right into [The Inspector](/toolsAndResources/inspector), creating particle systems is now as easy as right-clicking! From there you can save your particle system to a [snippet server for load](/features/featuresDeepDive/particles/particle_system/particle_snippets) or you can save your file to be [loaded from a local json file](/features/featuresDeepDive/particles/particle_system/particles_loadFromFile).

<img src="/img/tools/particleEditor.jpg" title="Babylon.js Particle Editor"/>

You can jump in and play around with it here: <Playground id="#M7MYT8#11" title="Particle Editor" description="Simple example of particles using the particle editor."/>

For an introductory look at the Particle Editor, check out where it all started with these videos:

<Youtube id="BPJ0SZQnOXk"/>

<Youtube id="HgcUkTZmWyA"/>

<Youtube id="mKTD2P1lF9Q"/>

When you're ready to learn more about particles and particle systems, head on over to the [Particle System Documentation](/features/featuresDeepDive/particles/particle_system).


## What is it?

Introduced in Babylon.js 5.0, The Performance Profiler is a fantastic visual performance debugging tool. As you develop your Babylon experience, this new tool can help you easily identify performance issues and hiccups in your scene.

<img src="/img/tools/PerfViewer/performanceViewerStatisticsTab.png" title="Babylon.js Performance Viewer Statistics Tab"/>

Available in the Statistics tab of the inspector, it allows you to visually see data charted over time rather than seeing the latest number at any one moment. The data is normalized on the displayed range, meaning the smallest value corresponds to the bottom y-position on the graph, while the highest value corresponds to the top y-position. 

The Performance Profiler can collect and display 3 types of data: 1) all the data under the statistics tab, 2) user-defined data, and 3) user-defined events through code.

It has two modes for recording data:
 - Real-time graph mode.
 - Headless recording mode.

## Use Case

You would want to use this to debug any performance issues in your scene and figure out a potential cause. 
For example, you may notice that FPS drops whenever you do a specific action in the scene, and that draws increase simultaneously.

## How to use it

<img src="/img/tools/PerfViewer/performanceViewerStatisticsTab.png" title="Babylon.js Performance Viewer Statistics Tab"/>

There are four buttons to choose from on this screen:
 - Open Realtime Perf Viewer
 - Load Perf viewer using CSV
 - Export Perf to CSV
 - Begin Recording

"Open Realtime Perf Viewer" will open the performance viewer popout in real-time graph mode. 
While "Load Perf viewer using CSV" will open the performance viewer popout in a view-only mode. 

<img src="/img/tools/PerfViewer/PerformanceViewerPopout.png" title="Babylon.js Performance Viewer Popout"/>

The left sidebar in the popout holds the activated collection types. It allows the user to toggle visibility and change color through the checkbox and color picker, respectively.
<img src="/img/tools/PerfViewer/PerfProfilerColor.png" title="Changing the color of a collection type through the color picker"/>

The center contains the graph, and you can hover at a particular timestamp to view all data values at the timestamp. 
<img src="/img/tools/PerfViewer/PerfProfilerHover.png" title="Popout"/>

You can zoom in and out using the mouse wheel. 

You can pan the graph by dragging while clicking, taking the graph out of the live data stream. 

You can hover over a single line outside the live data stream to focus on it, fading out the other lines. 

A horizontal line shows where that point is relative to every other point on the focused line.

<img src="/img/tools/PerfViewer/PerformanceViewerFocus.png" title="Babylon.js Performance Viewer Line Focus"/>

To return to the live data stream, you can either catch up to the live data stream or conveniently click the "Return" button.

"Begin Recording" will only begin recording in headless recording mode. This button also will allow you to stop recording when it changes the text to "Stop recording."

<img src="/img/tools/PerfViewer/PerfProfilerStopRecording.png" title="Babylon.js Performance Viewer Line Focus"/>

"Export Perf to CSV" allows you to export the performance recording to a CSV. The CSV export provides for sharing of performance data and also importing at a later time.

"Begin Recording" and "Export Perf to CSV" are helpful for the mobile experience, as the popout will not work as intended in real-time graph mode while on mobile. You will have to export the recording and import it on a PC. However, these can also be used on the PC outright.

## Headless recording mode vs. Real-time graph mode.
Real-time graph mode opens up a popout and begins recording, while headless recording mode begins recording without the popout.

Therefore, real-time graph mode will allow you to see a graph updating once per frame with performance data.

Headless recording mode will have a lower performance impact and not rely on the popout, useful for mobile.

## Collection Strategies
A collection strategy is just a strategy defining how to collect the data and do clean up appropriately.

There are many collection strategies already defined for you in the PerfCollectionStrategy class.

We currently support these out of the box:

| Id | Strategy |
| -- | -------- |
| FPS | FpsStrategy |
| Total Meshes | TotalMeshesStrategy |
| Active Meshes | ActiveMeshesStrategy |
| Active Indices | ActiveIndicesStrategy |
| Active Faces | ActiveFacesStrategy |
| [Active Bones](/features/featuresDeepDive/mesh/bonesSkeletons) | ActiveBonesStrategy |
| [Active Particles](/features/featuresDeepDive/particles) | ActiveParticlesStrategy |
| Draw Calls | DrawCallsStrategy |
| [Total Lights](https://doc.babylonjs.com/divingDeeper/lights) | TotalLightsStrategy |
| Total Vertices | TotalVerticesStrategy |
| [Total Materials](https://doc.babylonjs.com/divingDeeper/materials) | TotalMaterialsStrategy |
| Total Textures | TotalTexturesStrategy |
| Absolute FPS | AbsoluteFpsStrategy |
| [Meshes Selection](/features/featuresDeepDive/scene/optimizeOctrees#optimizing-meshes-selection-for-rendering) | MeshesSelectionStrategy |
| Render Targets | RenderTargetsStrategy |
| Particles | ParticlesStrategy |
| [Sprites](/features/featuresDeepDive/sprites) | SpritesStrategy |
| Animations | AnimationsStrategy |
| [Physics](/features/featuresDeepDive/physics) | PhysicsStrategy |
| Render | RenderStrategy |
| Frame Total | FrameTotalStrategy |
| Inter Frame | InterFrameStrategy |
| GPU Frame Time | GpuFrameTimeStrategy |
| [CPU Utilization](https://web.dev/compute-pressure/) | CpuStrategy |


The CPU strategy is more experimental as it uses the experimental computer pressure API. This strategy may not work as intended for all users.
You might have to enable experimental web features in chrome settings to enable this. This strategy allows you to know the utilization percentage of the CPU.

## Adding a custom collection strategy

You may have custom data that you want to track that we do not support outside of the box. Don't worry, we've made this very easy to do.

To start, you must define a function that returns an object like so:
```javascript
// This variable would be updated somewhere else.
var someVariableToTrack;

const someStrategyCallback = (scene) => {
    return {
        /**
        * The id of the strategy.
        */
        id: "some strategy id",
        /**
        * Function which gets the data for the strategy.
        */
        getData: () => someVariableToTrack,
        /**
        * Function which does any necessary clean-up. Called when performanceViewerCollector.dispose() is called.
        */
        dispose: () => {
            // do any clean up here.
        }
    }
};
```
When added to the performance collector, the collector passes the scene object as a parameter to the function (you can omit the scene parameter if you would like).
The function allows for any initialization of observers and other resources.

The id parameter is the name of the strategy. Make sure to have a unique id, or else there may be unintended side effects. Also, if your id contains the character "@", the character will be removed, since it is already used when exporting data. The left sidebar will display the id defined.
The getData function in the object must return a number that cannot be NaN. It is called once per frame.
The dispose function in the object should do any clean-up of resources created in the initialization part of the function.

Here is an example of how we keep track of draw calls in the PerfCollectionStrategy class:
```typescript
public static DrawCallsStrategy(): PerfStrategyInitialization {
    return (scene) => {
        let drawCalls = 0;
        const onBeforeAnimationsObserver = scene.onBeforeAnimationsObservable.add(() => {
            scene.getEngine()._drawCalls.fetchNewFrame();
        });

        const onAfterRenderObserver = scene.onAfterRenderObservable.add(() => {
            drawCalls = scene.getEngine()._drawCalls.current;
        });

        return {
            id: "draw calls",
            getData: () => drawCalls,
            dispose: () => {
                scene.onBeforeAnimationsObservable.remove(onBeforeAnimationsObserver);
                scene.onAfterRenderObservable.remove(onAfterRenderObserver);
            },
        };
    };
}
```
In the function, we create two observers and update the value of draw calls in the onAfterRenderObservable.
We return the value of draw calls in getData.
We remove all observers inside the dispose function.

Now that you have a collection strategy, you have to add it to the performance collector. To do so, you also have to specify a category for your strategy to be displayed in the left bar (you can leave it empty to display on top), and if that strategy is hidden or visible by default.

First, get the performance collector like so:
```javascript
const perfCollector = scene.getPerfCollector();
```
Then add the strategy we defined earlier to the performance collector:
```javascript
const someStrategy = {
    strategyCallback: someStrategyCallback,
    category: "My custom category",
    hidden: false
}
perfCollector.addCollectionStrategies(someStrategy);
```

<img src="/img/tools/PerfViewer/PerfViewerCustom.png" title="Custom strategies and categories"/>


<Playground id="#VK7KBX" title="Custom Performance Profiler strategies" description="Example of defining and visualizing your own custom profiler strategies"/>

## Registering a custom event.
An event is a particular type of strategy that can measure the number of times it was called in a frame or track a named custom value (related to an event usually) once per frame.
To register an event you would do the following:
```javascript
const perfCollector = scene.getPerfCollector();
const event = perfCollector.registerEvent("someEvent");
```
The register event function returns an object containing the event passed in:
```javascript
{
   /**
    * The name of the event.
    */
   name: "",
}
```

If you want to count the number of times an event was called, you would want the following somewhere in the code:
```javascript
perfCollector.sendEvent(event);
```

<Playground id="#WSVER7" title="Custom Performance Profiler event" description="Example of defining and visualizing your own custom profiler events"/>

If you want to track a custom value once per frame related to an event, try this:
```javascript
// somewhere in the code you want this
event.value = someValue;

// followed by this somewhere in the code
perfCollector.sendEvent(event);
```

**Note**: You shouldn't set the value property to undefined after selecting a value for it. Doing so may result in unexpected behavior (this will switch between counting the number of occurrences and tracking a custom value related to an event).

<Playground id="#SGLKK6" title="Custom Performance Profiler event with value" description="Example of defining and visualizing your own custom profiler events with values"/>



_This feature is a work in progress._

## Using the Reflector

### Step 1 - Start the reflector bridge

Clone the Babylon.js repo and launch the reflector bridge from the command line.

The default port is 1234. Specify a different port by adding `--port=<port>` to the command line.

![bridge](/img/features/reflector/bridge.png)

### Step 2 - Start the reflector debugging session
Open https://sandbox.babylonjs.com/?reflector=true.

The default hostname and port are `localhost` and `1234`. Specify a different hostname or port by adding `&hostname=<hostname>&port=<port>` to the url. The hostname and port must match the host and port that is running the reflector bridge.

![debug session](/img/features/reflector/debugSession.png)

### Step 3 - Connect to the reflector debugging session from the client

The reflector is supported in scenarios that run Babylon.js with WebSocket support (e.g. a web page running Babylon.js in a browser or a Babylon React Native application). To enable the connection, a [reflector](/typedoc/classes/babylon.reflector) instance must be created. Here is an example of the JavaScript:

```javascript
const reflector = new BABYLON.Reflector(scene, "localhost", 1234);

// ...

reflector.close();
```

The inspector UI in the Tools pane has this code built in. For example, loading a glTF model in the sandbox on an Android device connected to a desktop via USB connection with port forwarding enabled, the inspector can be used to connect to the remote debugging session.

![connect to reflector](/img/features/reflector/connectToReflector.png)

After transferring the scene, the reflector debugging session will reflect the scene from the device:

![debug session with scene](/img/features/reflector/debugSessionWithScene.png)

Happy remote debugging the scene!

## Known Issues

* Some states are not correctly reflected across the remote connection.
* Large scenes may exceed the limits of how much can be transferred via web sockets.
* The web scokets are currently not secure which can cause issues with https connections.



## Debugging Skeletons and Rigging Issues

When something isn't working right, simple debugging tools can help us identify and fix the issue quickly. This is Babylon.js 4.2 added an all new Skeleton Viewer. Built right into [The Inspector](/toolsAndResources/inspector), from rendering bones and joints, to visualizing skin weights, the Skeleton Viewer is sure to make it quick and easy to debug pesky rigging issues inside your scene.

<img src="/img/tools/skeletonViewer.jpg" title="Babylon.js Skeleton Viewer"/>

You can jump in and play around with it here: <Playground id="#KK9Z6D#1" title="Skeleton Viewer" description="Simple example of the skeleton viewer in The Inspector."/>

When you're ready to learn more about the different skeleton viewer options, head on over to the [Skeleton Viewer Documentation](/toolsAndResources/inspector#bones-viewer).


## Creating Sprites The Easy Way

Babylon.js has a sprite system with many features and components. Babylon.js 4.2 introduced a new tool to make it simple and easy to leverage this powerful system. The Babylon.js Sprite Editor. Built right into [The Inspector](/toolsAndResources/inspector), creating sprite managers and controlling sprites is now as easy as right-clicking!

<img src="/img/tools/spriteEditor.jpg" title="Babylon.js Sprite Editor"/>

You can jump in and play around with it here: <Playground id="#G3Q7GR#1" title="Sprite Editor" description="Simple example of sprites using the sprite editor."/>

For an introductory look at the Particle Editor, check out where it all started with these videos:

<Youtube id="v02wuOGD0Sg"/>

When you're ready to learn more, head on over to the [Introduction to Sprites Documentation](/features/featuresDeepDive/sprites/sprites_introduction) for more info.


## Using the Texture Inspector

The Texture Inspector is designed to enable you to debug your textures inside of Babylon. Users often load in textures and find that they do not appear as expected. Unexpected results can be related to transparency, UVs, or unique texture types such as cubemaps. The Texture Inspector allows you to investigate issues and even fix them in-engine.

## How to Access

![Accessing the Inspector](/img/features/debuglayer/texture/access.png)
The Texture Inspector can be accessed from the main inspector panel. Simply select a texture from the list, and click the "edit"  button underneath the texture preview.

## Properties

![Properties Bar](/img/features/debuglayer/texture/properties.png)

### Dimensions

The width and height of the texture are shown in pixels. Editing these values and then clicking the dashed rectangle will resize the texture.

### Pixel Inspection

These values show the coordinates and RGBA values of the pixel under the cursor.

### MIP Levels

Adjust the MIP level you are viewing. Some textures do not have mipmaps. Clicking the down button will take you to lower levels of detail.

### Reset, Upload, Download

The reset button restores the texture to its original state before it was opened in the inspector. The upload button allows you to upload a local file (.png, .jpeg, .dds, and .env are currently supported.) The download button will save the texture to your local machine using the name displayed in the bottom left.

### Faces (Cubemaps only)

When inspecting a cubemap, you can click through the 6 buttons to view the faces of the cubemap.

## Tools

![Toolbar](/img/features/debuglayer/texture/tools.png)

### Rectangle Select

Selects a region of the texture. When you have a reigon selected, edits will only be applied to that region. Press Escape to clear the selection.

### Paintbrush

Paints the active color onto the texture. The size slider controls the width of the brush. The paintbrush will always apply the exact active RGBA value, rather than blending with what's currently on the canvas.

### Eyedropper

Sets the active color to the RGBA value of clicked pixels.

### Floodfill

Floods the entire texture or selected region with the active color and alpha.

### Active Color

Displays the active color and alpha, which are used by other tools. Clicking opens a panel which allows precise manipulation of the RGBA values.

## Channels

![Channel Pane](/img/features/debuglayer/texture/channels.png)
This pane is used to control the RGBA channels. Clicking the eye icons on the left will hide individual channels, allowing you to narrow your focus to particular channels. Clicking the letter on the right will lock a channel, meaning that any edits you perform will not affect that channel.

## Shortcuts

-   Mousewheel and the +/- buttons allow you to zoom in and out
-   The middle mouse button allows you to pan across the texture
-   Control+A selects the entire texture
-   Escape deselects everything
-   Control+S saves the texture to your local machine
-   Control+R resets the texture to its original state



## What Is It?

Babylon.js inspector is a visual debugging tool created to help pinpoint issues you may have with a scene.

For a video overview of the inspector, check out [Introduction to the inspector - video series](/toolsAndResources/inspector/inspectorVideoOverview).

The inspector offers multiple tools like:

- A hierarchical view of your scene
- Multiple property grids to let you dynamically change object properties
- Specific helpers like the skeleton viewer, etc.

Its interface uses two panes:

- The scene explorer pane
- The inspector pane

It can be called in two manners:

1. Without [ES Modules](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)

```javascript
scene.debugLayer.show();
```

2. Using ES Modules (Avoid using the first approach if you're already using modules):

```javascript
import { Inspector } from '@babylonjs/inspector';

// ... YOUR SCENE CREATION
Inspector.Show(scene, {});
```

![debug layer overview](/img/features/debuglayer/debuglayer.jpg)

### Embedded Mode

The two panes can also be opened in an [embedded mode](/typedoc/interfaces/babylon.iinspectoroptions):

```javascript
scene.debugLayer.show({
  embedMode: true,
});
```

or:

```javascript
Inspector.Show(scene, {
  embedMode: true
});
```

![embed mode](/img/features/debuglayer/embedmode.jpg)

To hide the inspector:

```javascript
scene.debugLayer.hide();
```

or:

```javascript
Inspector.Hide(); // You don't need to pass the scene
```

## Scene explorer pane

![scene explorer](/img/features/debuglayer/sceneExplorer.jpg)

The scene explorer displays a hierarchical view of your scene. You can filter by name in the filter bar if you want to find a specific entry.

By clicking on a line you will select it and the inspector will automatically update to reflect the properties of the selected item.

Some entities offer shortcuts to contextual actions.

## Scene actions

![scene actions](/img/features/debuglayer/sceneactions.jpg)

The scene shortcuts are the following:

- The first 3 actions will turn on a specific gizmo mode ([translation](/typedoc/classes/babylon.transformnode#translate), rotation, scaling). When you click on one of them you can then click on a node in the Scene explorer or directly in your scene and it will be controllable with a gizmo:

![gizmo](/img/features/debuglayer/gizmo.jpg)

- The fourth action is a picker. Just pick a mesh in your scene and it will be selected in your scene explorer
- The last one will force the scene explorer to update. For performance reasons, the scene explorer is not listening to all changes that can happen on the scene so you may end up needing to refresh it manually.

## Mesh actions

![mesh actions](/img/features/debuglayer/meshactions.jpg)

The mesh shortcuts are the following:

- The first action will enable the bounding box gizmo:

![bounding box gizmo](/img/features/debuglayer/boundingboxgizmo.jpg)

- The second action will show/hide the mesh.

## Light actions

![light actions](/img/features/debuglayer/lightactions.jpg)

You can use the light action to turn a light on and off.

## Camera actions

![camera actions](/img/features/debuglayer/cameraactions.jpg)

You can use the camera action to switch the active camera (when they are multiple cameras in a scene).

## GUI control actions

![gui control actions](/img/features/debuglayer/controlactions.jpg)

You can use the GUI control actions to:

- Display outline of a control
- Show / hide a specific control

## Rendering pipeline actions

![Rendering pipeline actions](/img/features/debuglayer/renderpipelineactions.jpg)

When your scene does not contain a default rendering pipeline, you can right-click on the rendering pipelines node to get a context menu letting you create a new default rendering pipeline.

## Inspector pane

The inspector pane contains 4 tabs:

![inspector](/img/features/debuglayer/inspector.jpg)

- The property grid which will display configurable controls for the current selected entity:

![property grid](/img/features/debuglayer/property.jpg)

- The debug pane will let you turn features on and off. It also let you display a grid and turn viewers (bones or physics) on and off:

![debug pane](/img/features/debuglayer/debugpane.jpg)

- The statistics pane gives information about all metrics captured by the engine:

![stats pane](/img/features/debuglayer/statspane.jpg)

- The tools pane lets you access utilities (like screen capture or recording as well as several tools related to glTF):

![tools](/img/features/debuglayer/tools.jpg)

## Popup mode

There are occassions when opening the inspector in a child window is preferable. It may be that the canvas size is too small to effectively use the inspector or the inspector is covering too much of the canvas making it hard to debug the scene. There are a few ways you can pop the inspector into a child window that is still connected to the scene. The first is by simply clicking the icon on the right side of the pane header bar adjacent to the close button. 

![popup](/img/features/debuglayer/popup.jpg)

This will pop out the selected pane - either Scene Explorer or Inspector - into a child window. If the panes have been opened in [embedded mode](/toolsAndResources/inspector#embedded-mode), the embedded inspector will open into a single child window. Additionally, the inspector can be opened by default as a popup. The individual Scene Explorer and Inspector panes can be opened as popups with the following code:

``` javascript
var debugLayer = await scene.debugLayer.show();

debugLayer.popupSceneExplorer();
debugLayer.popupInspector();
```
<Playground id="#KN5JBQ#3" title="Popup mode for Inspector panes" description="An example of opening inspector panes in popup mode" image="/img/playgroundsAndNMEs/inspectorPopup.jpg" />

### Embedded Popup Mode
Additionally, the embedded mode inspector can be opened as a popup by default:

``` javascript
var debugLayer = await scene.debugLayer.show({
    embedMode: true
});

debugLayer.popupEmbed()
```
<Playground id="#KN5JBQ#5" title="Embedded popup mode for Inspector panes" description="An example of opening embedded inspector in popup mode" image="/img/playgroundsAndNMEs/inspectorEmbedPopup.jpg" />

## Specific debug tools

Specific debug tools can be found across the inspector:

## Render grid

This tool (available in the Debug pane) will render a grid on the (0,0,0) plane:

![grid](/img/features/debuglayer/grid.jpg)

## Bones viewer

This tool (available in the skeleton property grid) will render your skeletons:

![bones](/img/features/debuglayer/BonesView.png)

## Skeleton Map Shader

This tool (available in the mesh property grid when the mesh has an attached skeleton) will render a unique color on the mesh, for each bone, showing their total contribution:

![bones](/img/features/debuglayer/BonesMap.png)

## Bone Weight Shader

This tool (available in the mesh property grid when the mesh has an attached skeleton) will render a heat map showing the selected bones contribution:

![bones](/img/features/debuglayer/BonesWeight.png)

## Physics viewer

This tool (available in the Debug pane) will render your physics impostors:

![physics](/img/features/debuglayer/physics.jpg)

## Normal painter

This tool (available in the property pane when you select a mesh) will paint the normals on your active mesh:

![paint normal](/img/features/debuglayer/paintnormal.jpg)

## Vertex normal viewer

This tool (available in the property pane when you select a mesh) will render the vertex normals of a mesh:

![vertex normal](/img/features/debuglayer/vertexnormal.jpg)

## Texture painter

This tool (available in the property pane when you select a material with textures in it) will render the texture directly as an emissive one:

![texture painter](/img/features/debuglayer/texturepainter.jpg)

## Extensibility

The inspector can be easily extended to allow manipulation of custom node properties. Simply define your custom properties in the node's `inspectableCustomProperties` array, and they will be available under the CUSTOM heading after selecting the node in the inspector.

<Playground id="#LQF5QR#2" title="Inspector custom properties for a node" description="An example of inspector custom properties for a node" image="/img/playgroundsAndNMEs/inspectorCustomProperties.jpg" />

```javascript
myNode.inspectableCustomProperties = [
  {
    label: "My boolean field",
    propertyName: "myBooleanField",
    type: BABYLON.InspectableType.Checkbox,
  },
  {
    label: "My color field",
    propertyName: "myColor3Field",
    type: BABYLON.InspectableType.Color3,
  },
  {
    label: "My quaternion field",
    propertyName: "myQuaternionField",
    type: BABYLON.InspectableType.Quaternion,
  },
  {
    label: "My numeric range field",
    propertyName: "myRangeField",
    type: BABYLON.InspectableType.Slider,
    min: 0.5,
    max: 5.0,
    step: 0.1,
  },
  {
    label: "My string field",
    propertyName: "myStringField",
    type: BABYLON.InspectableType.String,
  },
  {
    label: "My vector field",
    propertyName: "myVector3Field",
    type: BABYLON.InspectableType.Vector3,
  },
  {
    label: "My tab field",
    type: BABYLON.InspectableType.Tab,
  },
  {
      label: "My options field",
      propertyName: "myOptionsField",
      options: [
          { label: "options1", value: 1 },
          { label: "options2", value: 2 }
      ],
      callback: (option)=>{
      
      },
      type: BABYLON.InspectableType.Options,

  },
  {
      label: "My button field",
      propertyName: "myButtonField",
      callback: ()=>{
      
      },
      type: BABYLON.InspectableType.Button,

  }
];
```

The inspector can also be extended to allow manipulation of custom material properties.
<Playground id="#LQF5QR#52" title="Inspector custom properties for a material" description="An example of inspector custom properties for a material"/>



## Overview

The Babylon.js Sandbox is a powerful, web-based 3D asset viewer and debugging tool for developers and designers working with Babylon.js. It allows users to load and inspect 3D models, textures, animations, and materials with an intuitive interface. The Sandbox is an essential utility for testing and fine-tuning assets before integrating them into a Babylon.js project.

## Features

- **Model Preview**: View and interact with 3D models in real-time.
- **Supported File Formats**: `.gltf`, `.glb`, `.obj`, `.stl`, `.babylon`
- **Animation Playback**: Play, pause, and scrub through animations.
- **Environment Map Support**: Select built-in or load custom environment textures for realistic lighting.
- **Inspector Integration**: Explore detailed object properties like meshes, lights, cameras, and more.

## Accessing the Sandbox
1. Open a web browser.
2. Visit the Sandbox at [sandbox.babylonjs.com](https://sandbox.babylonjs.com).

## Loading Assets
Load assets into the Sandbox using one of the following methods:
- **Drag and Drop**: Drag supported files directly onto the Sandbox interface.
- **File Selection**: Use the open button on the toolbar to browse the file system and load assets.

Note that all required assets including files referenced from the main asset file must all be dropped or
selected so that the browser knows about them. For example, if the asset is a glTF, the `.bin` file and
all image files must be dropped or selected for the asset to load properly.

## User Interface

### Toolbar
The toolbar at the bottom provides quick access to common tasks:
- **Animation Controls**: Play, pause, and scrub animations when animations are available.
- **Display inspector**: Opens the Inspector for detailed analysis.
- **Select environment**: Change environment lighting.
- **Open your scene**: Opens files from the local file system.

### Special Keys
- `R` - Reloads the current asset
- `Space` - Toggles the toolbar

## Advanced

### Custom Environment
Drag and drop an HDR environment map to test lighting and reflections on the loaded asset.

### URL Parameters
The sandbox URL accepts a query string to load a specific asset or configure settings. This is particularly useful when sharing an asset with a link so that the asset is presented with a specific configuration. Below are the available parameters.

_Parameter names and values are case-insensitive if possible._

- `asset` - The asset URL to load automatically.
- `autoRotate` - Set to `true` to turn on auto rotation of the active camera. Auto rotation is off by default.
- `camera` - The active camera index to use from the loaded scene.
- `cameraPosition` - The comma-separated `x,y,z` position of the active camera.
- `clearColor` - The clear color for the loaded scene in hex form (e.g., `FFFFFF` for pure white).
- `environment` - The environment URL to load for glTF assets. This parameter is ignored for other asset formats.
- `kiosk` - Set to `true` to hide the toolbar. The toolbar is visible by default.
- `skybox` - Set to `false` to not create a skybox for glTF assets. Skyboxes are created by default for glTF assets. This parameter is ignored for other asset formats.
- `toneMapping` - The tone mapping (`Standard`, `ACES`, `KHR_PBR_Neutral`) to use for the loaded scene.

#### Examples
- Load a specific URL  
  https://sandbox.babylonjs.com/?asset=https://assets.babylonjs.com/meshes/boombox.glb
- Hide the toolbar and auto rotate the camera  
  https://sandbox.babylonjs.com/?asset=https://assets.babylonjs.com/meshes/boombox.glb&kiosk=true&autorotate=true
- Use a specific environment  
  https://sandbox.babylonjs.com/?asset=https://assets.babylonjs.com/meshes/boombox.glb&environment=https://assets.babylonjs.com/environments/studio.env
- Use the Khronos PBR Neutral tone mapping and set the camera to a specific position  
  https://sandbox.babylonjs.com/?asset=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DragonDispersion/glTF/DragonDispersion.gltf&toneMapping=khr_pbr_neutral&cameraPosition=-0.13,1.64,3.4
