repository·master·Indexed 21 days ago
https://github.com/brianzinn/react-babylonjsA library that integrates the Babylon.js real-time 3D engine with React, enabling the creation of 3D scenes using a declarative syntax, reusable components, and hooks. It supports both web and React Native environments, providing a component-based architecture for Babylon.js core and GUI elements, along with specialized hooks for accessing the scene and engine.
react-babylonjs is a library that integrates the Babylon.js real-time 3D engine with React. It allows developers to build 3D scenes using React's component-based architecture and declarative patterns while leveraging the power of the Babylon.js engine.The react-babylonjs examples demonstrate various implementation patterns for integrating Babylon.js with React. Key topics covered in the examples include:
To improve consistency with the BabylonJS API, several components and event patterns were renamed or expanded in v1.0.0:
VRExperience is now VRExperienceHelper.Button.onPointerDown has been renamed to Button.onPointerDownObservable to match BabylonJS naming conventions.The <shadowGenerator /> component provides three ways to manage which meshes cast shadows:
shadowCastChildren: (Custom react-babylonjs prop) Automatically includes all child mesh elements in the shadow map's renderList. This is the easiest method for dynamic scenes.shadowCasters: A string array prop used to explicitly name the meshes that should be included in the shadow map's renderList.shadowCastersExcluding: A string array prop used to explicitly name the meshes that should be excluded from the shadow map's renderList.When using the Playground component, imports behave as follows:
package.json.Limitations:
.tsx files are supported for local imports.The Hooks API provides access to the Babylon.js Scene or Engine objects, as well as the render loop and mesh interactions (like hover/click).
Important: Hooks for SceneLoader and AssetManager require that the component using them be wrapped in a React <Suspense> component to handle asynchronous loading.
The library supports intrinsic JSX, allowing you to use Babylon.js elements (like cameras, lights, and meshes) as if they were standard HTML tags. You do not need to import these elements; they are understood by the renderer.
Common intrinsic elements include:
<freeCamera /><hemisphericLight /><ground /><box /> (and other mesh types)Method Calls via Props:
When calling Babylon.js methods declaratively, you can pass an array to a prop to represent the method's arguments. For example, setTarget={[Vector3.Zero()]} is the declarative equivalent of calling camera.setTarget(Vector3.Zero()).
<Scene>
<freeCamera name="camera1" position={new Vector3(0, 5, -10)} setTarget={[Vector3.Zero()]} />
<hemisphericLight name="light1" intensity={0.7} direction={new Vector3(0, 1, 0)} />
<ground name="ground" width={6} height={6} />
</Scene>In React Native environments, EngineView is the component used to bridge the Babylon.js Engine to a native view. This allows you to render the Babylon.js engine content within the React Native view hierarchy.
Note that when using multiple views with the same Engine, pointer events may only work on one of the views, though the visual output is mirrored across canvases using that shared engine.
// Note: The specific implementation details are located in the example source
// but the conceptual usage involves passing a Babylon.js Engine to EngineView.
<EngineView engine={yourBabylonEngine} />In react-babylonjs, context often needs to cross the boundary between the react-dom renderer and the Babylon.js Engine/Scene components. Because these components operate in different rendering contexts, standard React context providers defined in your main application tree may not be accessible inside the Scene.
To solve this, you can implement a ContextBridge. The pattern involves:
react-dom layer.Scene component using a bridge component.This is necessary for libraries that rely heavily on context, such as Theme providers or state management libraries like Redux. For new projects, using state management libraries that do not rely on context (like Zustand) can avoid this complexity entirely.
// Note: The actual implementation is located in ./context-bridge/ContextBridge.tsx
// The pattern follows: Capture context outside -> Provide context inside the Scene.The react-babylonjs library provides hooks to access core Babylon.js objects like the Scene or Engine, and to interact with the render loop or mesh events (hover/click).
Important: Hooks for SceneLoader and AssetManager require that the component using them be wrapped in a React <Suspense> boundary.
Due to conflicts with React.SVGProps<T>, certain component names have been prefixed with babylon- to ensure they work correctly in JSX. When using these components, use the prefixed name:
<babylon-button /> instead of button<babylon-ellipse /> instead of ellipse<babylon-image /> instead of image<babylon-line /> instead of line<babylon-polygon /> instead of polygon<babylon-text /> instead of textMost Babylon.js elements are available as declarative React components. These components follow the standard Babylon.js documentation API.
Because these are generated from Babylon typings, the props available on a component typically match the properties of the corresponding Babylon.js class. For example, a <box /> component will accept props corresponding to the Box geometry.