or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

2d-controls.md2d-layout.md3d-controls.md3d-materials.mdindex.mdinput-controls.mdutilities.md
tile.json

tessl/npm-babylonjs--gui

Babylon.js GUI module for creating graphical user interfaces in web-based 3D applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@babylonjs/gui@7.54.x

To install, run

npx @tessl/cli install tessl/npm-babylonjs--gui@7.54.0

index.mddocs/

Babylon.js GUI

Babylon.js GUI is a comprehensive library for creating graphical user interfaces in web-based 3D applications. It provides both 2D overlay controls and full 3D interface elements that can be integrated seamlessly into Babylon.js scenes. The library supports advanced features like dynamic texture manipulation, control positioning and styling, event handling for user interactions, and seamless integration with the Babylon.js rendering pipeline.

Package Information

  • Package Name: @babylonjs/gui
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babylonjs/core @babylonjs/gui

Core Imports

import { AdvancedDynamicTexture, Button, TextBlock, GUI3DManager, HolographicButton } from "@babylonjs/gui";

For full package import:

import * as GUI from "@babylonjs/gui";

CommonJS:

const { AdvancedDynamicTexture, Button, TextBlock, GUI3DManager, HolographicButton } = require("@babylonjs/gui");

Basic Usage

2D GUI Example

import { Engine, Scene, FreeCamera, Vector3 } from "@babylonjs/core";
import { AdvancedDynamicTexture, Button, TextBlock } from "@babylonjs/gui";

// Create basic scene setup
const canvas = document.getElementById("renderCanvas") as HTMLCanvasElement;
const engine = new Engine(canvas, true);
const scene = new Scene(engine);
const camera = new FreeCamera("camera", new Vector3(0, 5, -10), scene);

// Create fullscreen GUI
const advancedTexture = AdvancedDynamicTexture.CreateFullscreenUI("UI");

// Create a button
const button = Button.CreateSimpleButton("button", "Click Me!");
button.widthInPixels = 200;
button.heightInPixels = 40;
button.color = "white";
button.cornerRadius = 20;
button.background = "#4CAF50";

// Add button to GUI
advancedTexture.addControl(button);

// Handle button click
button.onPointerClickObservable.add(() => {
    console.log("Button clicked!");
});

3D GUI Example

import { GUI3DManager, HolographicButton } from "@babylonjs/gui";

// Create 3D GUI manager
const gui3DManager = new GUI3DManager(scene);

// Create 3D button
const button3D = new HolographicButton("button3D");
button3D.text = "3D Button";
button3D.position.x = 2;

// Add to GUI manager
gui3DManager.addControl(button3D);

// Handle 3D button interactions
button3D.onPointerClickObservable.add(() => {
    console.log("3D Button clicked!");
});

Architecture

Babylon.js GUI is organized into two main modules:

  • 2D Module: Provides overlay-style GUI controls rendered on a dynamic texture
  • 3D Module: Enables fully integrated 3D interface elements within the scene
  • Material System: Specialized materials for 3D controls (Fluent Design, MRDL)
  • Event System: Observable-based interaction handling for both 2D and 3D elements
  • Layout System: Grid, stack panel, and container-based layout management

Capabilities

2D GUI Controls

Core 2D interface functionality including buttons, text, images, input fields, and layout containers. Perfect for HUDs, menus, and traditional UI overlays.

class AdvancedDynamicTexture extends DynamicTexture {
  static CreateFullscreenUI(name: string, foreground?: boolean, sceneOrOptions?: Nullable<Scene> | IAdvancedDynamicTextureOptions, sampling?: number, adaptiveScaling?: boolean): AdvancedDynamicTexture;
  static CreateForMesh(mesh: AbstractMesh, width?: number, height?: number, supportPointerMove?: boolean, onlyAlphaTesting?: boolean, invertY?: boolean, materialSetupCallback?: (mesh: AbstractMesh, uniqueId: string, texture: AdvancedDynamicTexture, onlyAlphaTesting: boolean) => void, sampling?: number): AdvancedDynamicTexture;
  addControl(control: Control): AdvancedDynamicTexture;
  removeControl(control: Control): AdvancedDynamicTexture;
}

abstract class Control {
  widthInPixels: number;
  heightInPixels: number;
  left: string | number;
  top: string | number;
  color: string;
  alpha: number;
  isVisible: boolean;
  linkWithMesh(mesh: Nullable<AbstractMesh>): void;
  dispose(): void;
}

2D Controls

2D Layout and Containers

Container controls for organizing and positioning 2D GUI elements including grids, stack panels, and scroll viewers.

class Container extends Control {
  addControl(control: Control): Container;
  removeControl(control: Control): Container;
  getChildByName(name: string): Nullable<Control>;
}

class Grid extends Container {
  addRowDefinition(height: number, isPixel?: boolean): Grid;
  addColumnDefinition(width: number, isPixel?: boolean): Grid;
  addControl(control: Control, row?: number, column?: number): Grid;
}

class StackPanel extends Container {
  isVertical: boolean;
  spacing: string | number;
}

2D Layout

3D GUI Controls

Immersive 3D interface elements that exist within the 3D scene space, including holographic buttons, 3D panels, and spatial menus.

class GUI3DManager {
  constructor(scene?: Scene);
  addControl(control: Control3D): GUI3DManager;
  removeControl(control: Control3D): GUI3DManager;
  dispose(): void;
  onPickedPointChangedObservable: Observable<Nullable<Vector3>>;
  onPickingObservable: Observable<Nullable<AbstractMesh>>;
}

abstract class Control3D {
  position: Vector3;
  scaling: Vector3;
  mesh: Nullable<AbstractMesh>;
  isVisible: boolean;
  parent: Nullable<Container3D>;
  linkToTransformNode(transform: TransformNode): Control3D;
  dispose(): void;
}

3D Controls

3D Materials and Styling

Specialized materials for 3D GUI elements including Fluent Design System materials and Mixed Reality Design Language (MRDL) materials.

class FluentMaterial extends PushMaterial {
  albedoColor: Color3;
  renderHoverLight: boolean;
  renderBorders: boolean;
  borderWidth: number;
}

class HolographicButton extends Button3D {
  text: string;
  imageUrl: string;
  tooltipText: string;
  renderingGroupId: number;
}

3D Materials

Input and Interaction

Comprehensive input handling for both 2D and 3D controls including pointer events, keyboard input, and touch interactions.

// Input controls
class InputText extends Control {
  text: string;
  placeholderText: string;
  maxWidth: string | number;
  focusedBackground: string;
  onTextChangedObservable: Observable<InputText>;
  onFocusObservable: Observable<InputText>;
}

class VirtualKeyboard extends StackPanel {
  static CreateDefaultLayout(): VirtualKeyboard;
  static CreateNumericKeyboard(): VirtualKeyboard;
}

// Event handling
interface AbstractButton3D {
  onPointerClickObservable: Observable<Vector3WithInfo>;
  onPointerEnterObservable: Observable<Control3D>;
  onPointerOutObservable: Observable<Control3D>;
}

Input Controls

Utilities and Styling

Utility classes for measurements, styling, gradients, and value parsing that support both 2D and 3D GUI systems.

class Style {
  fontSize: string | number;
  fontFamily: string;
  fontStyle: string;
  fontWeight: string;
}

class ValueAndUnit {
  constructor(value: number, unit?: number, negativeValueAllowed?: boolean);
  getValue(host: Control): number;
  toString(): string;
  static Parse(source: string): ValueAndUnit;
}

class Measure {
  left: number;
  top: number;
  width: number;
  height: number;
  static Empty(): Measure;
}

Utilities