
<Alert severity="warning" title="Deprecated">
  The Babylon Viewer V1 is deprecated. When building new experiences, please use the [Babylon Viewer V2](/features/featuresDeepDive/babylonViewer).
</Alert>

## Display 3D models on your webpage

The Babylon.js viewer is the simplest way to display 3D content on a web page.

To display a 3D model on your web page:

1. Add a script reference to the viewer

    ```html
    <script src="https://cdn.babylonjs.com/viewer/babylon.viewer.js"></script>
    ```

2. Add a `<babylon>` tag and set the _model_ attribute to point to a `.gltf` or `.glb` file

    ```html
    <babylon model="model.gltf"></babylon>
    ```

    We recommend using the [glTF format](https://github.com/khronosgroup/gltf) (`.gltf` or `.glb`) for displaying 3D models on your webpage. Other formats supported by Babylon.js loaders are also supported by the viewer component, including `.babylon`, `.obj`, and `.stl`.

The Babylon.js viewer automatically provides a [default viewing experience](#default-viewing-experience) for 3D models. All aspects of this experience are configurable. See [Configuring the viewer](//doc.babylonjs.com/extensions/babylonViewer/configuringViewer) for more information on customizing the viewing experience.

## Example

<CodePen pen="QxzBPd" tab="html,result" title="Babylon.js Viewer - Display a 3D model" />

## Resizing

Controlling the size of the viewer is one of the most common configuration operations. It is fairly easy, as the viewer in default mode fills 100% of the width and height of its container. To control the viewer, you can simply style its enclosing container.

<CodePen pen="qMBwar" tab="html,result" title="Babylon.js Viewer - Resize the viewer" />

## Using the viewer in your project

The Babylon.js viewer is available on a CDN as well as an NPM package. The Babylon.js viewer is a wrapper around the Babylon.js engine and follows the same versioning scheme as the engine. The current stable version of the Babylon.js viewer uses the current stable version of the Babylon.js engine, and the preview version of the Babylon.js viewer uses the preview version of the Babylon.js engine.

## CDN

Stable versions of the viewer are available on:

-   https://cdn.babylonjs.com/viewer/babylon.viewer.js (minified)
-   https://cdn.babylonjs.com/viewer/babylon.viewer.max.js

Preview releases (nightlies) of the viewer are available on:

-   https://preview.babylonjs.com/viewer/babylon.viewer.js (minified)
-   https://preview.babylonjs.com/viewer/babylon.viewer.max.js

## NPM

To install the Babylon.js viewer through NPM, use:

```javascript
npm install --save babylonjs-viewer
```

This will install the latest stable version of the viewer, including its needed dependencies.

Afterward, it can be imported into the project using:

```javascript
import "babylonjs-viewer";
```

This will enable the `BabylonViewer` namespace.



## What Is It?

The Babylon.js Inspector is a visual debugging tool created to help pinpoint issues you may have with a scene.

For a video overview of the inspector, check out [Introduction to the inspector - video series](/legacy/inspector/inspectorVideoOverview).

The Inspector offers multiple tools, such as:

- A hierarchical view of your scene
- Multiple property grids to let you dynamically change object properties
- Specific helpers like the skeleton viewer, etc.

Its interface uses two panes:

- The scene explorer pane
- The inspector pane

It can be opened in two ways:

1. Without [ES Modules](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)

```javascript
scene.debugLayer.show();
```

2. Using ES Modules (Avoid using the first approach if you're already using modules):

```javascript
import { Inspector } from '@babylonjs/inspector';

// ... YOUR SCENE CREATION
Inspector.Show(scene, {});
```

![debug layer overview](/img/features/debuglayer/debuglayer.webp)

### Embedded Mode

The two panes can also be opened in an [embedded mode](/typedoc/interfaces/babylon.iinspectoroptions):

```javascript
scene.debugLayer.show({
  embedMode: true,
});
```

or:

```javascript
Inspector.Show(scene, {
  embedMode: true
});
```

![embed mode](/img/features/debuglayer/embedmode.webp)

To hide the inspector:

```javascript
scene.debugLayer.hide();
```

or:

```javascript
Inspector.Hide(); // You don't need to pass the scene
```

## Scene explorer pane

![scene explorer](/img/features/debuglayer/sceneExplorer.webp)

The scene explorer displays a hierarchical view of your scene. You can filter by name in the filter bar if you want to find a specific entry.

Clicking a line selects it, and the Inspector automatically updates to reflect the properties of the selected item.

Some entities offer shortcuts to contextual actions.

## Scene actions

![scene actions](/img/features/debuglayer/sceneactions.webp)

The scene shortcuts are as follows:

- The first 3 actions turn on a specific gizmo mode ([translation](/typedoc/classes/babylon.transformnode#translate), rotation, scaling). After you click one of them, you can click a node in the Scene Explorer or directly in your scene, and then control it with a gizmo:

![gizmo](/img/features/debuglayer/gizmo.webp)

- The fourth action is a picker. Just pick a mesh in your scene, and it will be selected in your Scene Explorer.
- The last one forces the Scene Explorer to update. For performance reasons, the Scene Explorer does not listen to all changes that can happen in the scene, so you may need to refresh it manually.

## Mesh actions

![mesh actions](/img/features/debuglayer/meshactions.webp)

The mesh shortcuts are as follows:

- The first action will enable the bounding box gizmo:

![bounding box gizmo](/img/features/debuglayer/boundingboxgizmo.webp)

- The second action will show/hide the mesh.

## Light actions

![light actions](/img/features/debuglayer/lightactions.webp)

You can use the light action to turn a light on and off.

## Camera actions

![camera actions](/img/features/debuglayer/cameraactions.webp)

You can use the camera action to switch the active camera when there are multiple cameras in a scene.

## GUI control actions

![gui control actions](/img/features/debuglayer/controlactions.webp)

You can use the GUI control actions to:

- Display outline of a control
- Show / hide a specific control

## Rendering pipeline actions

![Rendering pipeline actions](/img/features/debuglayer/renderpipelineactions.webp)

When your scene does not contain a default rendering pipeline, you can right-click on the rendering pipelines node to get a context menu letting you create a new default rendering pipeline.

## Inspector pane

The Inspector pane contains 4 tabs:

![inspector](/img/features/debuglayer/inspector.webp)

- The property grid, which displays configurable controls for the currently selected entity:

![property grid](/img/features/debuglayer/property.webp)

- The debug pane lets you turn features on and off. It also lets you display a grid and turn viewers (bones or physics) on and off:

![debug pane](/img/features/debuglayer/debugpane.webp)

- The statistics pane gives information about all metrics captured by the engine:

![stats pane](/img/features/debuglayer/statspane.webp)

- The tools pane lets you access utilities such as screen capture, recording, and several tools related to glTF:

![tools](/img/features/debuglayer/tools.webp)

## Popup mode

There are occasions when opening the Inspector in a child window is preferable. The canvas may be too small to use the Inspector effectively, or the Inspector may cover too much of the canvas, making the scene hard to debug. There are a few ways to pop the Inspector into a child window that is still connected to the scene. The first is to click the icon on the right side of the pane header bar adjacent to the close button. 

![popup](/img/features/debuglayer/popup.webp)

This pops out the selected pane - either Scene Explorer or Inspector - into a child window. If the panes have been opened in [embedded mode](/legacy/inspector#embedded-mode), the embedded Inspector opens in a single child window. Additionally, the Inspector can be opened as a popup by default. The individual Scene Explorer and Inspector panes can be opened as popups with the following code:

``` javascript
var debugLayer = await scene.debugLayer.show();

debugLayer.popupSceneExplorer();
debugLayer.popupInspector();
```
<Playground id="#KN5JBQ#3" title="Popup mode for Inspector panes" description="An example of opening inspector panes in popup mode" image="/img/playgroundsAndNMEs/inspectorPopup.webp" />

### Embedded Popup Mode
Additionally, the embedded mode inspector can be opened as a popup by default:

``` javascript
var debugLayer = await scene.debugLayer.show({
    embedMode: true
});

debugLayer.popupEmbed()
```
<Playground id="#KN5JBQ#5" title="Embedded popup mode for Inspector panes" description="An example of opening embedded inspector in popup mode" image="/img/playgroundsAndNMEs/inspectorEmbedPopup.webp" />

## Specific debug tools

Specific debug tools can be found throughout the Inspector:

## Render grid

This tool (available in the Debug pane) will render a grid on the (0,0,0) plane:

![grid](/img/features/debuglayer/grid.webp)

## Bones viewer

This tool (available in the skeleton property grid) will render your skeletons:

![bones](/img/features/debuglayer/BonesView.webp)

## Skeleton Map Shader

This tool (available in the mesh property grid when the mesh has an attached skeleton) will render a unique color on the mesh, for each bone, showing their total contribution:

![bones](/img/features/debuglayer/BonesMap.webp)

## Bone Weight Shader

This tool (available in the mesh property grid when the mesh has an attached skeleton) will render a heat map showing the selected bones' contribution:

![bones](/img/features/debuglayer/BonesWeight.webp)

## Physics viewer

This tool (available in the Debug pane) will render your physics impostors:

![physics](/img/features/debuglayer/physics.webp)

## Normal painter

This tool (available in the property pane when you select a mesh) will paint the normals on your active mesh:

![paint normal](/img/features/debuglayer/paintnormal.webp)

## Vertex normal viewer

This tool (available in the property pane when you select a mesh) will render the vertex normals of a mesh:

![vertex normal](/img/features/debuglayer/vertexnormal.webp)

## Texture painter

This tool (available in the property pane when you select a material that contains textures) will render the texture directly as an emissive one:

![texture painter](/img/features/debuglayer/texturepainter.webp)

## Extensibility

The Inspector can be easily extended to allow manipulation of custom node properties. Simply define your custom properties in the node's `inspectableCustomProperties` array, and they will be available under the CUSTOM heading after selecting the node in the Inspector.

<Playground id="#LQF5QR#2" title="Inspector custom properties for a node" description="An example of inspector custom properties for a node" image="/img/playgroundsAndNMEs/inspectorCustomProperties.webp" />

```javascript
myNode.inspectableCustomProperties = [
  {
    label: "My boolean field",
    propertyName: "myBooleanField",
    type: BABYLON.InspectableType.Checkbox,
  },
  {
    label: "My color field",
    propertyName: "myColor3Field",
    type: BABYLON.InspectableType.Color3,
  },
  {
    label: "My quaternion field",
    propertyName: "myQuaternionField",
    type: BABYLON.InspectableType.Quaternion,
  },
  {
    label: "My numeric range field",
    propertyName: "myRangeField",
    type: BABYLON.InspectableType.Slider,
    min: 0.5,
    max: 5.0,
    step: 0.1,
  },
  {
    label: "My string field",
    propertyName: "myStringField",
    type: BABYLON.InspectableType.String,
  },
  {
    label: "My vector field",
    propertyName: "myVector3Field",
    type: BABYLON.InspectableType.Vector3,
  },
  {
    label: "My tab field",
    type: BABYLON.InspectableType.Tab,
  },
  {
      label: "My options field",
      propertyName: "myOptionsField",
      options: [
          { label: "options1", value: 1 },
          { label: "options2", value: 2 }
      ],
      callback: (option)=>{
      
      },
      type: BABYLON.InspectableType.Options,

  },
  {
      label: "My button field",
      propertyName: "myButtonField",
      callback: ()=>{
      
      },
      type: BABYLON.InspectableType.Button,

  }
];
```

The Inspector can also be extended to allow manipulation of custom material properties.
<Playground id="#LQF5QR#52" title="Inspector custom properties for a material" description="An example of inspector custom properties for a material"/>



# Support for Physics Engines

Physics engines are third-party external programs that can be plugged into Babylon.js. Depending on their features, they emulate "real-life" interactions between objects, which can be meshes, solid particles from the solid particle system, or some cameras. One feature of a physics engine is the addition of gravity to a scene.

There are 2 physics architectures in Babylon.js.

- a Version 2 (V2 for short) with support for modern Physics Engines.

  > [🚀 You can find the V2 API documented here.](/features/featuresDeepDive/physics/usingPhysicsEngine)  

- Version 1 (V1 for short), which is a pre-6.0 Legacy API.

  > [⚠️ The documentation for V1 has been moved to the Legacy section.](/legacy/physics)

#### We strongly recommend using V2 over V1. [A migration guide is here](/features/featuresDeepDive/physics/migrate).

## Physics V2

There are plugins for 1 physics engine:

1. Havok - a powerful engine used in AAA games.

It needs to be enabled before use.

This architecture allows finer-grained control over your physics scene by distinguishing between collision shapes and physical bodies.
A typical use case is to have one collision shape used by numerous bodies.
This allows a lower memory footprint and more efficient memory addressing.
A special effort has been put into better performance for a huge number of bodies. This is also the case for the collision callback mechanism.

A broad overview of the Physics V2 advancements is available on this [Medium article](https://medium.com/@babylonjs/physics-v2-overview-ed36039ce1e7).

## Physics V1

There are plugins for 3 physics engines:

1. Cannon.js - a wonderful physics engine written entirely in JavaScript.
2. Oimo.js - a JS port of the lightweight Oimo physics engine.
3. Ammo.js - a JS port of the bullet physics engine.

All need to be enabled before use.

Interactions between objects are achieved by impostors, simple objects that are attached to complex objects in a scene. The impostor can be assigned physical attributes such as mass, friction, a coefficient of restitution, impulse, and linear and angular velocity.

Two imposters can be connected using joints such as a hinge or ball and socket.

Ammo also allows the creation of soft bodies.


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



# Space markup

## Introduction
Space markup is used to quickly construct simple XR simulators and helps
organize phantom objects in space. These objects can "interact" with the user,
emulating walls, slopes, curved surfaces, stairs, elevators, etc.

### Preparing the space
To enable this functionality, we need to include the SPACE_MARKUP
feature in the configuration.

Useful option types and floor description:
```typescript
type TSpaceMarkUpOptions = {
	// Minimum height difference recognized as a step or elevation change
	minStepValue: 0.15,
	
	// Maximum height difference the user can overcome in a "stepping" style
	maxStepValue: 0.45,
	
	// Duration of the step-up/step-down animation (default: 60 frames)
	stairStepAnimationDurationInFrames: 60,
	
	// If set, allows the user to move within this radius before being pulled back
	// to the last registered floor position. Works on x, z axes.
	// Essentially, how far the user can deviate from the boundary.
	borderOffset: 0.1,
	
	// When returning the user to a safe zone, this value determines the offset
	// away from the boundary to prevent triggering repeated floor boundary exits
	// due to minor jitter.
	returnOffset: 0.3,
	
	// Backward correction
	// The headset extends slightly forward relative to the user's center of mass.
	// This correction reduces desynchronization between the head and body position.
	//
	// [VR-P1-DEVICE]HEAD
	//                body
	//                body
	//         foot-P2-foot
	//
	// In the schematic, P1 represents the headset center,
	// while P2 is the correction point for XZ alignment (typically 0.1 - 0.22).
	realBodyXZCorrection: 0.17,
	
	// Default ray length for surface detection (shorter is better).
	// Can and should be adjusted dynamically using setRayLength().
	defaultRayLength: 3,

    //...
}

export type FloorDescription = {
	// The mesh representing the surface
	mesh: AbstractMesh;
	
	// If true, movement beyond this surface will be blocked
	lock?: boolean;
	
	// List of surfaces that can be transitioned to
	allowList?: AbstractMesh[];

    // Enables sliding logic	
	isSlope?: boolean;
	
	// Critical angle (in degrees) at which sliding starts
	criticalAngleDeg?: number;
};
```

In application code:

```typescript

const options = <TXRServiceOptions>{
    mode:'immersive-vr',
    features:{
	    SPACE_MARKUP:{
		    nativeConfig:<TSpaceMarkUpOptions>{ /* ... */}
        }
    }
}

const xrService =   new XRService();
xrService.init(options);
await xrService.activateXR();

// Feature
const spaceMarkUp  =   await xrService.extractFeatureEnv('SPACE_MARKUP');

spaceMarkUp.addFloors(<FloorDescription[]>[
	{mesh:scene.getMeshById('MainFloor')!},
	{mesh:stair,},
    /* ... */
	{mesh:slope, isSlope:true, criticalAngleDeg:5}
]);

spaceMarkUp.run();
// Also is possible set pause
spaceMarkUp.pause();
```

Additionally, you can configure a special effect material that changes the
scene when the user approaches the boundary of the allowed area.
```typescript
export interface ISpaceMarkUpEnv {
	//...
	enableBorderVFX(active:boolean):void;
	setBorderVFXMaterial(material:NodeMaterial):void;
	// ...
}
```


Legacy

Legacy Features

Coming next

Physics

Learn all about the powerful physics capabilities of Babylon.js.

The Inspector

Learn all about the incredibly powerful debug layer called "The Inspector" in Babylon.js.

Audio

Dive into everything you could want to know about using the Babylon.js sound engine for simple to advanced audio.

Babylon.js Viewer (V1)

The viewer is the simplest way to display 3D content on a web page.