babylon-msdf-text/readme.md

**babylon-msdf-text** is a library for rendering high-quality, scalable, and anti-aliased text in Babylon.js using the Multi-channel Signed Distance Field (MSDF) technique. It offers an efficient and straightforward solution for superior text rendering in

# babylon-msdf-text

**babylon-msdf-text** is a library for rendering high-quality, scalable, and anti-aliased text in Babylon.js using the Multi-channel Signed Distance Field (MSDF) technique. It offers an efficient and straightforward solution for superior text rendering in WebGL contexts, overcoming the limitations of traditional bitmap fonts. Written in TypeScript, it provides type safety and an improved developer experience, and includes support for instancing to optimize performance when rendering multiple text instances.

![npm](https://img.shields.io/npm/v/babylon-msdf-text.svg?style=flat-square) ![npm](https://img.shields.io/npm/dt/babylon-msdf-text.svg?style=flat-square)

## Features

- **High-Quality Text Rendering**: Uses MSDF for crisp, scalable text that remains sharp at any size.
- **TypeScript Support**: Includes type definitions for enhanced code completion and type safety.
- **Instancing**: Supports Babylon.js instancing for efficient rendering of multiple text copies.
- **Customizable**: Adjust text properties like color, stroke, opacity, alignment, and more.
- **Word Wrapping**: Automatically wraps text into multiple lines based on a specified width.
- **Alignment**: Offers left, center, and right horizontal alignment options.

## Installation

Install the package via npm:

```bash
npm install babylon-msdf-text
```

This package requires Babylon.js as a peer dependency. Ensure you have it installed in your project:

```bash
npm install @babylonjs/core
```

## Usage

Import the `createTextMesh` function to create a text mesh:

```javascript
import { createTextMesh } from "babylon-msdf-text";
```

The `createTextMesh` function creates a text mesh and accepts the following arguments:

- `name`: `string` - The name of the mesh (required).
- `options`: `TextMeshOptions` - Configuration object with the following properties:
  - `text`: `string` - The text to render (required).
  - `font`: `any` - A JSON file containing font data (required).
  - `atlas`: `string | BABYLON.Texture` - A URL to the font's PNG atlas or a Babylon.js Texture (required).
  - `width`: `number` - Maximum width of the text block in pixels; enables word wrapping (optional).
  - `opacity`: `number` - Text opacity (0 to 1; default: 1).
  - `lineHeight`: `number` - Line height as a percentage (minimum/default: 1).
  - `letterSpacing`: `number` - Letter spacing in pixels (default: 0).
  - `align`: `"left" | "center" | "right"` - Horizontal alignment (default: "left").
  - `color`: `BABYLON.Color3` - Text fill color (default: black).
  - `strokeColor`: `BABYLON.Color3` - Text stroke color (default: black).
  - `strokeWidth`: `number` - Stroke width (default: 0.5).
- `scene`: `BABYLON.Scene` - The Babylon.js scene (required).

### Basic Example

```javascript
// Import dependencies
import * as BABYLON from "@babylonjs/core";
import { createTextMesh } from "babylon-msdf-text";
import fnt from "./fontAssets/roboto-regular.json";
import png from "./fontAssets/roboto-regular.png";

// Set up Babylon.js scene
const canvas = document.getElementById("renderCanvas");
const engine = new BABYLON.Engine(canvas);
const scene = new BABYLON.Scene(engine);
scene.clearColor = new BABYLON.Color3(1, 1, 1);

// Add a camera
const camera = new BABYLON.ArcRotateCamera(
  "camera",
  0,
  0,
  10,
  new BABYLON.Vector3(0, 0, 0),
  scene
);
camera.attachControl(canvas, true);
camera.setPosition(new BABYLON.Vector3(0, 0, -400));

// Create text mesh
const textMesh = createTextMesh("textMesh", {
  text: "Hello\nBabylon",
  font: fnt,
  atlas: png,
  width: 200, // Enables word wrapping
  align: "center",
  color: new BABYLON.Color3(1, 0, 0), // Red text
  strokeColor: new BABYLON.Color3(0, 0, 1), // Blue stroke
  strokeWidth: 1.0,
  opacity: 0.8,
}, scene);

// Center the text mesh
textMesh.position.x = -textMesh.getBoundingInfo().boundingBox.center.x / 2;
textMesh.position.y = textMesh.getBoundingInfo().boundingBox.center.y / 2;

// Render loop
engine.runRenderLoop(() => {
  scene.render();
});

window.addEventListener("resize", () => {
  engine.resize();
});
```

### Instancing Example

To render multiple instances of the same text mesh efficiently, use Babylon.js's instancing:

```javascript
// Create base text mesh
const textMesh = createTextMesh("textMesh", {
  text: "Hello Babylon",
  font: fnt,
  atlas: png,
}, scene);

// Create instances
const instance1 = textMesh.createInstance("instance1");
instance1.position = new BABYLON.Vector3(100, 0, 0);

const instance2 = textMesh.createInstance("instance2");
instance2.position = new BABYLON.Vector3(-100, 0, 0);
```

This approach reuses the mesh geometry, improving performance for multiple text renders.

**Note**: The text content is static once the mesh is created. To display different text, create a new text mesh.

## How to Create MSDF Assets

Generate the required JSON and PNG files using the online MSDF assets generator:

1. Upload your `.ttf` font file.
2. Specify the characters to include (e.g., letters, numbers, symbols, and space).
3. Choose the texture size.
4. Generate and download the MSDF assets.


## Contributing

Contributions are welcome! To contribute:

1. Open an issue to report bugs or suggest features.
2. Submit a pull request with your changes.
3. For major updates, discuss them in an issue first.

## License

This project is licensed under the MIT License. See the LICENSE file for details.