
# Atmosphere

## Introduction

The atmosphere addon provides physically based sky and aerial perspective rendering.

Orbital views of the globe are also supported, as demonstrated in the following playground.

<Playground id="#K1Y1Q8#82" title="Default Atmosphere" description="The default atmosphere with a globe toggle." />

## Installation

The atmosphere addon is available as an ES6 NPM package:

```shell
npm install @babylonjs/addons --save
```

and as a UMD NPM package:

```shell
npm install babylonjs-addons --save
```

When using the ES6 package, import the `Atmosphere` class directly from its subpath:

```javascript
import { Atmosphere } from "@babylonjs/addons/atmosphere";
```

<Alert severity="info">
The atmosphere requires WebGPU or WebGL2. Call `Atmosphere.IsSupported(engine)` before creating an instance to verify the engine is compatible.
</Alert>

## Scene Setup

### PBRMaterial

For rendering objects within the atmosphere, it is recommended to use [physically based materials (PBR)](/features/featuresDeepDive/materials/using/introToPBR).

<Playground id="#K1Y1Q8#94" title="PBR Integration" description="A PBR sphere rendered within the atmosphere." />

<br/>
<br/>

The atmosphere addon automatically integrates with `PBRMaterial`, ensuring consistent lighting that accounts for atmospheric effects.

### Directional Light

The sun source for the atmosphere is represented by a `DirectionalLight`.

```javascript
const light = new DirectionalLight("sun", new Vector3(0, -1, 0), scene);
light.intensity = Math.PI; // Set intensity for PBRMaterials
```

To get the correct brightness on `PBRMaterial`s, the light intensity can be set to PI. This will cancel out the 1/PI factor from the PBR rendering.

