
In this section, learn how to use Babylon.js outside the browser! The Babylon.js platform offers several ways to use one awesome engine both on the web and for native applications. If you want one codebase that deploys across different platforms, look no further!


# Babylon.js Official Add-ons

This section contains all of our official add-ons from the [Addons npm package](https://www.npmjs.com/package/@babylonjs/addons).



## 9.15.0

### Migration to TC39 (Stage 3) decorators

Babylon.js has moved from TypeScript's legacy `experimentalDecorators` to standard TC39 Stage 3 decorators. This only affects you if your own code applies Babylon.js decorators (such as `@serialize`, `@serializeAsVector3`, `@expandToProperty`, `@addAccessorsForMaterialProperty`, or `@editableInPropertyPage`) to classes you author — for example when you subclass a Babylon.js type and add your own serializable or editable properties. Code that merely _uses_ Babylon.js classes is unaffected.

If you do apply these decorators yourself, update your project as follows.

**1. Compile with TC39 decorators.** Babylon.js' decorators now expect the Stage 3 calling convention, so your project must no longer use the legacy flag. In your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "experimentalDecorators": false
  }
}
```

`experimentalDecorators: false` is the default in modern TypeScript, so in most cases you can simply remove the flag. Leaving it `true` will cause Babylon.js' decorators to receive the wrong arguments at runtime and silently fail (properties will not be serialized or shown in editors).

**2. Add the `accessor` keyword where required.** `@expandToProperty` and `@addAccessorsForMaterialProperty` are auto-accessor decorators and must be applied to fields declared with the `accessor` keyword:

```typescript
// Before
@expandToProperty("_reorderLightsInScene")
public renderPriority: number = 0;

