---
title: "About using BabylonJS functionality in Twinfinity"
canonical: "https://help.twinfinity.com/space/HCFD/414089225/About%20using%20BabylonJS%20functionality%20in%20Twinfinity"
format: markdown
---
In our mission to provide a flexible and open environment for our users, Twinfinity leverages BabylonJS, a powerful game engine. By exposing the BabylonJS scene and engine, we aim to empower you with extensive capabilities while maintaining transparency. However, incorporating BabylonJS into Twinfinity's unique ecosystem presents certain challenges and changes how BabylonJS works. To ensure a smooth experience, we've made some adaptations that may impose limitations on its functionality within our platform. These limitations may cause errors on either side, both in Twinfinity and in BabylonJS — problems that may only occur under certain conditions and circumstances. We recommend that you do not manipulate meshes that are created or owned by the Twinfinity API, such as the ones in `ifcroot`.

This article explores the risks and limitations associated with using BabylonJS functionality in Twinfinity, alongside known workarounds and our approach to balancing openness with system stability.

## Low-risk functionalities

### Adding meshes

Adding new meshes to the scene remains a straightforward task. BabylonJS's robust support for mesh operations is well compatible with Twinfinity and lets you enhance your Twinfinity projects with custom shapes and models with minimal risk.

### Loading GLTF models

Twinfinity supports loading GLTF models through BabylonJS without significant issues. This lets you bring in complex 3D models efficiently, leveraging BabylonJS's versatile GLTF loader.

### Textures and materials

Using textures and materials on your own meshes is another low-risk area. You can use BabylonJS's extensive material system to customize the appearance of your 3D objects, although there are specific material-related considerations in the higher-risk scenarios discussed below.

## High-risk functionalities

### Post processes

Implementing post-process effects with BabylonJS carries a higher risk. These operations can introduce significant overhead and may not integrate seamlessly with Twinfinity's rendering pipeline. Proceed with caution and thoroughly test post-processes in your specific use case. Many post-processes will not work.

### Standard material-dependent features

Functionality relying on BabylonJS's standard material, such as clip planes, poses a higher risk. We recommend using Twinfinity's built-in alternatives for these features to ensure compatibility and stability within our system. Twinfinity uses custom materials optimized for rendering performance, but some sacrifices to BabylonJS feature support have been made as a result.

> Twinfinity now ships first-class clip planes — prefer them over raw BabylonJS clip planes. See [Clip planes](https://twinfinity.atlassian.net/wiki/spaces/HCFD/pages/1098743810).

## Known incompatibilities

### Multiple cameras

Twinfinity currently does not support multiple camera setups within a single scene.

### Extra lights

Adding lights beyond the default configuration will not work for Twinfinity meshes. Twinfinity's lighting model is optimized for a specific setup, and deviations may cause visual inconsistencies. There are lighting options provided in the Twinfinity BimAPI as a workaround.

### Multiple scenes

Managing multiple scenes concurrently is not supported. Twinfinity operates with a single scene context, and attempting to introduce additional scenes may lead to unexpected behaviour or crashes.

### Changing materials on Twinfinity meshes

Altering materials on meshes created by Twinfinity can lead to conflicts, unexpected behaviour and crashes. Stick to the system's predefined material management for reliable performance. This only applies to meshes added by Twinfinity's API — BabylonJS meshes that you add yourself have full support for materials.

### BabylonJS scene exports

Exporting scenes created in Twinfinity back to BabylonJS format is not supported. Twinfinity's scene graph and data structures are optimized for our platform and may not align with BabylonJS's export requirements.

## Known workarounds

### Using pick ray for picking

For selecting objects within a scene when working with custom cameras, pick ray functionality is a reliable method that will work.

```ts
const example = api.viewer.camera.pick({
  type: PickOptionType.Ray,
  ray: new Ray(new Vector3(20, 10, 20), new Vector3(30, 10, 30)),
});
```

Note that if you override the Twinfinity camera, change cameras, or take similar actions, Twinfinity API functionality that relies on the default camera may not work.

### Converting Twinfinity meshes to BabylonJS meshes

It's possible to convert Twinfinity meshes to BabylonJS meshes, which lets you work with those meshes using the full power of BabylonJS. Note that this has a significant negative impact on performance. If you go this route, make sure to only show a small subset of the model — a couple of rooms, or part of a floor. Out of the box, BabylonJS is not optimized for showing the massive amounts of geometry that a digital twin contains. This is possible, but not recommended unless absolutely necessary.

## Our approach to BabylonJS integration

We encourage you to explore BabylonJS's functionality within Twinfinity, but with a clear understanding of the associated risks. BabylonJS's evolving nature means breaking changes may occur, impacting compatibility. If Twinfinity updates the version of BabylonJS, we cannot take responsibility for the consequences that may have in your apps. While we strive to provide a robust interface, these integrations are used **at your own risk**.

We feel the potential issues are outweighed by the added value of using BabylonJS's capabilities. Twinfinity's open approach aims to give you the tools to innovate and create, despite the inherent limitations and challenges.

We remain committed to transparency and user empowerment. Your feedback is invaluable as we continue to refine our platform and improve the integration experience.

By providing this detailed overview, we hope to help you make informed decisions while leveraging BabylonJS functionality in Twinfinity. Embrace the possibilities, but tread thoughtfully, and always feel free to reach out with any concerns or insights.

## Summary of functionalities and risk levels

| Functionality | Risk level | Notes |
| --- | --- | --- |
| Adding meshes | Low | Smooth integration for custom shapes and models. |
| Loading GLTF models | Low | Efficiently loads complex 3D models. |
| Textures and materials | Low | Extensive support with some higher-risk caveats. |
| Post processes | High | Potential overhead and integration challenges. |
| Standard material-dependent features | High | Use Twinfinity's alternatives for stability. |
| Multiple cameras | Non-compatible | Design with a single camera in mind. |
| Extra lights | Non-compatible | Stick to the default lighting setup. |
| Multiple scenes | Non-compatible | Twinfinity operates with a single scene. |
| Changing materials on Twinfinity meshes | Non-compatible | Follow predefined material management for reliability. |
| BabylonJS scene exports | Non-compatible | Scene graphs are optimized for Twinfinity, not for export. |
| Using pick ray for picking | Workaround | Reliable method for object selection. |

Feel free to reach out if you have any questions or need further clarification on how to navigate these limitations while working with BabylonJS in Twinfinity.