About using BabylonJS functionality in Twinfinity

Leveraging BabylonJS in Twinfinity: Navigating Limitations and Opportunities

In our mission to provide a flexible and open environment for our users, Twinfinity leverages BabylonJS, a powerful game engine. By exposing the scene and engine of BabylonJS, we aim to empower users with extensive capabilities while maintaining transparency. However, incorporating BabylonJS into Twinfinity's unique ecosystem presents certain challenges and changes to how BabylonJS works. To ensure a smooth experience, we have made some adaptations that may impose limitations on its functionalities within our platform. These limitations may cause errors on either side, both in Twinfinity and in BabylonJS. Problems that may occur only in certain conditions and circumstances. We recommed 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 functionalities in Twinfinity, alongside known workarounds and our approach to balancing openness with system stability.

Low-Risk Functionalities

Adding Meshes

Adding new meshes into the scene remains a straightforward task. BabylonJS’s robust support for mesh operations is well compatible with Twinfinity and allows users to enhance their Twinfinity projects with custom shapes and models with minimal risk.

Loading GLTF Models

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

Textures and Materials

Using textures and materials to own meshes is another low-risk area. Users can utilize BabylonJS’s extensive material system to customize the appearance of their 3D objects, although there are specific material-related considerations in higher-risk scenarios discussed later.

High-Risk Functionalities

Post Processes

Implementing post-process effects using BabylonJS carries a higher risk. These operations can introduce significant overhead and may not integrate seamlessly with Twinfinity’s rendering pipeline. Users should proceed with caution and thoroughly test post-processes in their specific use cases. Many post-processes will not work.

Standard Material-Dependent Features

Functionalities relying on BabylonJS's standard material, such as clip planes, pose 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 that are optimimized for rendering performance, but in that some sacrifices to BabylonJS feature support have been made.

Known Incompatibilities

Multiple Cameras

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

Extra Lights

Adding additional 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 to this.

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 behavior or crashes.

Changing Materials on Twinfinity Meshes

Altering materials on meshes created by Twinfinity can lead to conflicts, unexpected behaviour and crashes. The system's predefined material management should be adhered to for reliable performance. This only apply to meshes added by Twinfinity’s API, BabylonJS meshes that added do have full support for materials.

BabylonJS Scene Exports

Exporting scenes created in Twinfinity back to BabylonJS format is not supported. Users should be aware that 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.

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

However, please note that if you overide the Twinfinity camera, change camera or similar actions Twinfinity API functionality that relies on the Twinfinity default camera may not work.

Converting Twinfinity meshes to BabylonJS meshes

It is possible to convert Twinfinity meshes to BabylonJS meshes which will allow for those meshes to be worked with utilizing the full power of BabylonJS. Though note that this will have a significant negative impact on performance. If you go this path with your solution make sure to only show a small subset of the model like a couple of rooms, or part of a floor. BabylonJS out of the box is not optimized for showing the massive amounts of geometry that digital twin contains. This is possible, but is not recommended unless absolutely necessary.

Our Approach to BabylonJS Integration

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

We feel that the the potential issues are outweighed by the added value of utilizing BabylonJS's capabilities. Twinfinity’s open approach aims to give users 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 guide you in making informed decisions while leveraging BabylonJS functionalities in Twinfinity. Embrace the possibilities, but tread thoughtfully, and always feel free to reach out with any concerns or insights.

Summary Table of Functionalities and Risk Levels

Functionality	Risk Level	Notes

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-Compat	Design with a single camera in mind.
Extra Lights	Non-Compat	Stick to the default lighting setup.
Multiple Scenes	Non-Compat	Twinfinity operates with a single scene.
Changing Materials on Twinfinity Meshes	Non-Compat	Follow predefined material management for reliability.
BabylonJS Scene Exports	Non-Compat	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.