// After
@expandToProperty("_reorderLightsInScene")
public accessor renderPriority: number = 0;
```

Decorators applied to plain fields — such as `@serialize()` and `@editableInPropertyPage(...)` — continue to work as field decorators and do **not** require the `accessor` keyword. Only the auto-accessor decorators above do.

**3. Target ES2015 or later.** The `accessor` keyword requires a compilation target of `ES2015` (ES6) or newer. If your `tsconfig.json` still targets `ES5`, raise it:

```json
{
  "compilerOptions": {
    "target": "ES2015"
  }
}
```

**4. Reading Node Material / Node Geometry editable properties.** If you previously read the internal `_propStore` array from a class to enumerate `@editableInPropertyPage` properties, use the exported `GetEditableProperties(target)` helper instead — the metadata is now stored on the class' `Symbol.metadata` rather than on a `_propStore` field.

**UMD bundle target.** The published UMD bundles (`babylon.max.js` and the companion `babylonjs.*.js` bundles for gui, loaders, materials, serializers, etc.) are now emitted at **ES2015** instead of ES5. All currently supported browsers run ES2015 natively, so no change is needed for normal web usage, including the Playground. Only environments that require ES5 script (such as Babylon Native's Chakra engine) need a down-level step; the Babylon.js CI already performs this for Native.

See PRs [#18631](https://github.com/BabylonJS/Babylon.js/pull/18631), [#18630](https://github.com/BabylonJS/Babylon.js/pull/18630), and [#18647](https://github.com/BabylonJS/Babylon.js/pull/18647) for more information.

## 8.10.1

### Fix target camera orientation issues when using right-handed scenes

When using right-handed scenes, setting and getting the `rotation` or `rotationQuaternion` properties of a target camera was rotated 180 degrees on the Y-axis when compared to the view or world matrix of the camera. This is confusing and caused problems when exporting glTF. Any code that previously set the `rotation` or `rotationQuaternion` properties of a camera derived from `TargetCamera` (`FreeCamera` or `ArcRotateCamera`, for example) when using right-handed scenes will now be wrong. The default orientation of a target camera still faces +Z as before to maintain backwards compatibility. Left-handed scenes are also unaffected. See [PR](https://github.com/BabylonJS/Babylon.js/pull/16691) for more information.

## 8.2.0

### PBR: Add flag to calculate legacy translucency

In previous PRs (https://github.com/BabylonJS/Babylon.js/pull/16337, https://github.com/BabylonJS/Babylon.js/pull/16214), we corrected the way translucency/transmission is calculated.
However, we failed to add a flag to allow you to render your scene exactly as it was before these changes. We have therefore added a property `mat.subSurface.legacyTranslucency` (default: false), in case your scene does not render as expected with the new code and you want an easy way to do it. You can also set `PBRSubSurfaceConfiguration.DEFAULT_LEGACY_TRANSLUCENCY` to true to automatically apply the back compat behavior to all materials.

PR: https://github.com/BabylonJS/Babylon.js/pull/16446

## 7.54.0

### PBR: Fix calculation of diffuse transmission in PBR materials

This is a bug fix, but it may have an impact on the rendering of your scene. Previously, we incorrectly applied the albedo color when outputting the subsurface block calculation.
However, if you need to restore the old behavior for some reason, you can do `mat.subSurface.applyAlbedoAfterSubSurface = true`. Note that from 8.0.2 and forward you can also set `PBRSubSurfaceConfiguration.DEFAULT_APPLY_ALBEDO_AFTERSUBSURFACE` to true to automatically apply the back compat behavior to all materials.
Note that you can probably make your assets compatible with the new code without needing to set `applyAlbedoAfterSubSurface = true` by setting the correct texture in the `translucencyColorTexture` property.

PR: https://github.com/BabylonJS/Babylon.js/pull/16337

## 7.52.0

### Deprecation of legacy audio engine

To pave the way for the new audio engine, the old audio engine is no longer created by default when the graphics engine is initialized. To use the old deprecated audio engine, set the `audioEngine` option to `true` in the graphics engine constructor, for example:

```javascript
const engine = BABYLON.Engine(canvas, true, { audioEngine: true }, true);
```

PR: https://github.com/BabylonJS/Babylon.js/pull/15839

## 7.51.0

### Fix calculation of diffuse transmittance in PBR materials

This is a bug fix, but it may have an impact on the rendering of your scene. It will manifest itself as lighter materials when you activate translucency on a PBR material.

PR: https://github.com/BabylonJS/Babylon.js/pull/16214

## 7.47.3

### Fix alpha support
It was not always easy to understand how alpha was applied, depending on the value of certain material properties, and the handling of certain glTF files with transparency was even broken.

Since version 7.47.3, if you give a non-null value to `transparencyMode`, it will always be respected, regardless of the values you give to the other properties (such as the mesh `visibility`, the material `alpha`, etc.). This makes it easy to apply alpha testing, alpha blending, or both at the same time, by setting the correct value for `transparencyMode`.

However, this change could break your code. If it does, most of the time, the solution is simply to set the correct value for `transparencyMode`.

PR: https://github.com/BabylonJS/Babylon.js/pull/16144

## 7.46.0

### Loading screen on multiple canvases
In order to manage the visibility of the loading screen on multiple canvases, we have changed the underlying data structure that tracks the loading screen info.

However, if you have implemented your own custom loading screen, this change could break your code. If it does, you should:
1. Manually set the `this._isLoading` attribute to true in `displayLoadingUI` and false in `hideLoadingUI`.
2. Manage your custom loading div through `this._loadingDivToRenderingCanvasMap` rather than the old `this._loadingDiv` attribute.

Here is an example of a PG using a custom loading screen:
<Playground id="#5Y2GIC#847" title="Custom Loading Screen Example" description="Simple example showing how to create and use a custom loading screen."/>

## 7.45.0

### `PBRMaterial` rough metals are looking closer to ray traced results
Improving the way we render is an ongoing mission for the Babylon team, and as explained on the [forum](https://forum.babylonjs.com/t/differences-in-pbr-material-behavior-between-babylon-5-and-7/56585/5?u=sebavan), our PBR rendering has been improved to produce more correct results.

As we understand it, you might have changed your art to adapt to the previous behavior. You can bring it back by setting `PBRBRDFConfiguration.DEFAULT_MIX_IBL_RADIANCE_WITH_IRRADIANCE = false;` before creating your `PBRMaterial`.

## 7.34.0

### `SceneLoader.Load`, `SceneLoader.Append`, `SceneLoader.ImportMesh` no longer return the plugin used to load the content
In order to support automatic mimetype detection, we have removed the synchronous aspect of these 3 functions, and they will return void from now on.
More details: https://forum.babylonjs.com/t/potential-new-breaking-change-please-chime-in/54651

To get the plugin used to load content, you can register to `SceneLoader.OnPluginActivatedObservable`.

## 7.31.0

### Instances now get the same parent as the source
Before, instances were created with no parent, but this caused a lot of rendering issues when the source came from a glTF object. This change makes sure the source and the instance have the same parent.

### Deprecation of CSG class in favor of CSG2

The old CSG class was made of pure JS (it was a port from https://github.com/evanw/csg.js/) and while it served us, it was not maintained and not usable anymore.
We are now encouraging everyone to switch to the new CSG2 class.

### Porting from CSG to CSG2

#### Asynchronous initialization

The main difference is that CSG2 uses the [fantastic Manifold](https://github.com/elalish/manifold) to do the boolean operations. To that end, you have to call `BABYLON.InitializeCSG2Async()` before you can use the CSG2 class.

Example:

```
await BABYLON.InitializeCSG2Async();