A more physically-based `DirectionalLight` setup can leverage the [IntensityMode](/features/featuresDeepDive/materials/using/masterPBR#intensitymode) to specify the light in physical units (e.g., lux or nits).

### Rendering Pipeline

To allow for dynamic range and accurate lighting calculations, the `DefaultRenderingPipeline` can be used.

```javascript
const pipeline = new DefaultRenderingPipeline("Default", true /* hdr */, scene);
pipeline.imageProcessingEnabled = true;
pipeline.imageProcessing.toneMappingEnabled = true;
pipeline.imageProcessing.ditheringEnabled = true;
```

Tonemapping can be enabled to better handle the high dynamic range of the atmosphere, and dithering will help reduce color banding in the sky.

## Customizing the Atmosphere

Create the atmosphere by passing the directional light.

```javascript
const atmosphere = new Atmosphere("atmosphere", scene, [light]);
// True if rendering to an HDR target (e.g. DefaultRenderingPipeline with hdr: true)
atmosphere.isLinearSpaceComposition = true;
// True if light value in the scene is expected to be linear (e.g. PBRMaterials)
atmosphere.isLinearSpaceLight = true;
```

By default, Earth-like scattering parameters and dimensions are used. This can be further customized.

### Rayleigh Scattering

Rayleigh scattering can have a strong effect on the overall color of the atmosphere.

<Playground id="#K1Y1Q8#83" title="Green Rayleigh Scattering" description="Create a green sky by increasing Rayleigh scattering in the green channel." />

```javascript
atmosphere.physicalProperties.peakRayleighScattering = new Vector3(0.001, 0.034, 0.001); // r, g, b
```

### Mie Scattering and Absorption

Mie scattering and absorption affect the haziness of the atmosphere.

<Playground id="#K1Y1Q8#84" title="Increased Mie Scattering" description="Increased Mie scattering for a hazier atmosphere." />

```javascript
atmosphere.physicalProperties.mieScatteringScale = 100;
```

### Ozone Absorption

Ozone absorption can also affect the color of the atmosphere.

<Playground id="#K1Y1Q8#85" title="Increased Ozone Absorption" description="Increased ozone absorption for a deeper blue sky." />

```javascript
atmosphere.physicalProperties.ozoneAbsorptionScale = 5;
```

### Multiple Scattering

Multiple scattering simulates light within the atmosphere that has scattered more than once. This affects the brightness of the atmosphere but can also affect the overall color, especially depending on the ground albedo.

<Playground id="#K1Y1Q8#86" title="Increased Multiple Scattering" description="Increased multiple scattering and red ground albedo." />

```javascript
atmosphere.multiScatteringIntensity = 4.0;
atmosphere.groundAlbedo = new Color3(1.0, 0.2, 0.2);
```

### Optimization and Quality

By default, the atmosphere uses lookup tables (LUTs) for improved efficiency. To fall back to the more expensive but higher-quality ray marching, use the following properties.

<Playground id="#K1Y1Q8#87" title="Full Ray Marching" description="The default atmosphere with full ray marching." />

```javascript
atmosphere.isAerialPerspectiveLutEnabled = false;
atmosphere.isSkyViewLutEnabled = false;
```

## Time of Day

The atmosphere can simulate different times of day by changing the direction of the light.

Typically, a -Y light direction can be used for a directly overhead sun, although this depends on what is considered the up-vector of the scene.

<Playground id="#K1Y1Q8#90" title="Day-Night Animation" description="Simulating different times of day by animating the sun position." />

```javascript
// Assuming +Y is up
light.direction = new Vector3(0, -1, 0); // Day
light.direction = new Vector3(0, 1, 0); // Night
light.direction = new Vector3(1, 0, 0); // Sunrise/Sunset
```

To simulate night, a minimum multiple scattering intensity can be set. This maintains some ambient light in the atmosphere even when the sun is below the horizon.

```javascript
atmosphere.minimumMultiScatteringIntensity = 0.1;
```

## Disposal

When the atmosphere is no longer needed, call `dispose()` to release all GPU resources and remove it from the scene:

```javascript
atmosphere.dispose();
```


# MSDF Text Renderer

## Introduction
The TextRenderer class provides a powerful and efficient solution for rendering crisp, scalable text in Babylon.js scenes using MSDF (Multi-channel Signed Distance Fields). Unlike traditional bitmap fonts or SDF techniques, MSDF preserves sharp corners and detailed glyph shapes at any scale, making it ideal for modern 3D and 2D applications that demand both performance and visual fidelity.

Example:

<Playground id="#6RLCWP#38" title="TextRenderer example" description="Example of using a TextRenderer"/>

Rendering text in WebGL presents a unique challenge: balancing resolution-independence with performance. Simple bitmap fonts scale poorly and blur at larger sizes, while classic single-channel SDFs tend to lose precision around complex edges. MSDF solves these issues by encoding distance information into three color channels (RGB), allowing precise reconstruction of glyph shapes using a shader, regardless of size or zoom level.

This technique offers:

* Resolution-independent clarity — no pixelation at large scales.

* GPU-efficient rendering — no need to regenerate or resize textures.

* Support for complex typographic details — sharp corners, curves, and serifs remain intact.

The TextRenderer class handles MSDF rendering under the hood, managing vertex buffers, instancing, and shader logic seamlessly. It supports advanced features like billboarding, text thickness control, and instanced paragraph rendering, enabling dynamic, high-quality text rendering in immersive 3D environments.

Whether you're building UI overlays, 3D HUDs, or in-world labels, TextRenderer offers a scalable and performant foundation for text in Babylon.js.

## Installation

The MSDF Text Renderer is available as a UMD NPM package.

```shell
-npm install babylonjs-addons --save
```

and as an ES6 package:

```shell
-npm install @babylonjs/addons --save
```

## Initialization

Two assets are needed to initialize an MSDF `TextRenderer`:
1. A texture that contains the MSDF glyphs.
2. A JSON file that describes the bounds of each glyph within the texture, as well as other per-glyph information.

Because we need to load the correct shaders (either WebGL or WebGPU), creating a TextRenderer is async:

```
const sdfFontDefinition = await (await fetch("https://assets.babylonjs.com/fonts/roboto-regular.json")).text();
const fontAsset = new ADDONS.FontAsset(sdfFontDefinition, "https://assets.babylonjs.com/fonts/roboto-regular.png");

const textRenderer = await ADDONS.TextRenderer.CreateTextRendererAsync(fontAsset, engine);
```

The `fontAsset` defines the font shapes and can be shared across several TextRenderers.

## Generating font data

You can check the following free tools to generate font assets for your project:

* https://msdf-bmfont.donmccurdy.com/
* https://github.com/Chlumsky/msdfgen#using-a-multi-channel-distance-field

These tools generate the required JSON file and texture image (for example, a PNG). You will need to provide as input the set of characters that you need in your app. For example, if you want to support typical alphanumeric English characters along with other common characters, your input string might be:
```text
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 `~!@#$%^&*()-_=+[{]}\|;:'",<.>/?
```

After generating custom font assets, you might find this Playground useful for testing:

<Playground id="#Y20U5M#3" title="TextRenderer Test" description="Helpful PG for testing custom MSDF font assets"/>

## Usage

Using a TextRenderer is pretty straightforward:

```
textRenderer.addParagraph("Hello World !");
```

This will add the text centered on the screen.

You can also provide options to control how your paragraph is set up:

```
textRenderer.addParagraph("What's up ?", {
    textAlign: "center"
});
```

The options are defined by this type:

```
type ParagraphOptions = {
    maxWidth: number;
    lineHeight: number;
    letterSpacing: number;
    tabSize: number;
    textAlign: "left" | "right" | "center";
    translate: Vector2 | undefined;
};
```

You can also add a third parameter to the `addParagraph` call to control where you want your text:

```
textRenderer.addParagraph("What's up ?", {
    textAlign: "center"
}, BABYLON.Matrix.Translation(5, 0, 0));
```

The following properties are also available to control all rendering for a TextRenderer:

* color: Color4 used to define the color of the text
* thicknessControl: a float indicating how to change the overall default thickness (between -0.5 and 0.5, with 0 as the default value)
* parent: A node used to attach the text to
* isBillboard: a boolean indicating you want the text to always face the camera. ** Please note that in this case only the translation part of the parent world matrix will be considered **
* isBillboardScreenProjected: indicates whether billboard mode renders the text in screen-space. When set to true, the text keeps a constant on-screen size—its scale no longer changes with the camera’s distance.
* strokeColor: Color4 used to define the color of the stroke around the text
* strokeInsetWidth: Size of the stroke inset (inside the text)
* strokeOutsetWidth: Size of the stroke outset (outside the text)
* ignoreDepthBuffer: Will ignore depth buffer value and render the text on top of whatever is already in the frame buffer
* transformMatrix: Matrix used to move the entire list of paragraphs as a whole

## Positioning and scaling

By default, the text will be rendered at 0,0,0. Then we apply the paragraph world matrix, followed by the transform matrix.

You can control its position, rotation, and scaling by setting a parent. If you opt to use billboard mode, then only the parent's position will be used.

The overall location of the text will be computed as follows:

Final world matrix = Parent World * Transform Matrix * Paragraph Matrix

## Examples

Setting a parent:

<Playground id="#6RLCWP#72" title="TextRenderer" description="Setting a parent"/>

A Star Wars scroller:

<Playground id="#6RLCWP#40" title="TextRenderer" description="Star Wars scroller"/>

Thickness control:

<Playground id="#IABMEZ#4" title="TextRenderer" description="Thickness control"/>

Stroke:

<Playground id="#6RLCWP#41" title="TextRenderer" description="Setting a parent"/>


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


Babylon.js Official Addons

Coming next

HtmlMesh

The HTML Mesh is a mesh that displays a webpage (or DOM element) in the scene, meaning that it can occlude other meshes and be occluded by other meshes.

Atmosphere

The atmosphere addon provides physically based sky and aerial perspective rendering.

MSDF Text

Documentation page for MSDF Text