
An overview of the accessibility features in Babylon.js



## The Asset Librarian

Babylon.js provides a large asset library of free models, environments, textures, materials, particles, sounds, etc. These assets are free for you to use under the [Creative Commons 0](https://creativecommons.org/share-your-work/public-domain/cc0/) license.

Intrdouced in Babaylon.js 5.0, the Asset Librarian is an incredibly simply tool allowing you to access this full library of content directly in the playground with simple lines of code.

Using the "Assets" namespace, you can easily add any asset into your scene.

For example adding the Pirate Fort mesh into your scene is as simple as this:

```javascript
BABYLON.ImportMeshAsync(Assets.meshes.pirateFort.rootUrl + Assets.meshes.pirateFort.filename, scene);
```

<Playground id="#ABDDD6#122" title="Load a Mesh Using the Asset Librarian" description="Simple example of how to use the Asset Librarian to load mesh into the scene." isMain={true} category="Import"/>

## Adding To the Asset Library

The raw files for the assets available through the Asset Librarian can be found in the [Babylon.js Assets Github Repository](https://github.com/BabylonJS/Assets).

This library of assets is free, open-source, and available for anyone to use under the [Creative Commons 0](https://creativecommons.org/share-your-work/public-domain/cc0/) license.

If you would like to contribute your own assets to the asset repository, you are ABSOLUTELY encouraged to do so. This is the spirit of Open Source Software.

We will gladly accept assets that:

1. Are family-friendly, safe, and welcoming to everyone.
2. Can be useful to anyone (no custom airplane turbine mounting bracket CAD files please)

Please be aware that the Babylon Development Team reserves the right to accept, decline, or remove ANY asset being contributed to this library for any reason, including: overusing hosting resources, content that is not family-friendly, safe, or welcoming of everyone, content that does not benefit the greater community.

Also please understand that by contributing your assets to the asset repository, you are offering your assets freely under the [Creative Commons 0](https://creativecommons.org/share-your-work/public-domain/cc0/) license. Only assets that are given freely to the public domain will be accepted.




# Asset Libraries

A range of libraries for textures, models and more to load into the playground. These can help you to illustrate issues you may have without having to find a CORs acceptable server to load your own assets into the playground. Also a range of programmable textures and material built using a variety of shaders.


<img src="/img/tools/guiEditor/overview.jpg" title="Babylon.js GUI Editor"/>

## Creating GUIs With Ease

Introduced in Babylon.js 5.0, the GUI Editor is a visual editor for building complex and beautiful graphical user interfaces. Traditionally, Babylon GUIs has to be constructed using code, which could be a tedious and confusing process. The GUI Editor lets you see the interface as you're assembling it, and makes it easy to manipulate all the parameters of each control.

You can access the GUI Editor here: https://gui.babylonjs.com/. The GUI editor can also be opened in a pop-up window from the inspector, allowing you to edit a GUI inside a scene and see your changes propagate back instantly!

This document will walk you through the editor and its capabilities and should help you quickly start creating your own GUIs. If you're not familiar with the GUI system in Babylon.js and would like to learn more, you can read all about it here: [Babylon GUI Documentation](/features/featuresDeepDive/gui/gui)

<Youtube id="9VXgZ_af-nE"/>

## Getting Familiar With The Layout

Let's start by familiarizing ourselves with different parts of the editor.

### Header Bar

<img src="/img/tools/guiEditor/commandBar.jpg" title="GUI Editor Command Bar"/>

The Header Bar provides several handy items to help you navigate and manage your GUI creations.

#### Hamburger Menu

<img src="/img/tools/guiEditor/hamburgerMenu.jpg" title="GUI Editor Hamburger Menu"/>

The hamburger menu provies some basic helpful scene management options, including saving and loading your progress locally, saving and loading your progress to the snippet server, and a quick 'help' link to access the Babylon.js GUI documentation.

#### Select (S)

<img src="/img/tools/guiEditor/select.jpg" title="GUI Editor Select"/>

The select button allows you to select different GUI controls within your scene.

#### Pan (P)

<img src="/img/tools/guiEditor/pan.jpg" title="GUI Editor Move"/>

The move button allows you to pan around the GUI by clicking and dragging. You can also use the middle mouse button, or hold space and drag, to pan around your GUI.

#### Zoom (Z)

<img src="/img/tools/guiEditor/zoom.jpg" title="GUI Editor Zoom"/>

The zoom button allows you to click on the canvas and drag to zoom in. You can also hold ALT+click to zoom out.

#### Fit To Window (F)

<img src="/img/tools/guiEditor/fitToWindow.jpg" title="GUI Editor Fit To Window"/>

When pressed, the Fit To Window button will snap the zoom and panning back to the starting position, where the entire canvas can be seen. If you have any controls selected, Fit To Window will crop the viewport around those controls.

#### Toggle Guides

<img src="/img/tools/guiEditor/toggleGuides.jpg" title="GUI Editor Toggle Guides"/>

The Toggle Guides button will display boundary lines for all of the GUI elements in your scene.

<img src="/img/tools/guiEditor/toggleGuidesVisual.jpg" title="GUI Editor Toggle Guides Example"/>

#### Artboard Color

Allows you to change the background color in the region outside of the canvas.

#### Responsiveness and Resolution

You can either specify a specific resolution for your canvas in pixels, or you can turn on responsive mode, which lets you easily swap between common resolutions such as mobile and desktop. Responsiveness is an editor-only concept, it does not affect the exported GUI.

<img src="/img/tools/guiEditor/resolutionResponsive.jpg" title="GUI Editor Responsive Resolution"/>

### Hierarchy Panel

<img src="/img/tools/guiEditor/layersPanel.jpg" title="GUI Editor Layers Panel"/>

The Hierarchy Panel is an organized list of all of the GUI controls that you've added to the canvas. You can select controls from this list as well as click and drag to parent and unparent them.

<img src="/img/tools/guiEditor/parenting.jpg" title="GUI Editor Parenting"/>

The order of controls listed in the Layers Panel reflects the z-order of the scene with the elments at the top of the list having a z-order that will render them on top of elements towards the bottom of the list.

If a control is placed behind another control in the scene, and it has a lower z-order, the only way to select it is from the hierarchy.

The 'eye' icon will show/hide controls on the canvas.

<img src="/img/tools/guiEditor/showHide.jpg" title="GUI Editor Show Hide"/>

### Controls Bar

<img src="/img/tools/guiEditor/toolsBar.jpg" title="GUI Editor Tools Bar"/>

The Controls Bar allows you to create GUI controls, such as a text box, rectangle, grid, etc. Each icon in this bar can be clicked on to add a specific GUI control to your canvas. You can also drag and drop these icons into either the canvas or the hierarchy tree to add it to the scene.

If you'd like to see a full list of supported GUI controls in the editor, [click here.](#supported-controls)

### Canvas

<img src="/img/tools/guiEditor/canvas.jpg" title="GUI Editor Canvas"/>

The Canvas is the main play area of the tool. The canvas contains the artboard where you can add controls, select controls, and click and drag controls to move them around. This panel represents a WYSIWYG (what you see is what you get) experience to how GUIs will show up in Babylon Scenes.

The checkerboard area reflects the content that will actually be visible in your scene when you load the GUI in. Note that controls can be moved outside of that region, which may be helpful if, for example, your UI has components that animate on and off-screen.

### Handy Keyboard Shortcuts

There are several handy keyboard shortcuts that you can utilize in the GUI Editor.

#### General Navigation:

- S = Select Mode
- P = Pan Mode
- Z = Zoom Mode
- F = Fit to Window
- G = Toggle Outlines
- CTRL+A = Select All

#### With a GUI Control Selected:

- CTRL+C = Copy
- CTRL+V = Paste
- CTRL+X = Cut
- Delete/Backspace = Delete

### Control Properties Panel

<img src="/img/tools/guiEditor/propertiesPanel.jpg" title="GUI Editor Properties Panel"/>

The Properties Panel will change based on which controls are selected to reflect the properties specific to those controls. This is where you'll find all of the properties and can fully customize each individual element of your overall GUI.

For example here is how to change the name of a GUI.

<img src="/img/tools/guiEditor/changeName.jpg" title="GUI Editor Change Name"/>

For properties which can be expressed in either pixels or percentage values, you can click on the unit button next to the input to toggle between unit types. The existing value will be converted into the equivalent value in the other unit.

<img src="/img/tools/guiEditor/changeUnits.jpg" title="GUI Editor Change Units"/>

Note: While using the GUI Editor to create a GUI and modify its properties, these properties can later be changed in the Babylon.js scene code. So you have full control over all of the GUI Control properties at creation time as well as runtime!

### Special Properties for Grid Control

Grids are a powerful tool for building complex UI layouts. Grids are helpful for setting up the foundation of your design. Just like in code, in the GUI Editor you can define your grid's row and column definitions.
You can add and remove rows and columns, as well as modify the sizes using either pixels or percent.

<img src="/img/tools/guiEditor/grid.jpg" title="GUI Editor Grid Properties"/>

You can then add them to the grid through parenting in the layers panel. Once parented, you can modify a control's grid cell by selecting the control and editing the newly added property at the bottom of the Properties Panel.

<img src="/img/tools/guiEditor/cell.jpg" title="GUI Editor Changing Control's Grid Cell"/>

Note: the zOrder of each control is determined by its position in the hierarchy tree, and can be reordered with normal dragging regardless of which grid cell it belongs to.

### Saving GUIs Out Of the Editor

You can save your GUI creations from the Editor in two different ways, locally or on the Babylon.js Snippet Server.

#### Saving Locally

Saving locally will download a .JSON object of your GUI to your local machine. This can then be either loaded back into the editor later for future use, or can be hosted somewhere of your choosing and then loaded directly into your Babylon scene. [See Loading GUIs Into The Playground](#loading-locally)

You can save locally by selecting the 'Save' button in the hamburger menu:
<img src="/img/tools/guiEditor/saveLocal1.jpg" title="GUI Editor Save Local 1"/>

#### Saving To The Snippet Server

Just like all Babylon tools, you have the option of saving your GUI creation directly to the Babylon.js snippet server. Saving in this manner saves the .json object to a Babylon.js server and provides a simple URL hash back for you to reference in the future. You can then load your GUI back into the editor by using this unique hash, or you can use the hash to load your GUI directly into the Babylon scene. [See Loading GUIs Into The Playground](#load-from-snippet-server). Saving to the snippet server will also update the browser's URL to point to that snippet (e.g., gui.babylonjs.com/#aaaaaa)

You can save to the snippet server by selecting the 'Save To Snippet' button in the hamburger menu:
<img src="/img/tools/guiEditor/saveSnippet1.jpg" title="GUI Editor Save Snippet 1"/>

### Loading GUIs Into the Editor

You can load your GUI creations into the Editor in two different ways, locally or from the Babylon.js Snippet Server.

#### Loading locally

Loading locally will prompt you to upload a .JSON object of your GUI into the Editor.

You can load locally by selecting the 'Load' button in the hamburger menu:
<img src="/img/tools/guiEditor/loadLocal1.jpg" title="GUI Editor Load Local 1"/>

#### Loading From The Snippet Server

Loading from the snippet server will take a unique hash of a previously saved GUI and load it into the Editor.

You can load from the snippet server by selecting the 'Load From Snippet Server' button in the hamburger menu:
<img src="/img/tools/guiEditor/loadSnippet1.jpg" title="GUI Editor Load Snippet 1"/>

### Using GUIs From The Editor In Your Scene

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 .JSON Object

You can load a GUI into your Babylon scene from a saved .JSON file somewhere on the web like this:

```javascript
let advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("GUI", true, scene);
let loadedGUI = await advancedTexture.parseFromURLAsync("https://doc.babylonjs.com/examples/ColorPickerGui.json");
```

<Playground id="#SWI883" title="Load a GUI from a .json Object" description="Simple example that shows how to load a GUI into your scene from a .json object."/>

#### Load From Snippet Server

You can also load a GUI into your Babylon scene from the Snippet Server like this:

```javascript
let advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("GUI", true, scene);
let loadedGUI = await advancedTexture.parseFromSnippetAsync("#MMWSUI");
```

<Playground id="#4RTUCB#1" title="Load a GUI From The Snippet Server" description="Simple example that shows how to load a GUI into your scene from the snippet server."/>

#### Load in Fullscreen Mode

You can load your saved GUI as a fullscreen GUI that's overlayed on top of your entire scene like this:

```javascript
let advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("GUI", true, scene);
let loadedGUI = await advancedTexture.parseFromSnippetAsync("#MMWSUI");
```

<Playground id="#4RTUCB#1" title="Load a GUI Into Fullscreen Mode" description="Simple example that shows how to load a GUI into fullscreen mode."/>

Further Information about fullscreen GUIs can be found here: [Fullscreen GUIs](/features/featuresDeepDive/gui/gui#fullscreen-mode)

#### Load in Texture Mode

You can also load a saved GUI as a texture that can be used like any other texture in your scene. Here's an example of using a loaded GUI as a texture for the material of a mesh:

```javascript
let screenUI = BABYLON.GUI.AdvancedDynamicTexture.CreateForMeshTexture(device.screen, 2048, 2048, true, false);
screenUI.parseFromSnippetAsync("#WFL50L");
```

<Playground id="#H896c7#145" title="Load a GUI Into Texture Mode" description="Simple example that shows how to load a GUI into texture mode and project it onto a mesh."/>

Further information about GUIs as in-scene textures can be found here: [GUIs as a Texture](/features/featuresDeepDive/gui/gui#texture-mode)

#### Changing GUI Control Properties In Your Scene

After loading a saved GUI into your scene, you can easily access the properties of your GUI Controls.

You can access an individual control by name like this:

```javascript
let backgroundBox = advancedTexture.getControlByName("BackgroundBox");
backgroundBox.background = "blue";
```

<Playground id="#JSF3QM" title="Load a GUI And Modify GUI Control Properties" description="Simple example that shows how to load a GUI and modify GUI controls."/>

A more sophisticated example can be found here:

<Playground id="#0CRLP8#13" title="Game Menu Demo" description="A game menu built using the GUI editor which demonstrates how tab navigation can be implemented." />

#### Playground Templates

You can also find quick access to the common lines of code needed to load GUIs into your scene, through the [playground templates.](/toolsAndResources/thePlayground/pgTemplates)

### Supported Controls

Here is a list of supported GUI controls available in the GUI Editor:

| Icon                                                             | Control Name     | Further Information                                                                              |
| ---------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| ![rectangle](/img/tools/guiEditor/rectangleIcon.jpg)             | Rectangle        | [Rectangle Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#rectangle)              |
| ![ellipse](/img/tools/guiEditor/ellipseIcon.jpg)                 | Ellipse          | [Ellipse Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#ellipse)                  |
| ![stackpanel](/img/tools/guiEditor/stackPanelIcon.jpg)           | Stack Panel      | [Stack Panel Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#stackpanel)           |
| ![grid](/img/tools/guiEditor/gridIcon.jpg)                       | Grid             | [Grid Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#grid)                        |
| ![scrollviewer](/img/tools/guiEditor/scrollViewerIcon.jpg)       | Scroll Viewer    | [Scroll Viewer Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#scrollviewer)       |
| ![line](/img/tools/guiEditor/lineIcon.jpg)                       | Line             | [Line Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#line)                        |
| ![textblock](/img/tools/guiEditor/textIcon.jpg)                  | Text Block       | [Text Block Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#textblock)             |
| ![inputText](/img/tools/guiEditor/inputTextIcon.jpg)             | Input Text       | [Input Text Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#inputtext)             |
| ![inputPassword](/img/tools/guiEditor/inputPasswordIcon.jpg)     | Input Password   | [Input Password Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#inputpassword)     |
| ![image](/img/tools/guiEditor/imageIcon.jpg)                     | Image            | [Image Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#image)                      |
| ![displayGrid](/img/tools/guiEditor/displayGridIcon.jpg)         | Display Grid     | [Display Grid Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#displaygrid)         |
| ![textButton](/img/tools/guiEditor/textButtonIcon.jpg)           | Text Button      | [A Button with a Text Block as a Child] (https://doc.babylonjs.com/divingDeeper/gui/gui#button)  |
| ![checkbox](/img/tools/guiEditor/checkBoxIcon.jpg)               | Checkbox         | [Checkbox Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#checkbox)                |
| ![radioButton](/img/tools/guiEditor/radioIcon.jpg)               | Radio Button     | [Radio Button Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#radiobutton)         |
| ![slider](/img/tools/guiEditor/sliderIcon.jpg)                   | Slider           | [Slider Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#slider)                    |
| ![virtualkeyboard](/img/tools/guiEditor/virtualKeyboardIcon.jpg) | Virtual Keyboard | [Virtual Keyboard Documentation](https://doc.babylonjs.com/divingDeeper/gui/gui#virtualkeyboard) |
| ![colorpicker](/img/tools/guiEditor/colorPickerIcon.jpg)         | Color Picker     | [Color Picker](https://doc.babylonjs.com/divingDeeper/gui/gui#colorpicker)                       |

### Demos

Check out additional demos here:
<Playground id="#5JEP1H" title="Full Color Picker Demo" description="More advance example that shows how to load a GUI and modify GUI controls."/>



## 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"/>



## Creating Shaders The Easy Way

Creating shaders can be a very dense and complicated process, often requiring knowledge of glsl and a strong understanding of how shaders work. Starting with Babylon.js 4.1, the Node Material Editor was introduced. This amazing tool is a visual editor allowing you to connect blocks together to make shaders. It's really that simple. 

<img src="/img/how_to/Materials/nme1.jpg" title="Babylon.js Node Material Editor"/>

You can jump in and play around with it here: <NME id="" title="Node Material Editor" description="The starting basic template for creating Node Materials."/>

For an introductory look at the Node Material Editor, check out where it all started with this video:

<Youtube id="34uIGJH0ySU"/>

When you're ready to learn more, head on over to the [Node Material Documentation](/features/featuresDeepDive/materials/node_material/nodeMaterial) for more info.

You can also dive into the API that powers it all here: [API documentation.](/typedoc/classes/babylon.nodematerial)

A handy pro tip in the Node Material Editor Preview Window is the ability to CTRL+Hover to see the RGB values.

<img src="/img/how_to/Materials/nmeRGBTrick.jpg" title="Babylon.js Node Material Editor"/>


## 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



## What Is Smart Filter Editor?

The Smart Filter Editor (SFE) is a visual tool, much like the Node Material Editor, designed to make it easy to rapidly build and preview Smart Filters.

It is available at https://sfe.babylonjs.com and your can run it locally if you clone the [BabylonJS/SmartFilters](https://github.com/BabylonJS/SmartFilters) repo and run the `npm run start:sfe` command.

It includes the blocks from the @babylonjs/smart-filters-blocks package (also in the [BabylonJS/SmartFilters](https://github.com/BabylonJS/SmartFilters)) repo, and can also use custom blocks you upload as JSON or GLSL files. These custom blocks are persisted in local storage, so you can load your own blocks once, then make use of them each time you return to SFE.

You can save the Smart Filters you create with SFE as local JSON files or as custom URLs you can share with others.

<Alert severity="Info">
Note that if you share a Smart Filter that uses custom assets or blocks, the person you are sharing with will with need to load those custom assets and blocks before loading your Smart Filter.
</Alert>

## Navigating SFE

![LAYOUT](/img/how_to/smart-filters/sfe-layout.png)

1. The Block Library is on the left
   - Click "Add..." in "Custom Blocks" to add a custom block to the library (see _Custom Blocks_ below for details)
   - Drag a block you'd like to use onto the canvas in the middle to create an instance of it
2. The canvas is in the middle of the tool, and shows your current Smart Filter visually
   - Drag from one connection point to another to form connections
   - You can zoom in/out with the mouse scroll wheel
   - Click on the background of the canvas to see Smart Filter level properties and actions in the right pane
3. The right pane contains properties and actions relevant to the selected block (or the whole Smart Filter if nothing is selected), as well as a real-time preview of the Smart Filter output
   - When no block is selected, you can choose to Load a Smart Filter from a local JSON file, Save to a local JSON file, or save to a unique URL
     - If you save to a unique URL, the URL in your address bar will update to that new unique URL which you can use in the future to load this Smart Filter from any browser
4. The console at the bottom shows timestamped status messages, including helpful details if an error occurs (such as a required connection isn't made)

## Custom Blocks

By default, SFE populates the block library with the blocks found in the @babylonjs/smart-filters-blocks package. You can add your own custom blocks to SFE without building it yourself by clicking the "Add..." button in the "Custom Blocks" section.

Custom blocks are saved in local storage, so you don't have to add them each time you visit SFE, but you will need to add them again if you need to open a Smart Filter that uses them in another browser or another computer.

There are 3 types of custom blocks that SFE supports adding:

1. Annotated GLSL block definitions
1. JSON block definitions
1. JSON aggregate block definitions (saved Smart Filters themselves)

### Annotated GLSL block definitions

These are fragment shaders defined in GLSL files with certain annotations in them to be loaded as Smart Filter blocks.

For example:

```annotated-GLSL
// { "smartFilterBlockType": "AnnotatedGlslTintBlock" }

uniform sampler2D input;
// { "default": { "r": 1, "g": 0, "b": 0 } }
uniform vec3 tint;
// { "default": 0.25 }
uniform float amount;

vec4 mainImage(vec2 vUV) { // main
    vec4 color = texture2D(input, vUV);
    vec3 tinted = mix(color.rgb, tint, amount);
    return vec4(tinted, color.a);
}
```

See [Creating New Blocks](/features/featuresDeepDive/smartFilters/creatingNewBlocks) for details of the annotation format.

### JSON block definitions

Block definitions can be serialized `SerializedShaderBlockDefinition` objects, such as this example:

```JSON
{
    "format": "shaderBlockDefinition",
    "formatVersion": 1,
    "blockType": "JSONTintBlock",
    "namespace": "Babylon.Demo.Effects",
    "shaderProgram": {
        "fragment": {
            "uniform": "
               uniform sampler2D _input_;
               uniform vec3 _tint_;
               uniform float _amount_;",
            "mainFunctionName": "_mainImage_",
            "functions": [
                {
                    "name": "_mainImage_",
                    "code": "
                        vec4 _mainImage_(vec2 vUV) {
                            vec4 color = texture2D(_input_, vUV);
                            vec3 tinted = mix(color.rgb, _tint_, _amount_);
                            return vec4(tinted, color.a);
                        }"
                }
            ]
        }
    },
    "inputConnectionPoints": [
        {
            "name": "input",
            "type": 2
        },
        {
            "name": "tint",
            "type": 3,
            "defaultValue": {
                "r": 1,
                "g": 0,
                "b": 0
            }
        },
        {
            "name": "amount",
            "type": 1,
            "defaultValue": 0.25
        }
    ],
    "disableOptimization": false
}
```

### JSON aggregate block definitions

Entire Smart Filters themselves can be imported into other Smart Filters as custom aggregate blocks! Try saving a Smart Filter to a local JSON file, then add it as a custom block to SFE.

Notes:

1. The input blocks in the imported Smart Filter will become input connection points on the custom aggregate block
1. The name and namespace of the Smart Filter (see the top right of SFE when no block is selected) becomes the block name and namespace of the custom aggregate block

## Special Input Blocks

SFE contains some special input blocks for testing your Smart Filters:

1. WebCamBlock
   - This is really a texture InputBlock which SFE automatically connects to your webcam as an easy way to preview live video in your Smart Filter
   - Note that when integrating a Smart Filter that uses a WebCamBlock into an application, that application will need to supply a texture for that InputBlock, which could come a webcam, or any other source
1. TimeBlock
   - This is really a float InputBlock which SFE automatically increments as a simple animation
   - Like with the WebCamBlock, when integrated into an application, this will behave as a regular InputBlock (this one of type float) whose value could be animated by the hosting application

## Assets

SFE contains some built-in assets for testing your Smart Filters, which you will see in the properties panel on the right when a texture InputBlock is selected.

You can use those built-in assets, or:

1. Upload your own image asset, which will be base64 encoded and saved in the Smart Filter for SFE to use later
1. Enter a URL to an image or video asset you'd like to use



## The Playground

The place to try out coding with Babylon.js. [Playground](https://playground.babylonjs.com/)

Experimenting and changing any code in the playground and clicking on the **Run** button will not affect any original code in the playground you are currently using.
Original code can be restored by refreshing the browser.

You can write the code in JavaScript or Typescript. The playground software compiles the code to JavaScript, in the background, before rendering.

### Scene creation functions

Usually you'll want to place your scene creation code in the already defined `createScene` function. But sometimes, you might want to substitute it for the `delayCreateScene` function, which allows you to return a scene without a camera (because for instance you plan to create the camera after an asynchronous mesh load, like: <Playground id="TVHK90#113" title="delayCreateScene example" description="An example of a Playground scene defined using the delayCreateScene function" image="/img/playgroundsAndNMEs/delayCreateSceneExample.png"/>).

You can also override the engine creation by defining the `createEngine` function. This can be useful if you want to test a scene without antialiasing, for example: <Playground id="#NCWBUU#1" title="createEngine example" description="How to use createEngine on the playground to customize engine creation" image="/img/playgroundsAndNMEs/createEnginePG.png"/>

## Overview

![Playground Overview](/img/how_to/Introduction/playground.jpg)

The Playground consists of four areas:

- A menu bar at the top.
- A links bar at the bottom.
- A coding editor on the left
- A rendering area of the right.

The space for the coding editor and rendering area can be adjusted by dragging the vertical bar between them.

## The Menu

![Playground Menu](/img/how_to/Introduction/pgmenu.jpg)

In Typescript mode the menu has an orange color theme:

![Playground Typescript Menu](/img/how_to/Introduction/pgmenu_ts.jpg)

### Large Screen

- **Title and Version**: As stated.
- **Language**: Typescript/JavaScript switch.
- **Run**: Commands the playground to try to render your scene.
- **Save**: Causes your scene to be permanently stored in the playground's database and it will issue a unique URL for each save. On save you will be asked to complete the metadata so that it can be searched for. Once saved it is a good idea to bookmark the page so you can return to it later. You could then share the URL with others, for example, if it is not working as you expect you can ask a question in the forum along with the link to your playground.
- **Download**: Allows you to download a zip file named _sample.zip_. Once downloaded and unzipped, you will see a file named `index.html`
  which contains everything necessary to run the code in your browser, including links to external _Babylon.js_ and other files.
- **New**: Places a basic `createScene()` function into the editor along with code to initialize the scene variable and provide a camera.
- **Clear**: Empties all the code out of the playground editor. You could then paste in any createScene function you are working on locally.
- **Settings**: The Settings button has a sub menu with extra options
  - _Theme_: Choose the theme for the playground
  - _Font size_: Set the font size in the editor.
  - _Safe Mode_: When the checkbox is ticked the playground issues a "leaving the page?" confirmation warning when you try to unload/reload a freshly-edited, un-saved scene.
  - _Editor_: The checkbox hides or un-hides the editor portion of the playground.
  - _Full Screen_: Makes the render area full screen.
  - _Editor Full Screen_: Makes the editor area full screen.
  - _Format Code_: Pretty prints the code.
  - _Minimap_: Display the minimap of the code editor.
  - _Metadata_: This is where you describe your playground allowing yourself and other to search the playground database for examples of use.
- **Version**: Allows and shows your choice of the Babylon.js framework, either the current stable one or the latest preview version.
- **Examples**: A drop down menu giving examples of playgrounds with a search filter.

### Small Screens

![Playground Typescript Menu](/img/how_to/Introduction/smallScreensPG.png)

- **Menu**: Contains Run, New, Clear, Save and Zip as submenus.
- **Code/Scene**: Bottom Left Corner - switch between Code and Scene views.

## Playground URL formats and templates

After editing any saves of the playground are numbered incrementally from one, for example:

- https://playground.babylonjs.com/#6F0LKI#1
- https://playground.babylonjs.com/#6F0LKI#2
- etc...

Some useful HTML templates are also available:

| Template                                                           | Description                                                                                          |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| [full.html](https://playground.babylonjs.com/full.html#6F0LKI#2)   | Shows the render area in full screen                                                                 |
| [frame.html](https://playground.babylonjs.com/frame.html#6F0LKI#2) | Shows the render area in full screen, but with a bottom toolbar showing FPS, reload and edit buttons |
| [debug.html](https://playground.babylonjs.com/debug.html#6F0LKI#2) | Uses a debug version of Babylon.js                                                                   |

## Forum sharing

Of course the playground is extremely useful to get help from the community. In the forum, simply paste the link of your playground.

You can have fun showing directly your playground embedded into your message, using iframe. But take note that you have to be sparing with this functionality: this will slow down the loading of your topic.

```html
<iframe src="https://playground.babylonjs.com/frame.html#6F0LKI#2" width="400px" height="250px"></iframe>
```

![playground forum sharing ways](/img/features/pgsupport/pg-forum-sharing-ways.jpg)

## Compilation Errors

![compilation error popup](/img/features/pgsupport/pg-compilation-error.jpg)

Any errors in your playground are flagged with a red pop-up box containing limited information. After making an adjustment to your code, you need not close the compilation error pop-up. It should close automatically at the next Run, if all errors have been corrected.

## Focus

Whenever a scene in the playground needs the use of keys to move an object, such as a mesh or camera, around then the rendering area needs to have the focus. After running the playground ensure that the render area has the focus by clicking inside it before using the keys.



# Utilities

These are JavaScript functions that can be added to your Babylon.js project if they are useful. Each is given a brief explanation and a Playground example of its use.

## Overview

The [Viewer Configurator](https://viewerconfig.babylonjs.com) is a tool that simplifies configuring the [Babylon Viewer](/features/featuresDeepDive/babylonViewer). Rather than relying on documentation and setting the html attributes of the `<babylon-viewer>` directly in your code editor, the Viewer Configurator gives you an interactive visual interface to configure every aspect of the Viewer. The output is a block of [html](#output-format) that you can copy and paste into your web app, or [json](#output-format) that you can use as the `ViewerOptions`.

## Accessing the Viewer Configurator

1. Open a web browser.
2. Visit the Viewer Configurator at [viewerconfig.babylonjs.com](https://viewerconfig.babylonjs.com).

## Loading Assets

Load a model into the Viewer Configurator using one of the following methods:

1. **URL**: Enter the url to a supported model type in the "Model" text input and click the confirm button to the right of the text input.
2. **File Selection**: Use the open file button to the right of the "Model" text input and browse the file system.
3. **Drag and Drop**: Drag supported files directly onto the Viewer Configurator interface.

<Alert severity="info">
Note that when using a local file, the output html simply includes the name of the file. You will need to set the `source` attribute to a valid model url when using the html snippet in your web app.
</Alert>

<Alert severity="info">
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 .gltf along with the .bin file and all image files must be dropped or selected for the asset to load properly.
</Alert>

## Configuration

Ideally the Viewer Configurator is self explanatory, but there are some complexities that will be covered in more detail below.

### Revert and Reset

In various places in the Viewer Configurator, you will see Revert and Reset buttons.

Revert means sync the live Viewer state with what you see in the html output (e.g. the current viewer configuration). For example, if an initial camera pose has been configured, but then you change the camera pose in the Viewer, reverting it will set the camera pose back to the configured pose as seen in the html output.

Reset means to remove the configuration entirely and reset to the default state. For example, if an initial camera pose has been configured, resetting the camera pose will remove that configuration *and* revert the camera pose to its default.

### Snapshotting Viewer State

Generally all Viewer configuration happens in the side pane of the Configurator. Usually this is done by manipulating UI such as toggles and sliders directly in the side pane. However some state is established directly in the Viewer. For example, to set the initial camera pose, you can position the camera to your liking in the Viewer, and then click the "Use Current Pose" button. This "snapshots" the current camera pose and adds it to the html snippet.

Similar behaviors exist for other Viewer features, like animation and material variants.

### Hot Spots

Creating and configuration [hot spots](/features/featuresDeepDive/babylonViewer/hotspots) is a multi-step process.

1. Required: Click the `+` button to add a new hot spot.
1. Optional: Update the hot spot name (make sure it is unique relative to other hot spots).
1. Required: Click the target button to the right of the hot spot name text input. You are now in picking mode.
1. Required: Click a point on the surface of the model. This establishes the position of the hot spot.
1. Optional: Rotate the camera around the hot spot to a desired camera pose and then click the camera button to the right of the hot spot name text input. This establishes a custom camera pose relative to the hot spot position.

When hot spots are added, they will immediately show up in the Viewer toolbar. Hot spots can be re-ordered by clicking and dragging the handle to the left of the hot spot name text input.

## Output Format

By default, the Viewer Configurator outputs html that can be copied and pasted into a web page. The output format can also be changed to json. In this case, the json can be parsed and directly used as `ViewerOptions` in any of the Viewer layers:

```ts
const configuration: string = "the copied and pasted output of the Viewer Configurator goes here";
const options: ViewerOptions = JSON.parse(configuration);
```

### `ConfigureCustomViewerElement`

The `ConfigureCustomViewerElement` function creates a configured `HTML3DElement` (`<babylon-viewer>`). For example, if you know you want the same skybox for multiple instances of the Babylon Viewer, this could be configured in the Configurator and the parsed `ViewerOptions` (as described above) could be used like this:

```ts
ConfigureCustomViewerElement("my-babylon-viewer", options);
```

```html

<my-babylon-viewer source="model1.glb"></my-babylon-viewer>
<my-babylon-viewer source="model2.glb"></my-babylon-viewer>
<my-babylon-viewer source="model3.glb"></my-babylon-viewer>
```

### `HTML3DElement` Constructor

If the Viewer element is being constructed in code, the same options can be passed to the constructor:

```ts
const viewerElement = new HTML3DElement(options);
document.body.appendChild(viewerElement);
```

### `CreateViewerForCanvas`

If a `Viewer` is being created without the html layer but from a `Canvas`, the options can be passed to the factory function:

```ts
const viewer = await CreateViewerForCanvas(canvas, options);
```

### `Viewer` Constructor

If a `Viewer` is being instantiated directly, the options can be passed to the constructor:

```ts
const viewer = new Viewer(engine, options);
```

## Saving & Loading

After the Viewer has been configured, you can also save the current state of the Viewer Configurator and restore this state later. This works the same as other Babylon tools: clicking the save button will save a "snippet" and encode the snippet id into the url. If you reload this url later, it will restore the currently configured state.

<Alert severity="info">
Note that if you have loaded a local model, that model is not saved with the snippet. You will have to reload the same local model after reloading the url.
</Alert>

## Testing

What you see in the Viewer Configurator should be exactly what you see when you use the html snippet in your own web app. An easy way to further test this is to copy the html output from the Viewer Configurator and paste it into this codepen:

<CodePen pen="ByaZQEp" tab="html,result" title="Viewer Configurator Test" />


# Tools and Resources

This section contains all sorts of handy information for developing in Babylon.js. From a rich set of tools to make development easier, to several free asset libraries for you to leverage in your scenes, this section is sure to help you make the most beautiful experiences possible, as quickly and efficiently as possible!



This document is for you if you are using a bundler like webpack or rollup to build your Babylon.js project. It will help you understand how to control async-loading of packages and chunks in Babylon.js.

If you don't mind how your app is built and simply trust that your bundler will provide you the required files to deploy your Babylon experience, no need to read further. If you found too many different files in your dist folder and it triggers your curiosity, continue reading!

## Introduction

Babylon.js has recently introduced async-loading to the framework. The main goal of this new architecture is to allow you, the developer provide your consumer the smallest package possible. This is achieved by splitting the framework into multiple load-able assets, and only loading them when needed.

The most split-feature we currently have in the framework si the separation of the different shader code between WebGL and WebGPU. When deciding what engine you are using, the framework will also "Decide" for you what files are loaded - from the shader processors to the different shaders, you will only load what you need.

Async-loading is a standard JavaScript feature, defined in the ECMAScript standard ([Import Calls](https://tc39.es/ecma262/multipage/ecmascript-language-expressions.html#sec-import-calls)), and is supported by all modern browsers. It allows you to load JavaScript files asynchronously, without blocking the main thread.

When using it in the browser, the files will simply be loaded when needed. But when you are using a bundler like webpack you will notice that the final dist folder will contain files that you might not have expected to see. This is because the bundler will try to optimize the loading of the files, and will split the files into chunks.

This article will explain how to control the generated chunks, how to configure your bundler to work according to your needs, and how to optimize your build to get the best package size and loading time, while still enjoying fully from babylon's features.

Note that this feature is only available in Babylon 7.15 and up, and only if you use the ES6 packages. Our UMD package will always be a single file without chunks.

## Example output

I will be using webpack here, but this is valid for any other bundler.

Let's say we are building a simple babylon project, using the default template found here - [babylonjs-webpack-es6](https://github.com/RaananW/babylonjs-webpack-es6).

If we simply build the project, we will notice the following files in the dist folder:

![List of files using the default build](/img/defaultDistFolder.png)

Each of these files represents an `import()` call in the framework. For example, this is a code snippet from our standard material:

```javascript
let effect = scene.getEngine().createEffect(
  shaderName,
  {
    attributes: attribs,
    uniformsNames: uniforms,
    uniformBuffersNames: uniformBuffers,
    samplers: samplers,
    defines: join,
    fallbacks: fallbacks,
    onCompiled: this.onCompiled,
    onError: this.onError,
    indexParameters,
    processFinalCode: csnrOptions.processFinalCode,
    processCodeAfterIncludes: this._eventInfo.customCode,
    multiTarget: defines.PREPASS,
    shaderLanguage: this._shaderLanguage,
    extraInitializationsAsync: this._shadersLoaded
      ? undefined
      : async () => {
          if (this._shaderLanguage === ShaderLanguage.WGSL) {
            await Promise.all([import("../ShadersWGSL/default.vertex"), import("../ShadersWGSL/default.fragment")]);
          } else {
            await Promise.all([import("../Shaders/default.vertex"), import("../Shaders/default.fragment")]);
          }
          this._shadersLoaded = true;
        },
  },
  engine,
);
```

Notice the `import()` calls in the `extraInitializationsAsync` function. Each of these calls will be transformed by the bundler into separate files, and will be loaded only when needed.

The rest of the files are many other parts of the framework, each split into its own file.

But you might not want all of them. The example we have above will generate 4 chunks - two for the vertex and fragment shaders, in both webgl and webgpu. If you want to control the number of files generated, you will need to configure your bundler accordingly.

## Configuring different bundlers

### Webpack

Webpack allows you to fully configure your chunks. You can control the files added to a single chunk, the amount of chunks in your project, and even the name of the files. The full documentation for the feature can be found in the [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/) available per default in webpack 5.

Let's get a simple webpack configuration that takes all WebGL shaders and packs them all together in a single file. First, let's change slightly the output configuration:

```javascript
output: {
        filename: "js/[name].js",
        // ... further configuration
    },
```

So now we just need to define the name of each chunk, and what files go into it. We can do that by using the `optimization.splitChunks.cacheGroups` configuration:

```javascript
{
// ... webpack configuration
    optimization: {
        splitChunks: {
            cacheGroups: {
                webgpuShaders: {
                    name: "webgpu-shaders",
                    chunks: "all",
                    priority: 50,
                    enforce: true,
                    test: (module) => /\/ShadersWGSL\//.test(module.resource),
                },
                webglShaders: {
                    name: "webgl-shaders",
                    chunks: "all",
                    priority: 50,
                    enforce: true,
                    test: (module) => /\/Shaders\//.test(module.resource),
                },
                webgpuExtensions: {
                    name: "webgpu-extensions",
                    chunks: "all",
                    priority: 50,
                    enforce: true,
                    test: (module) => /\/WebGPU\//.test(module.resource),
                },
                babylonBundle: {
                    name: "babylonBundle",
                    chunks: "all",
                    priority: 30,
                    reuseExistingChunk: true,
                    test: (module) => /\/node_modules\/@babylonjs\//.test(module.resource),
                },
            },
        },
        usedExports: true,
        minimize: true,
    },
}
```

Now we have the following files generated:

![Webpack list of files after optimization](/img/webpackChunksConfiguration.png.png)

We have webgpu shaders, webgl shaders, webgpu extensions and our babylon bundle. The "main.js" file is the actual project code.

#### Ignoring certain files

Let's say we don't want the webgpu shaders at all. We want to completely ignore them. To do that we can use a different webpack feature, the `IgnorePlugin`. We can add the following to our plugins array:

```javascript
new webpack.IgnorePlugin({
    resourceRegExp: /ShadersWGSL/,
    // optionally:
    contextRegExp: /@babylonjs/,
}),
```

Now the webgpu-shaders bundle will not be generated.

#### Preventing chunks altogether

If you want to prevent the generation of chunks altogether, you can use the included webpack [limit chunks plugin](https://webpack.js.org/plugins/limit-chunk-count-plugin/). This plugin will allow you to limit the number of chunks generated. If you set it to 1, you will have a single file generated:

```javascript
{
    plugins: [
        // ... other plugins
        new webpack.optimize.LimitChunkCountPlugin({
            maxChunks: 1,
        }),
    ],
}
```

### Rollup

Note - this is also valid for vite, as it is using rollup under the hood

Rollup is a bit different than webpack, but it also allows you to control the chunks generated.
The equivalent of the webpack configuration above would be:

```javascript
export default {
  // ...
  output: {
    dir: "output",
    manualChunks: (id) => {
      if (id.includes("ShadersWGSL")) {
        return "webgpu-shaders";
      } else if (id.includes("Shaders")) {
        return "webgl-shaders";
      } else if (id.includes("WebGPU")) {
        return "webgpu-extensions";
      } else if (id.includes("babylonjs")) {
        return "babylonjs";
      }
    },
  },
};
```

This will generate the same 5 chunks as the webpack configuration above.

#### Preventing chunks altogether in rollup

To do that simply set the manual chunks of `@babylonjs/core` to a single file:

```javascript
export default {
  // ...
  output: {
    dir: "output",
    manualChunks: (id) => {
      if (id.includes("babylonjs")) {
        return "babylonjs";
      }
    },
  },
};
```

or simpler:

```javascript
export default {
  // ...
  output: {
    dir: "output",
    manualChunks: {
      babylonjs: ["@babylonjs/core"],
    },
  },
};
```