const sphereCSG = BABYLON.CSG2.FromMesh(sphere);
const boxCSG = BABYLON.CSG2.FromMesh(box);

const mesh = boxCSG.subtract(sphereCSG).toMesh("test");
```

### Inverse

The inverse feature is no longer supported (and it was not really working, so we should all be fine).

#### ToMesh

The method `toMesh` takes 3 parameters: name, scene, and options.

#### MultiMaterials

CSG2 has a far simpler way to deal with multi-materials as it will automatically rebuild meshes with multi-materials if the source meshes had different materials.

### Example

Here is an example of a PG using CSG:
<Playground id="#VYZEEQ#4" title="CSG Subtract Example" description="Simple example of using a CSG subtract operation."/>

And the converted version:
<Playground id="#PJQHYV#1" title="CSG Subtract Example" description="Simple example of using a CSG2 subtract operation."/>

### Using CSG2

Please refer to the CSG2 [class documentation for more details](/features/featuresDeepDive/mesh/mergeMeshes#merging-meshes-with-constructive-solid-geometry)

## 7.19.0

### Main materials now generate WGSL shader code when used with WebGPU

This change is an improvement, as the main shaders (StandardMaterial, PBRMaterial, and BackGroundMaterial) now generate pure WGSL and do not require compilation of GLSL code with TintWASM when used with a WebGPUEngine.
If you still need to get GLSL code (for instance, if you inject your own custom code with a MaterialPlugin0), you can force the materials to use the GLSL code path with a boolean in the materials' constructors.

## 7.11.0

### mesh.overrideMaterialSideOrientation was renamed to mesh.sideOrientation

This change was made to simplify the sideOrientation process. Starting with this version, mesh.sideOrientation is used unless material.sideOrientation is not null.
[content/breaking-changes.md](https://github.com/BabylonJS/Babylon.js/pull/15189)

## 7.6.0

### canvas is not xrCompatible by default

This change should not affect our XR users, but it is a breaking change. Instead of defining the canvas as XR compatible when creating the WebGL2 context, the canvas is made XR compatible when entering XR.
[content/breaking-changes.md](https://github.com/BabylonJS/Babylon.js/pull/15027)

## 7.2.2

### Remove WebGPUEngine Dependency on Engine

**[14931](https://github.com/BabylonJS/Babylon.js/pull/14931)**
This is a rather large change to decouple `WebGPUEngine` from `Engine`, where all properties of `Engine` in the library are now properties of `AbstractEngine`. The existing methods, however, are all unchanged, so the impact on them should be minimal. `ThinEngine` and `Engine` are almost entirely unchanged, but there are two important considerations to keep in mind:

1. `AbstractEngine` is abstract and should not be instantiated
2. All common functions have been moved from `ThinEngine` to `AbstractEngine` so they can be shared with WebGPU Engine

The main impact on user code will only affect TypeScript, as the type of all `getEngine()` functions will be `AbstractEngine` instead of `ThinEngine`.

## 7.0.0

### Thin Instances

**[#14679](https://github.com/BabylonJS/Babylon.js/pull/14679)** The default value of the thin instances staticBuffer parameter was changed to true. When staticBuffer parameter is set to false, Angle can rearrange the buffers under the hood and completely break performance when in DirectX mode. In OpenGL mode using a value of false for the staticBuffer parameter does not affect performance. Due to the performance issues in DirectX mode, the new default for staticBuffer will be true to maintain performance levels.

### WebVR

**[#14439](https://github.com/BabylonJS/Babylon.js/pull/14439)** The WebVR API was deprecated and has now been removed from the engine. The remaining part of the previous implementation of WebVR is the VR experience helper. Leaving this in the engine will help any experiences that used WebVR and the VR experience helper to continue working. In the case that the VR experience helper is called in an experience the engine will correctly fall back to using WebXR. This will enable older VR experiences to continue to function while it is updated to remove the deprecated feature.

### ArrayBufferView

**[#13946](https://github.com/BabylonJS/Babylon.js/pull/13946)** Added ArrayBufferView to be one of the accepted types in the SceneLoader import methods. The SceneLoader methods for ImportMesh, ImportMeshAsync, Load, LoadAsync, Append, AppendAsync, and LoadAssetContainer have traditionally accepted the types string and File. Now these methods will also be able to receive the type ArrayBufferView.

This was required by Babylon Native for those times when model data is passed from C++ into JavaScript by mapping native memory into ArrayBuffers. Included with this change is an additional visualization test for loading a mesh directly from binary data.

### glTF Serializer

**[#13909](https://github.com/BabylonJS/Babylon.js/pull/13909)** The glTF exporter used to attempt to change the mesh data on serialization to bake in a conversion from a left-handed scene - which is the default in Babylon.js - to a right-handed coordinate system which is expected by the glTF specification. This conversion was causing issues with some exported assets so the breaking change was to stop attempting to change the mesh data to account for a right-handed coordinate system to match the glTF specification and instead negate one axis of the asset. This results in a negative scale on one axis of the asset's root node when imported into a left-handed Babylon.js scene.

### Material Cloning

**[#13807](https://github.com/BabylonJS/Babylon.js/pull/13807)** When cloning materials, the default behavior has been to clone any textures used in multiple material channels once for each channel that uses it. To prevent duplicating a texture multiple times when cloning a material, the parameter `cloneTexturesOnlyOnce` was added to clone to prevent extra duplication of textures allowing multiple material channels to reference a single texture. Since this behavior logically should be the way clone works, the default value of `cloneTexturesOnlyOnce` is set to true, which is a breaking change from how the engine used to work. If the previous behavior is desired, setting this parameter to false will restore the previous behavior.

### ShaderPath

**[#14908](https://github.com/BabylonJS/Babylon.js/pull/14908)** Previously, when using ShaderMaterial, the constructor accepted a type of _any_ for ShaderPath, which could cause issues in TypeScript projects. This change adds types to ShaderPath instead of _any_, which will protect type compatibility with ShaderMaterial and TypeScript.



# Extensions

This section contains incredible Babylon.js extensions and resources contributed by the amazing community surrounding this platform. While they are not part of the main engine, and therefore are not maintained by the core Babylon.js development team, this section includes some incredible technology that you can use to extend your Babylon.js experience even further!



## Contributions

You can contribute either to the Babylon.js engine directly or to its documentation. The documentation is split into two parts: the 'tutorial' section and the API. The API documentation is generated from comments within the Babylon.js code, so details on how to contribute to the API fall under this section.


# Babylon.js Features

This section will help you learn all about the breadth and depth of features available with Babylon.js and how to use them. Buckle up! There's a LOT!


A selection of tutorials on games and applications that describe how they are achieved.


## Welcome - Your Journey Starts Here

Hello and welcome to Babylon.js! We know you're eager to start your learning journey, but before you dive any deeper or go clicking around, we'd humbly ask that you take the time to read through the following three very important documents. Reading these docs will set you up for success as you begin your Babylon.js learning journey.

- [Your Very First Step](/journey/theFirstStep)
- [Learning The Docs](/journey/learningTheDocs)
- [The Babylon.js Forum](/journey/forum)


## Legacy Features

Maintaining backward compatibility is one of the main tenets of Babylon.js. However, with changes in technology, we sometimes have to make the decision to move older features to "Legacy" status, so that we can develop more modern and efficient approaches to problems. When a legacy feature has a more modern alternative, it is advisable to move to the modern approach when possible. This section lists all of our legacy features.



Creating assets that are beautiful and engaging while still being optimized for rendering performance at 60 fps can be tricky. This section is here to help you understand some of the basic concepts of creating real-time assets to use in Babylon.js. There are many great resources for learning how to create 3D assets for real-time rendering available online, so this section will point to those resources when available. In that sense, this guide won't be a step-by-step guide for creating a specific asset in a specific digital content creation (DCC) tool, but rather a higher level discussion of the concepts that artists will be faced with when creating real-time assets. This section will also explain Babylon.js-specific concepts for asset creation to help you get the most out of your art pipeline.

To start things off, we will link to the [Khronos Group Real-Time Asset Creation Guidelines](https://registry.khronos.org/3DCommerce/AssetCreation/) which does a good job of explaining many of the basics of what real-time artists face when creating an asset. This guide is a good place to start for general concepts, but understand that the guide was written with creating assets for e-commerce in mind. This means that the target use is likely a small scene with a limited number of assets meant to help the purchase decision of the user. This means that any guidelines you see for triangle count, texture size, download size, material count, etc. may not fit the size or scope of your scene and may need to be adjusted.

This section will also grow as demand dictates and you can help with that. Do you want to learn about a topic? Let us know on the [Babylon.js Forum!](https://forum.babylonjs.com/)



## Getting Your Babylon.js Web Project Set Up
This section provides guidance on the workflow required to create a 3D web app, from getting started by downloading a complete webpage from a simple playground to building a large application using an IDE and other development frameworks and packages.


# Tools and Resources

This section contains all sorts of helpful information for developing with Babylon.js. From tools that make development easier to free asset libraries you can use in your scenes, it is designed to help you create beautiful experiences as quickly and efficiently as possible.



## Welcome To The Babylon.js Documentation

Hello and welcome to the Babylon.js Documentation. In these pages, you will find everything you could ever want to know about this powerful, beautiful, simple, and completely open-source web rendering engine. Whether you are just starting your Babylon.js journey, or you are a seasoned veteran, it is our sincere hope that the information contained here will help you bring your ideas to life.

We know that each person comes to Babylon.js with their own background, experiences, and learning style. We also understand that each of you has a different goal in mind for your learning journey. We have done our best to organize these doc pages to help as many people as possible achieve their learning goals efficiently. Our documentation has two main parts: one for those who want to dive right into Babylon.js and learn about the engine and its features, and another for those who prefer to start by understanding how to get Babylon.js set up and integrated into a web application. In the coming pages, you'll find paths optimized for each of these learning styles.

However, before you go any further, we strongly encourage (and humbly ask) EVERYONE to [Start Your Babylon.js Journey Here.](journey/theFirstStep)

![Babylon](/img/home/babylonjs_identity_color.webp?expandable=false)

## Code license

Unless otherwise stated, all code provided in the documentation pages is licensed under Apache 2.0.

Babylon.js Documentation

Welcome To The Babylon.js Documentation

Code license

Coming next

Your Journey Starts Here

The very beginning of EVERYONE's Babylon journey.

Babylon.js Features

Learn all about the breadth and depth of features that come with Babylon.js

Workflow

The workflow from a simple webpage to a complete app with an IDE and development frameworks.

Tools And Resources

Learn about handy development tools and resources available to you for creating stunning Babylon.js scenes.

Preparing Assets for Babylon.js

Learn all about how to prepare various assets for use in Babylon.js

Babylon.js Cross Platform

Learn how to use Babylon.js to create Native Apps!

Contribute

Describes how you can contribute to the development of Babylon.js

Guided Learning

A selection of tutorials on games and applications that describe how they are achieved

Babylon.js Official Addons

Learn all about the Babylon.js addons and how to use them in your projects.

Community Extensions

Learn all about amazing community-led extensions to the core Babylon platform.

Legacy

Babylon.js legacy features

What's New

Documentation page for What's New

Babylon.js Breaking Changes

Breaking changes and how to adapt for them

API

Documentation page for API

Search

Documentation page for Search

Playground search

Documentation page for Playground search