
This page will walk you through the 3D Commerce Viewer Certification Program, what it is, and how to get a certified viewer version based on the Babylon.js engine.

## 3D Commerce Viewer Certification Program

3D visualization technologies, initially developed for gaming and visual effects, are beginning to transform online retail experiences, advertising, and even physical retail experiences with AR/VR. 3D Commerce is a standardization working group within the [**Khronos Group**](https://www.khronos.org/) that aims to remove the barriers to deploying 3D in e-commerce. 

The Viewer Certification Program enables 3D viewers across the industry to demonstrate that they can accurately and consistently display 3D products, clearing the way for reliable 3D and AR-powered shopping across multiple platforms and devices.

![3D Viewer Certification Program Overview (source: Khronos Web site)](/img/how_to/3D-commerce-certif/2021-3dcommerce-certification-overview.webp)

This program is still in its early days, and as a member of this working group, the Babylon.js team is fully engaged in helping to develop it and support its adoption. More info is available on the [**3D Commerce website**](https://www.khronos.org/3dcommerce/).

## Babylon.js Sandbox - certified version

A special version of the [**Babylon.js Sandbox**](https://sandbox.babylonjs.com) has been certified because some parameters have to be set differently than the default engine values (which cannot be changed for backward compatibility reasons):

- Specular over alpha has to be turned off (right side of the picture below). It was being used to render glass before the apparition of dedicated glTF extensions such as transmission and volume.
  ![Specular over alpha turned-on (left) and off (right)](/img/how_to/3D-commerce-certif/specular-over-alpha.webp)

- Tone mapping is enabled using `Khronos PBR Neutral`. See [here](https://www.khronos.org/news/press/khronos-pbr-neutral-tone-mapper-released-for-true-to-life-color-rendering-of-3d-products) for more info about this tone mapping technique.

This 3D Commerce certified Babylon.js Sandbox is accessible here: [**https://3dcommerce.babylonjs.com**](https://3dcommerce.babylonjs.com)

## Certified viewer version based on Babylon.js engine

If you have an existing viewer, or are developing one, based on the Babylon.js engine, you can get a certified viewer version by:

- Setting a flag in the glTF loader to enable transparency as coverage which will turn off specular over alpha:
  ```JavaScript
  SceneLoader.OnPluginActivatedObservable.add((plugin) => {
      if (plugin.name === "gltf") {
          const loader = plugin as GLTFFileLoader;
          loader.transparencyAsCoverage = true;
      }
  });
  ```

- Enabling the `Khronos PBR Neutral` tone mapping for a scene:
  ```JavaScript
  scene.imageProcessingConfiguration.toneMappingEnabled = true;
  scene.imageProcessingConfiguration.toneMappingType = ImageProcessingConfiguration.TONEMAPPING_KHR_PBR_NEUTRAL;
  ```

The certification program will likely evolve with the glTF format and with new extensions being taken into account. If some changes are not backward compatible, we'll make sure to continue documenting them on this page.



This tutorial:

- Is for you if you have no or limited experience with web development or servers in general.
- Will show you how to set up and start a simple, local Node.js web server for your Babylon.js application.
- Is primarily focused on Windows.

## Nodejs & NPM

If you already have Node.js and NPM installed, skip to the **Sample** section.

Download the latest LTS Node.js installer from https://nodejs.org/en/download/

Run the installer and follow the Node.js setup wizard. The default settings are fine for our use.

NPM is included in this installation.

## Sample

Now that Node.js and NPM are installed, we're ready for the server code.

- Create a folder for your project.

In this tutorial, we'll use **C:\babylon**

- Download the sample server [master.zip](https://github.com/aWeirdo/babylonJs_sample_server/archive/master.zip)
- Extract the .zip file contents to C:\babylon.

Your **C:\babylon** folder should now look something like this:

```shell
C:\babylon\public\
C:\babylon\public\index.html
C:\babylon\public\babylonScene.js

C:\babylon\package.json
C:\babylon\readme.md
C:\babylon\server.js
C:\babylon\Windows_NPM_INSTALL.BAT
C:\babylon\Windows_START.BAT

```

**On Windows**

- In File Explorer, navigate to C:\babylon.
- Double-click **Windows_NPM_INSTALL.BAT**
- Wait for the BAT window to finish running and close itself. This executes `npm install --save`.

A new `node_modules` folder should be created.

- Double-click **Windows_START.BAT**. This executes `node server.js`
- A new BAT window should open:

```shell
C:\babylon>node server.js
Server is listening on port 80
```

- Your server should now be running. Note: Closing this window will shut down the Node.js server again.
- In your browser, navigate to http://localhost/
- If the BAT file closes immediately, please check that the previous steps were completed correctly.
- To view errors, in a CMD or PowerShell window run `C:\babylon> node server.js`

**Other OSes**

- See the npmjs.org and nodejs.org documentation for instructions.
- Execute "npm install --save" on C:\babylon
- Execute "node server.js" on C:\babylon

_If anyone wishes to expand this section, feel free to open a PR._

## Public Folder

In the Public folder, you'll find a sample scene consisting of an _index.html_ file and a _babylonScene.js_ file.

The browser's access is restricted to this folder and its files and subfolders.

You're now ready to start your project.



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 do not mind how your app is built and simply trust that your bundler will provide the required files to deploy your Babylon experience, there is no need to read further. If you found too many different files in your `dist` folder and that sparked your curiosity, continue reading!

## Introduction

Babylon.js recently introduced async loading to the framework. The main goal of this new architecture is to help you, the developer, provide your users with the smallest package possible. This is achieved by splitting the framework into multiple loadable assets and loading them only when needed.

The most heavily split feature we currently have in the framework is the separation of shader code between WebGL and WebGPU. When the framework determines which engine you are using, it also decides which files to load. From the shader processors to the shaders themselves, you 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 are simply loaded when needed. But when you use a bundler like webpack, you will notice that the final `dist` folder contains files you might not have expected to see. This is because the bundler tries to optimize file loading and splits the files into chunks.

This article explains how to control the generated chunks, how to configure your bundler to match your needs, and how to optimize your build for the best package size and loading time while still taking full advantage of 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 use webpack here, but the same ideas apply to other bundlers.

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.webp)

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 above generates four chunks: two for the vertex and fragment shaders, for both WebGL and WebGPU. If you want to control the number of generated files, you need to configure your bundler accordingly.

## Configuring different bundlers

### Webpack

Webpack lets you fully configure your chunks. You can control which files are added to a single chunk, how many chunks your project has, and even the names of the files. Full documentation for this feature is available in the [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/), which is included by default in webpack 5.

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

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

Now we just need to define the name of each chunk and which files go into it. We can do that with 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 now have WebGPU shaders, WebGL shaders, WebGPU extensions, and our Babylon bundle. The `main.js` file contains 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 chunk generation altogether, you can use the included webpack [LimitChunkCountPlugin](https://webpack.js.org/plugins/limit-chunk-count-plugin/). This plugin lets you limit the number of generated chunks. If you set it to 1, only a single file is generated:

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

### Rollup

Note: this also applies to Vite, as it uses Rollup under the hood.

Rollup is a bit different from webpack, but it also allows you to control the generated chunks.
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 for `@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"],
    },
  },
};
```



To create the minified version of Babylon.js, run `npm run build:babylonjs`.

The files will be available in `packages/public/umd/babylonjs`.

If you want to build the entire framework, use `npm run build:umd` or `npm run build:es6`, depending on the flavor you want to build. The packages will be available in `packages/public/FLAVOR`.



## Debugging and Profiling with PIX

[PIX](https://devblogs.microsoft.com/pix/) is a performance tuning and debugging tool from Microsoft for DirectX-based applications on Windows. It allows you to capture and analyze GPU workloads, inspect draw calls, profile frame timing, and debug shaders. When used with Babylon.js running on a WebGPU-enabled browser such as Chrome, PIX provides deep visibility into the rendering pipeline, helping you identify performance bottlenecks, verify that GPU resources are being used efficiently, and diagnose visual artifacts at the API level.

![Babylon.js PIX 0](/img/pix/pix-ui-0.webp)

![Babylon.js PIX 1](/img/pix/pix-ui-1.webp)

## Prerequisites

<Alert severity="info" title="Version Note" description="These instructions were tested with PIX 2601.15 and Chrome 145. Steps and appearance may vary slightly with different versions of PIX or Chrome."/>

Install PIX 2601.15:  
https://devblogs.microsoft.com/pix/download/

Download the WinPixEventRuntime NuGet package, unzip `winpixeventruntime.*.nupkg`, and copy the `bin\x64\*.dll` files into your `<Chrome Installation Directory>` (usually `C:\Program Files\Google\Chrome\Application\`):  
https://www.nuget.org/packages/WinPixEventRuntime

<Alert severity="warning" title="Modifying Chrome Installation" description="This step requires administrator permissions. The DLLs must be recopied after each Chrome update, as updates replace the installation directory contents. Remove them when PIX is no longer needed."/>

## Setting Up the Environment

Enable developer settings in the NVIDIA Control Panel:

![NVIDIA Control Panel](/img/pix/pix-nvcp-0.webp)

Allow access to GPU counters:

![NVIDIA Control Panel](/img/pix/pix-nvcp-1.webp)

Enable Developer Mode in Windows Settings:

![Windows Settings](/img/pix/pix-win-settings.webp)

## Launching the Process

Launch PIX with **administrator privileges** (right-click and select "Run as administrator"). This is required for PIX to access GPU hardware counters and inject into the Chrome GPU process.

![PIX As Administrator](/img/pix/pix-as-admin.webp)

In PIX, select **Launch Process** from the home screen and configure it with the following settings:

![PIX Launch Process](/img/pix/pix-launch-process.webp)

**Executable Path:** `<Chrome Installation Directory>/chrome.exe`

**Working Directory:** `<Chrome Installation Directory>`

**Command Line Args:** `--incognito --disable-gpu-sandbox --disable-gpu-watchdog --disable-direct-composition --enable-dawn-features=emit_hlsl_debug_symbols,disable_symbol_renaming https://playground.babylonjs.com/?inspectorv2=true&engine=webgpu#DR9MT2#35`

<Alert severity="warning" title="Security and Stability Warning" description="This Chrome command line disables the GPU sandbox and GPU watchdog, which weakens browser security and can impact stability. Use these flags only with trusted content."/>

<Alert severity="info" title="WebGPU Engine" description="The URL includes the query parameter engine=webgpu, which forces the Babylon.js Playground to use the WebGPU engine instead of the default WebGL. This is required for PIX to capture DirectX-level GPU activity."/>

<Alert severity="info" title="WebGL Engine" description="If you need to debug the WebGL engine instead, enable the Force D3D11On12 option in PIX's launch settings to route DirectX 11 calls through DirectX 12, making them visible to PIX."/>

| Chrome option used to launch | Description |
| --- | --- |
| `--incognito` | Launches Chrome in incognito mode so that extensions and cached state do not interfere with the capture. |
| `--disable-gpu-sandbox` | Disables the GPU process sandbox, allowing PIX to inject into and communicate with the GPU process. |
| `--disable-gpu-watchdog` | Prevents Chrome from killing the GPU process when a frame takes too long, which is common while PIX is capturing or single-stepping through draw calls. |
| `--disable-direct-composition` | Disables Windows DirectComposition, forcing Chrome to use a swap chain that PIX can intercept for frame capture. |
| `--enable-dawn-features=emit_hlsl_debug_symbols,disable_symbol_renaming` | Enables Dawn (Chrome's WebGPU implementation) features: **emit_hlsl_debug_symbols** includes debug information in the generated HLSL shaders, and **disable_symbol_renaming** preserves original variable and function names so they are readable in PIX's shader debugger. |

## GPU Capture

A GPU capture records a single frame of rendering activity, letting you inspect every draw call, resource binding, and pipeline state in detail. After launching Chrome through PIX, click the **GPU Capture** button (camera icon) on the PIX toolbar to capture the current frame. Once the capture completes, PIX opens an analysis view where you can step through each API call, examine textures and buffers at any point in the frame, and debug shaders directly.

![PIX GPU Capture](/img/pix/pix-gpu-capture.webp)

## Timing Capture

A timing capture profiles GPU and CPU activity over a span of multiple frames, giving you a timeline view of how work is distributed. Unlike a GPU capture, a timing capture requires you to manually attach to the correct Chrome process. Launch the process as described above, then use **Attach to Process**:

![PIX Timing Capture Configuration Windows](/img/pix/pix-timing-capture.webp)

Select the Chrome process whose command line contains `--type=gpu-process`.

![PIX Attach To Process Dialog](/img/pix/pix-attach.webp)

Once attached, click the **Timing Capture** button (stopwatch icon) on the PIX toolbar to begin recording, let the scene run for the desired duration, then click the button again to stop. The resulting timeline shows GPU queue utilization, command list execution, and hardware counter data, making it straightforward to identify bottlenecks such as GPU-bound passes, excessive state changes, or pipeline stalls.

![PIX Toolbar With Timing Capture](/img/pix/pix-start-capture.webp)

## Additional Resources

This article covers how to set up PIX for use with Babylon.js and WebGPU. For a deeper understanding of PIX itself — including how to navigate captures, interpret timeline data, and debug shaders — the following Microsoft resources are great starting points.

Analyzing frames with GPU captures  
https://learn.microsoft.com/en-us/windows/win32/direct3dtools/pix/articles/gpu-captures/pix-gpu-captures

Timing Captures - The Timeline layout  
https://learn.microsoft.com/en-us/windows/win32/direct3dtools/pix/articles/timing-captures/layouts/pix-timing-captures-timeline-layout

Videos showing how to use the PIX on Windows tool for performance tuning and debugging DirectX 12 games  
https://www.youtube.com/playlist?list=PLeHvwXyqearWuPPxh6T03iwX-McPG5LkB



Starting with Babylon.js v3.1, we introduced the NullEngine, which is a version of the main Babylon.js engine that does not require a WebGL-capable device.

The NullEngine does not produce any rendering and can therefore be used in a Node.js or server-side environment.

It can be used to:

- Run tests
- Run a server-side version of your application or game
- Use specific Babylon.js services, such as glTF loaders

## General

To use a headless version of Babylon.js, just run:

```javascript
var engine = new BABYLON.NullEngine();
var scene = new BABYLON.Scene(engine);
```

If you want to use it in a Node.js environment, you may need to add some additional resources, such as support for XHR:

First install babylonjs and babylonjs-loaders: `npm install babylonjs babylonjs-loaders`

Then use this code:

```javascript
var BABYLON = require("babylonjs");
var LOADERS = require("babylonjs-loaders");
global.XMLHttpRequest = require("xhr2").XMLHttpRequest;

var engine = new BABYLON.NullEngine();
var scene = new BABYLON.Scene(engine);

var light = new BABYLON.PointLight("Omni", new BABYLON.Vector3(20, 20, 100), scene);

var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 100, BABYLON.Vector3.Zero(), scene);

BABYLON.ImportMeshAsync("https://playground.babylonjs.com/scenes/skull.babylon", scene).then(function ({ meshes }) {
  camera.target = meshes[0];

  console.log("Meshes loaded from babylon file: " + meshes.length);
  for (let index = 0; index < meshes.length; index++) {
    console.log(meshes[index].toString());
  }

  BABYLON.ImportMeshAsync("https://www.babylonjs.com/assets/DamagedHelmet/glTF/DamagedHelmet.gltf", scene).then(function ({ meshes }) {
    console.log("Meshes loaded from gltf file: " + meshes.length);
    for (let index = 0; index < meshes.length; index++) {
      console.log(meshes[index].toString());
    }
  });

  console.log("render started");
  engine.runRenderLoop(function () {
    scene.render();
  });
});
```

## Configuration

You can specify some options in the `NullEngine` constructor:

```javascript
const engine = new BABYLON.NullEngine({
    renderWidth: 512,
    renderHeight: 256,
    textureSize: 512
});
```

With `renderWidth` and `renderHeight`, you can define the size of the virtual canvas used to simulate the render surface.
With `textureSize`, you can define the size of all textures, which will all be black, used by the NullEngine.

## Troubleshooting

While the goal of the NullEngine is to completely replace the `Engine` class, some features cannot be used server-side:

- `camera.attachControl` cannot be used as it requires an HTML element
- `DynamicTexture` cannot be used as it relies on HTML canvas

Furthermore, as mentioned earlier, you need to provide an implementation of the `XMLHttpRequest` class.



# Visual Studio Code

VSCode is one of several integrated development environments that can be used to develop Babylon.js projects. It has built-in Git integration and a plugin for displaying `.babylon` files.

You can install VSCode from its site: [https://code.visualstudio.com/](https://code.visualstudio.com/)

## Useful plugins

Once installed, a few plugins will help you have the best experience. You can search for them in the Extensions view (default shortcut: Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS):

1. [Shader languages support for VSCode](https://marketplace.visualstudio.com/items?itemName=slevesque.shader) for syntax highlighting and autocompletion in GLSL shaders
2. [Babylon.js file viewer](https://marketplace.visualstudio.com/items?itemName=julianchen.babylon-js-viewer) can be used to display the contents of a `.babylon` file directly in VSCode. It can be useful if you want to quickly check whether your artist did a good job with an object and its names :)

## Keybindings setup

Finally, I would recommend adding a few shortcuts to your environment. Follow the [guide](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings):

1.  To configure keyboard shortcuts the way you want, go to the menu under File > Preferences > Keyboard Shortcuts. (Code > Preferences > Keyboard Shortcuts on Mac)
2.  Click ```Open Keyboard Shortcuts (JSON)``` on the right side and add:

```
// Place your key bindings in this file to overwrite the defaults
[
    { "key": "ctrl+shift+alt+s", "command": "workbench.action.files.saveFiles" },
    { "key": "ctrl+shift+alt+k", "command": "workbench.action.tasks.terminate" },
    { "key": "ctrl+shift+alt+t", "command": "workbench.action.tasks.test" },
    { "key": "ctrl+shift+alt+l", "command": "workbench.action.tasks.showLog" },
    { "key": "ctrl+shift+alt+r", "command": "workbench.action.tasks.runTask" }
]
```

This will make the main commands quicker to access. Do not hesitate to adapt the bindings to your preferences.

![keybindings](/img/how_to/howToStart/keybindings.webp)

## Debugging code

VSCode also has a `Run and Debug` tab in the left pane. Select the launch configuration you want to use, then press the `Start Debugging` button (F5).

With the test task running from the VSCode `Run and Debug` tab, choose the section you want to debug and launch the debugger.

The debug session will debug all the TypeScript and JavaScript in Chrome and stop on your breakpoints set up in files in VSCode. It debugs all the code from src, materialsLibrary, proceduralTexturesLibrary, postprocessLibrary, etc.

_Hint_: If another Chrome session is already running with remote debugging on port 9222, the debugger will fail to attach because the port is already in use. You will need to close the other remote debugging session first.



## Introduction

Starting with v3.0, Babylon.js supports rendering with both WebGL1 and WebGL2 contexts.
This support is transparent to developers. By default, the engine tries to get a WebGL2 context. If none is available, it falls back to a WebGL1 context.

You can check which version of WebGL is enabled with the `engine.webGLVersion` property.

## Shaders

When WebGL2 is enabled, the shaders are automatically converted to [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) v3.0. Babylon.js will then automatically take advantage of extended instruction/uniform counts.

If you are using custom shaders, the best approach is to provide [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) v2.0 shaders. This way, your code will work on both contexts.
You can, of course, provide only v3.0 shaders, but in that case your code will work only when WebGL2 is enabled.

## Supported features

You can find the list of supported features and backward-compatibility options, when available, here:

| Feature                      | Description                                                                                                                                                                                                                                        | WebGL1 compatibility                                                                                          | Demo                                                                                                             | More info                                                                |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Depth Frag                   | Used to compute logarithmic depth buffer                                                                                                                                                                                                           | Yes through an [extension](https://www.khronos.org/registry/webgl/extensions/EXT_frag_depth/)                 | <Playground id="#1180R5#15" title="Depth Frag" description="Depth Frag"/>                               | [Documentation](/features/featuresDeepDive/materials/advanced/logarithmicDepthBuffer) |
| Multisample render targets   | Rendertarget textures can be multisampled to get antialiasing effect                                                                                                                                                                               | No. Has no effect on WebGL1 context                                                                           | <Playground id="#12MKMN" title="Multisample Render Targets" description="Multisample render targets."/> | [See below](/setup/support/webGL2#multisample-render-targets)          |
| Standard derivatives         | Standard derivatives are used in Babylon.js to help compute real-time bump mapping                                                                                                                                                                 | Yes through an [extension](https://www.khronos.org/registry/webgl/extensions/OES_standard_derivatives)        | [Demo](https://www.babylonjs.com/Demos/Bump/)                                                                    | [Documentation](/features/featuresDeepDive/materials/using/moreMaterials)             |
| Texture LOD                  | Used by PBRMaterial to simulate microsurface                                                                                                                                                                                                       | Yes through an [extension](https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_shader_texture_lod.txt) | [Demo](/features/featuresDeepDive/materials/using/HDREnvironment)                                                             | [Documentation](/features/featuresDeepDive/materials/using/introToPBR)                |
| Vertex array objects (VAO)   | A Vertex Array Object (or VAO) is an object that describes how the vertex attributes are stored in a Vertex Buffer Object (or VBO)                                                                                                                 | Yes through an [extension](https://www.khronos.org/registry/webgl/extensions/OES_vertex_array_object/)        | N/A. Every rendering is done with VAO by default                                                                 | [See below](/setup/support/webGL2#vertex-array-objects)                |
| Uniform buffer objects (UBO) | A uniform buffer object (or UBO) lets you specify a group of uniforms from a buffer                                                                                                                                                               | No. Uniforms are handled independently on a WebGL1 context                                                    | N/A. Materials supporting UBO automatically use them                                                             | [See below](/setup/support/webGL2#uniform-buffer-objects)              |
| Multiple Render Target (MRT) | Several Render Targets can be rendered in the same draw call.                                                                                                                                                                                      | Yes through an [extension](https://www.khronos.org/registry/webgl/extensions/WEBGL_draw_buffers)              | <Playground id="#NZ6P07" title="Multiple Render Target" description="Multiple Render Target"/>          | [See below](/setup/support/webGL2#multiple-render-target)              |
| Occlusion Queries            | Occlusion queries detect whether a Mesh is visible in the current scene or not                                                                                                                                                                     | Yes through an [extension](https://www.khronos.org/opengl/wiki/Query_Object#Occlusion_queries)                | <Playground id="#QDAZ80#646" title="Occlusion Queries" description="Occlusion Queries"/>                  | [See below](/setup/support/webGL2#occlusion-queries)                   |
| 3D Textures                  | 3D textures are textures with a 3rd dimension. You can see them as multiple 2D textures where every texture is a slice in the 3d texture.                                                                                                          | No. Cannot be created in WebGL1                                                                               | This feature will automatically be used when possible.                                                           | [See below](/setup/support/webGL2#3d-textures)                         |
| 2D Array Textures            | 2D array textures are very similar to 3D textures but are designed for constructing a texture atlas instead of a volumetric texture.                                                                                                               | No. Cannot be created in WebGL1                                                                               | <Playground id="#XEVUD9" title="2D Array Textures" description="2D Array Textures"/>                    | [See below](/setup/support/webGL2#2d-array-textures)                   |
| Power of two textures        | In the past, to achieve the best performance and higher quality texture rendering, images with dimensions that are a power of two were required. With support for WebGL2 this is no longer the case, any sized texture will be rendered optimally. | Yes, however Babylon will resize textures to be a power of two causing a hit to performance                   | N/A. This is done by default                                                                                     | [See below](/setup/support/webGL2#power-of-two-textures)               |
| Transform feedback buffer    | Transform feedback buffer can be used to update vertex buffers from GPU. Babylon.js uses it to implement GPU particles                                                                                                                             | No. Not supported on WebGL1                                                                                   | <Playground id="#PU4WYI" title="Power Of Two Textures" description="Power Of Two Textures"/>            | [See particles documentation](/features/featuresDeepDive/particles/particle_system/particle_system_intro#gpu-particles)       |
| Shadow Samplers              | Shadow samplers are used to enable PCF depth comparison on the hardware. Babylon.js uses it to implement PCF and PCSS shadows.                                                                                                                     | No. Not supported on WebGL1 (shadows fall back to poisson sampling)                                           | <Playground id="#ZT8BKT#57" title="Shadow Samplers" description="Shadow Samplers"/>                      | [See shadows documentation](/features/featuresDeepDive/lights/shadows)                         |
| More precise shadows         | Shadow maps can now use 32 bits depth buffers improving by a large scale the precision of the shadows.                                                                                                                                             | No. Not supported on WebGL1 (shadows precision will fall back to 16 bits)                                     | <Playground id="" title="#ZT8BKT#57More Precise Shadows" description="More Precise Shadows"/>            | [See shadows documentation](/features/featuresDeepDive/lights/shadows)                         |

## Multisample render targets

By default, render targets, such as mirrors, are created without support for multisampling. To turn it on, set `renderTarget.samples` to a value greater than 1.
On a WebGL1 context, this does nothing. On a WebGL2 context, it enables multisampling. More samples imply better antialiasing but slower rendering.

Here is an example of a mirror (512x512) with and without multisampling:

| No MSAA (1 sample)                 | MSAA (8 samples)                 |
| ---------------------------------- | -------------------------------- |
| ![Title](/img/features/nomsaa.webp) | ![Title](/img/features/msaa.webp) |

## Vertex array objects

When possible, either on a WebGL2 context or when the extension is available on a WebGL1 context, Babylon.js uses VAOs to control rendering. VAOs are a kind of geometry object. Instead of sending all the attributes and buffers used by a mesh—one for position, one for normal, one for indices, one for texture coordinates, and so on—you can build a VAO that keeps track of all the attributes and buffers used.

At render time, you only need to bind one VAO instead of multiple VBOs (vertex buffer objects).

You can find more details on [Tojicode's blog](http://blog.tojicode.com/2012/10/oesvertexarrayobject-extension.html).

## Uniform buffer objects
On a WebGL1 context, all uniforms are sent to the GPU independently. This means that if your shader uses 16 matrices, you will call the WebGL API 16 times to update them before using your shader.

On a WebGL2 context, you can use a UBO to set the values in a typed array in JavaScript. This is much faster. Once all the values are set, you can send them to the GPU with a single call.

You can find more details on [WebGL 2 specification](https://www.khronos.org/registry/webgl/specs/latest/2.0/#3.7.16)

## Multiple Render Target

With WebGL1, one draw call meant one target texture. Now you can bind several target textures to a shader and specify in the fragment shader which colors to write to each texture. This saves a lot of CPU time and enables advanced effects like [Deferred Shading](https://fr.wikipedia.org/wiki/Deferred_Shading).

In Babylon.js, our first use of this technique is to render a geometry buffer of the scene.

## Occlusion queries

Occlusion queries detect whether a mesh is visible in the current scene, and based on that result the mesh is drawn or not. Occlusion queries are useful when you have an expensive object in the scene and want to make sure it is drawn only if it is visible to the camera and not behind an opaque object. Babylon.js provides an implementation for occlusion queries through the `occlusionType` property on the `AbstractMesh` class.

[Babylon.js Occlusion Queries Feature](/features/featuresDeepDive/occlusionQueries)

[WebGL 2 Occlusion Queries](https://www.khronos.org/opengl/wiki/Query_Object#Occlusion_queries)

## 3D textures

3D textures are mostly used for volumetric effects like color grading, fire, and smoke. WebGL 2 support for 3D textures is as good as its support for 2D textures.

So far, Babylon.js uses them for color grading textures: <Playground id="#17VHYI#2" title="3D Textures Example" description="Simple example of using 3D textures."/>

## 2D array textures

2D array textures allow you to pass a texture atlas to a custom shader. This could be used whenever you have multiple, distinct, 2D textures that you want to blend or switch between inside your shader. For example tiles, terrain splatting or frames of an animation. Using array textures ensures that distinct layers are sampled _as if_ they were separate textures, so there will be no bleeding between different sections of the atlas.

Usage is very similar to 3D textures: create a `RawTexture2DArray`, use `setTexture` on the shader material, and use a sampler of type `sampler2DArray`. Sample using `texture(yourSampler, vec3(u,v,layerIndex))` where `layerIndex` is a 0-based index into the array.

More information is available on the [Khronos wiki](https://khronos.org/opengl/wiki/Array_Texture).

<Playground id="#XEVUD9" title="2D Array Textures Example" description="2D Array Textures Example"/>

## Power of two textures

On WebGL1 context, all textures are resized to a power of two to produce the best quality. This resize may impact performance.

On WebGL2 context, no resize is required and any size texture will be rendered with the best quality.

You can find more details on [WebGL 2 specification](https://www.khronos.org/registry/webgl/specs/latest/2.0/#4.1.3)



## Introduction
Since the Babylon.js 5.0 release in May 2022, WebGPU support has been available and backward compatible with the WebGL implementation of the engine. It was a huge milestone after many iterations on the specification from the [GPU for the Web Working Group](https://github.com/gpuweb/gpuweb), along with close collaboration with the teams implementing WebGPU in browsers. In 2024, we also rewrote all core engine shaders in native WGSL to avoid the use of TintWASM in full WGSL applications.

![Inspector](/img/extensions/WebGPU.webp)

### Benefits of WebGPU
The promise behind [WebGPU](https://developer.chrome.com/en/docs/web-platform/webgpu/#what) is a faster API, provided through lower-level control over system graphics resources from JavaScript, along with new capabilities. We hope to bring these improvements to developers so they can create even higher-quality 3D web games and experiences through a tool they are already familiar with: Babylon.js.

Some features WebGPU brings to the table are:
* Compute shaders
* Ray tracing ([in-progress](https://github.com/gpuweb/gpuweb/issues/535))
* Improved performance across the board
* and more...

## Progress

See the [dedicated progress page](/setup/support/webGPU/webGPUStatus).

The current implementation of WebGPU is merged in the main branch of the Babylon.js [GitHub repository](https://github.com/BabylonJS/Babylon.js).

WebGPU is also supported by [Node Material and can be defined in the editor](/features/featuresDeepDive/materials/node_material/nodeMaterial#using-node-material-with-webgl-and-webgpu).

## Migration of Existing Games and Apps
Because backward compatibility is one of our pillars, the only difference is that engine initialization must be asynchronous:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas);
await engine.initAsync();
```

## Canvas tone mapping and output color space

The [`WebGPUEngineOptions`](/typedoc/interfaces/BABYLON.WebGPUEngineOptions) interface can pass tone-mapping and color-space settings to the browser's WebGPU canvas:

- `canvasToneMapping` accepts `{ mode: "standard" }` or `{ mode: "extended" }`. If you omit it, the browser uses standard tone mapping.
- `canvasColorSpace` accepts `"srgb"` or `"display-p3"`. If you omit it, the browser uses sRGB.

The following example requests extended tone mapping and Display P3 output:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas, {
    swapChainFormat: "rgba16float",
    canvasToneMapping: { mode: "extended" },
    canvasColorSpace: "display-p3",
});
await engine.initAsync();
```

Extended tone mapping can present HDR output, but the canvas setting alone does not create an HDR image. It requires the `"rgba16float"` swap-chain format, support from the browser and display, and a rendering pipeline that keeps color values above 1. It does not replace tone mapping in materials or post-processes.

Display P3 changes how the browser interprets output color values. It does not convert the scene's colors to Display P3. The rendering pipeline must produce the correct values for that color space.

Babylon.js uses these settings again whenever it configures the canvas context. Existing applications that omit them keep the browser's standard tone-mapping and sRGB defaults.

## Is WebGL still supported?
Yes! Support for WebGL and WebGPU is maintained side by side for the foreseeable future.

## WebXR support

Babylon.js supports experimental WebGPU-backed WebXR through `XRGPUBinding`. WebGPU support alone does not imply WebGPU-XR support: check the target immersive session mode and `WebXRSessionManager.IsWebGPUXRSupported` separately. The WebGPU-XR getter verifies both the projection binding APIs and `XRGPUSubImage.prototype.getViewDescriptor`, which Babylon requires when creating projection texture views.

A WebGPU engine intended for XR must be created with `new WebGPUEngine(canvas, { xrCompatible: true })`, and the WebXR Layers feature must be enabled before entering XR. Because Babylon cannot swap an existing WebGPU scene to WebGL, choose the engine before creating the scene and its resources. See [WebGPU in WebXR](/features/featuresDeepDive/webXR/webGPUXR) for setup, fallback guidance, and current limitations.

## Testing WebGPU
You can refer to [this page](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status) for detailed information on browser support.

Assuming you are using a browser that supports WebGPU, you can try it out yourself in the [Playground](https://playground.babylonjs.com/).

![WebGPU](/img/extensions/webGPUPlayground.webp)

All demo code is available on [GitHub](https://github.com/BabylonJS/Website/tree/master/build/Demos/WebGPU), so you can compare the WebGL and WebGPU versions and note that there are currently no differences besides initialization. We will try to keep it this way. :-)



## Customize Your Build

The workloads you may have known were removed in 4.0.0 in favor of [ES6 packages](/setup/frameworkPackages/npmSupport#es6). You no longer need to customize the build output, because you can rely on [tree shaking](https://webpack.js.org/guides/tree-shaking/) with our npm packages.



# Developing With and For Babylon.js

For those of you who want to know more about the organization and structure of Babylon.js so you can either build well-structured projects of your own or contribute to it, you have come to the right place. Here you will find where to obtain Babylon.js in full or just the modules you need to import into your JavaScript or TypeScript application.

Even the best developers need help from time to time, and the Babylon.js forum is there to help. To make the best use of the forum, check out the first page of this section.

Contributions can come in many forms. Answering questions on the forum is a useful contribution. Others may spot spelling errors in the documentation or find ways to improve it. Potential contributors to Babylon.js come from many different backgrounds. For some of you, version control systems, repositories, package managers, and task runners are second nature, and all you need to know are the requirements set by the Babylon.js core team for a pull request to be accepted. For others, especially those who just want to explore the world of 3D, they can feel like a series of confusing hurdles. This section therefore contains details that many of you can ignore as obvious. For others, those details may be the difference between making a contribution and not making one.



This guide is for contributors adding or modifying Babylon.js framework code. Application developers should start with [Using Pure Imports](/setup/frameworkPackages/es6Support/treeShaking/usingPureImports) and [Registering Side Effects](/setup/frameworkPackages/es6Support/treeShaking/registeringSideEffects).

## The File Pattern

Most files in Babylon.js have no side effects. These use a regular filename, such as `feature.ts`, and do not need any special treatment.

The multi-file pattern only applies to modules with side effects. Those are split into up to three files:

```text
feature.pure.ts  -> Implementation and registration function
feature.types.ts -> TypeScript module augmentations, if any
feature.ts       -> Backward-compatible wrapper
```

Not every side-effect module needs all three files. The `.types.ts` file is only needed when the feature adds methods or properties to another class.

### No Side Effects: Regular File

If your feature has no side effects at all, use the regular filename: `feature.ts`. No `.pure.ts`, wrapper, or `.types.ts` file is needed. This is the most common case.

### Side Effects Without Type Augmentations: Two Files

If your feature only has `RegisterClass` calls or static assignments, with no prototype augmentation:

- `feature.pure.ts` contains the implementation and `RegisterFeature()` function.
- `feature.ts` is the wrapper that calls `RegisterFeature()`.

No `.types.ts` file is needed if there are no `declare module` blocks.

### Side Effects With Type Augmentations: Three Files

You need all three if your feature:

- Adds methods or properties to existing classes.
- Uses `declare module` to tell TypeScript about those added members.

## Step-by-Step: Adding a New Prototype Augmentation

This example adds `doSomething()` to `Scene`.

### 1. Create the Types File

```typescript
// myFeatureSceneComponent.types.ts
import type { Scene } from "../scene.pure";

declare module "../scene.pure" {
  export interface Scene {
    /**
     * Does something useful.
     * @returns The result.
     */
    doSomething(): string;
  }
}
```

Rules:

- Use type-only imports.
- Target the `.pure` module in `declare module`.
- Document augmented public members with JSDoc.

### 2. Create the Pure Implementation

```typescript
// myFeatureSceneComponent.pure.ts
/** This file must only contain pure code and pure imports */

export * from "./myFeatureSceneComponent.types";

import { Scene } from "../scene.pure";
import { RegisterClass } from "../Misc/typeStore";

export class MyFeatureSceneComponent {
  // Implementation.
}

let _registered = false;
export function RegisterMyFeatureSceneComponent(): void {
  if (_registered) {
    return;
  }
  _registered = true;

  Scene.prototype.doSomething = function (): string {
    return "something";
  };

  RegisterClass("BABYLON.MyFeatureSceneComponent", MyFeatureSceneComponent);
}
```

Rules:

- Start `.pure.ts` files with `/** This file must only contain pure code and pure imports */`.
- Re-export the `.types` module when the feature has type augmentations.
- Put all side effects inside the `RegisterXxx()` function.
- Guard registration with an idempotency flag.
- Import from `.pure` specifiers when a pure module exists.
- Keep `RegisterClass` calls inside the registration function.

### 3. Create the Wrapper

```typescript
// myFeatureSceneComponent.ts
export * from "./myFeatureSceneComponent.pure";
import { RegisterMyFeatureSceneComponent } from "./myFeatureSceneComponent.pure";

RegisterMyFeatureSceneComponent();
```

The wrapper preserves existing behavior: importing the non-pure module still runs the compatibility side effects.

### 4. Update Barrels

Add the pure export to the directory's pure barrel:

```typescript
export * from "./myFeatureSceneComponent.pure";
```

Add the existing wrapper export to the standard barrel:

```typescript
export * from "./myFeatureSceneComponent";
```

### 5. Generate Side-Effect Stubs

If your feature augments prototypes, regenerate the side-effect stubs:

```bash
npm run generate:side-effect-stubs
```

This adds a lightweight missing-side-effect stub to the relevant pure class.

## Step-by-Step: Adding a RegisterClass-Only Module

If a feature only needs deserialization support and does not augment another class, create a pure implementation and wrapper:

### 1. Create the Pure Implementation

```typescript
// myNewMesh.pure.ts
/** This file must only contain pure code and pure imports */

import { Mesh } from "./mesh.pure";
import { RegisterClass } from "../Misc/typeStore";

export class MyNewMesh extends Mesh {
  // Full implementation.

  public static Parse(parsedMesh: unknown, scene: Scene): MyNewMesh {
    return new MyNewMesh("name", scene);
  }
}

let _registered = false;
export function RegisterMyNewMesh(): void {
  if (_registered) {
    return;
  }
  _registered = true;

  RegisterClass("BABYLON.MyNewMesh", MyNewMesh);
}
```

### 2. Create the Wrapper

```typescript
// myNewMesh.ts
export * from "./myNewMesh.pure";
import { RegisterMyNewMesh } from "./myNewMesh.pure";

RegisterMyNewMesh();
```

## Naming Conventions

### Registration Function Naming

Registration functions always use `Register` plus the PascalCase file name:

| Filename                               | Function                                 |
| -------------------------------------- | ---------------------------------------- |
| `standardMaterial.pure.ts`             | `RegisterStandardMaterial()`             |
| `engine.multiRender.pure.ts`           | `RegisterEngineMultiRender()`            |
| `WebXRHandTracking.pure.ts`            | `RegisterWebXRHandTracking()`            |
| `joinedPhysicsEngineComponent.pure.ts` | `RegisterJoinedPhysicsEngineComponent()` |

## Import Specifiers in Pure Files

When a `.pure.ts` module imports another module that also has a pure version, import the pure specifier:

```typescript
// Correct
import { Scene } from "../scene.pure";
import { Vector3 } from "../Maths/math.vector.pure";
import { Mesh } from "../Meshes/mesh.pure";

// Wrong: pulls in side effects
import { Scene } from "../scene";
import { Vector3 } from "../Maths/math.vector";
```

Do not import the non-pure module from a pure file, because that can pull side effects back into the pure graph.

Exception: type-only imports are erased at compile time, so they do not create runtime side effects:

```typescript
import type { Scene } from "../scene";
```

Using the pure path is still the clearest convention for new pure code.

## Static Method Extraction

When adding static methods to a class in a `.pure.ts` file, consider whether the method can be exported as a standalone function. This can improve tree-shaking for utility-style operations.

### Methods That Stay as Class Statics

Keep a method as a class static when it needs private or protected class members, when it is a static getter or setter, or when class identity is part of the public API.

### Methods That Should Be Standalone Functions

Prefer a standalone function when the method is pure computation, a simple factory, or a utility operating on structural types.

Example: if an existing class exposes `MyAsset.Parse(...)`, keep the parse implementation available from the pure module as a top-level function. Add the class static only in the wrapper so importing the pure module does not perform a static assignment side effect.

```typescript
// myAsset.pure.ts
/** This file must only contain pure code and pure imports */

export class MyAsset {
  public name: string;

  public constructor(name: string) {
    this.name = name;
  }
}

export function MyAssetParse(parsedAsset: { name: string }): MyAsset {
  return new MyAsset(parsedAsset.name);
}
```

```typescript
// myAsset.types.ts
import type { MyAssetParse } from "./myAsset.pure";

declare module "./myAsset.pure" {
  namespace MyAsset {
    export let Parse: typeof MyAssetParse;
  }
}
```

```typescript
// myAsset.ts
export * from "./myAsset.pure";
export * from "./myAsset.types";

import { MyAsset, MyAssetParse } from "./myAsset.pure";

MyAsset.Parse = MyAssetParse;
```

Users who import from `myAsset.pure` can tree-shake `MyAssetParse` independently from the compatibility static. Users who import from `myAsset` get the legacy `MyAsset.Parse(...)` API and its matching type augmentation.

## Automatic Dependencies

If a registration function depends on another registered feature, call it inside your function:

```typescript
export function RegisterMyMaterial(): void {
  if (_registered) {
    return;
  }
  _registered = true;

  // Register dependencies needed for loading saved scenes.
  RegisterTexture();
  RegisterImageProcessingConfiguration();

  RegisterClass("BABYLON.MyMaterial", MyMaterial);
  SerializationHelper._MyMaterialParser = MyMaterial.Parse;
}
```

Add automatic dependencies when:

- Your feature's `Parse()` method will trigger another missing-registration error.
- Your feature's constructor always creates instances of another registered class.
- Your feature is unusable without the dependency.

Do not add transitive registration when:

- The dependency is optional.
- Adding it would pull in a very large module from a small utility.

## The `#__PURE__` Annotation

TypeScript decorators compile to module-scope `__decorate(...)` calls, which can block tree-shaking. The build pipeline injects `/*#__PURE__*/` annotations into compiled `.pure.js` files automatically.

If your `.pure.ts` file uses decorators, no manual annotation is needed. Make sure the file uses the `.pure.ts` suffix so the post-build script can process it.

## Validation Checklist

Before submitting a PR that adds or modifies tree-shakeable code:

1. **TypeScript compiles**: `npm run build:es6` with 0 errors.
2. **ESLint passes**: `npm run lint:check`. Two custom ESLint rules enforce tree-shaking correctness.
3. **Tree-shaking verification passes**: `npm run check:treeshaking`, which verifies manifest drift, pure barrels, and side-effect stubs.
4. **Side-effects sync check passes**: `npm run check:side-effects-sync`, which verifies the `sideEffects` array in `@babylonjs/core/package.json` matches the manifest.
5. **Bundle smoke tests pass**: `npm run test:treeshaking`.

`@babylonjs/require-pure-annotation` requires `/*#__PURE__*/` on module-scope calls and static field initializers in `.pure.ts` files. It is auto-fixable.

`@babylonjs/no-side-effect-imports-in-pure` disallows side-effect-only imports in `.pure.ts` files and checks that `pure.ts` barrels only re-export side-effect-free sources.

The full CI check runs all of these together:

```bash
npm run check:treeshaking-all
```

If `check:treeshaking` fails, the error message tells you which fix command to run:

```bash
# If manifest drift is detected:
npm run update:manifest

# If sideEffects array is out of sync:
node scripts/treeshaking/syncSideEffects.mjs

# If pure barrels are out of date:
npm run generate:pure-barrels

# If side-effect stubs are out of date:
npm run generate:side-effect-stubs
```

## Automation Scripts

| Script                        | npm Command                          | Purpose                                             |
| ----------------------------- | ------------------------------------ | --------------------------------------------------- |
| `verifyTreeShaking.mjs`       | `npm run check:treeshaking`          | Unified CI check for manifest, barrels, and stubs   |
| `checkManifestDrift.mjs`      | `npm run check:manifest-drift`       | Verify manifest matches source                      |
| `generatePureBarrels.mjs`     | `npm run generate:pure-barrels`      | Regenerate `pure.ts` barrel files                   |
| `generateSideEffectStubs.mjs` | `npm run generate:side-effect-stubs` | Generate prototype warning stubs                    |
| `auditSideEffects.mjs`        | `npm run audit:side-effects`         | Scan for all side effects                           |
| `syncSideEffects.mjs`         | (manual)                             | Sync manifest to package metadata                   |
| `injectPureAnnotations.mjs`   | (runs automatically during build)    | Inject `/*#__PURE__*/` in compiled JS               |
| `bundleSmokeTest.mjs`         | `npm run test:treeshaking`           | Run tree-shaking bundle tests                       |
| `fixPureImports.mjs`          | (manual)                             | Rewrite imports in `.pure.ts` to `.pure` specifiers |

Both `generatePureBarrels.mjs` and `generateSideEffectStubs.mjs` support `--check` mode, which is used by `verifyTreeShaking.mjs` to compare expected output to committed files without modifying anything.

`syncSideEffects.mjs` also supports `--check` mode, used by `npm run check:side-effects-sync` in CI.

## Pre-Commit Hook

The Babylon.js repository uses a `.githooks/pre-commit` hook. When core source files are staged, the hook automatically:

1. Runs `npm run precommit`.
2. Regenerates the side-effects manifest with `npm run update:manifest`.
3. Regenerates pure barrels with `npm run generate:pure-barrels`.
4. Regenerates side-effect stubs with `npm run generate:side-effect-stubs`.
5. Stages the updated manifest, package metadata, and generated barrels.

After editing `.pure.ts` files, the hook handles the common generation steps. You can still run the individual commands manually to verify before committing.

## Quick Reference: File Header Convention

```typescript
// .pure.ts files:
/** This file must only contain pure code and pure imports */

// .types.ts files:
// No special header needed; these only contain declare module blocks.

// .ts wrapper files:
// No special header needed; these are thin wrappers.
```


Developing With and For Babylon.js

Coming next

A Local Webserver for Babylon.js

A simple local webserver for running Babylon.js.

3D Commerce Certified Viewer

Learn how to get a 3D Commerce certified viewer version based on the Babylon.js engine.

Workloads (legacy)

Learn about the legacy workload system in Babylon.js.

Using Visual Studio Code (VSCode)

Learn how to use the popular oss IDE VSCode for Babylon.js development.

The .babylon File Format

Dive deep into the inner workings of the .babylon file format.

Creating The Minified Version of Babylon.js

Learn how to create the minified version of Babylon.js.

WebGL2 Support

Dive into understanding the full scope of support for WebGL2 in Babylon.js.

WebGPU Support

Dive into understanding the full scope of support for WebGPU in Babylon.js.

Running Babylon.js On A Server

Learn how to run Babylon.js on a server.

Code splitting and Chunks using known bundlers

Learn how to control code splitting in Babylon.js, when using bundlers like webpack or rollup

Debugging and Profiling with PIX

Learn how to use PIX to debug and profile your Babylon.js application.