Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/brianzinn/react-babylonjs

React for Babylon 3D engine
https://github.com/brianzinn/react-babylonjs

3d 3d-engine 3d-models babylonjs physics react reactjs vr

Last synced: 4 months ago
JSON representation

React for Babylon 3D engine

Lists

README 

        
# react-babylonjs



> _'react-babylonjs'_ integrates the Babylon.js real time 3D engine with React



`react-babylonjs` lets you build your scene and components using a familiar

declarative syntax with the benefits of reusable components and hooks. The

Babylon.js API is mostly covered declaratively thanks to code generation and

even custom props allow you to declaratively add shadows, physics, 3D models,

attach 2D/3D UI to meshes, etc.



Fully supports hooks. Full support for TypeScript with auto-completion on

elements and compile time checks. Context API and hooks provide easy access to

Scene/Engine/Canvas.



[![NPM version](http://img.shields.io/npm/v/react-babylonjs.svg?style=flat-square)](https://www.npmjs.com/package/react-babylonjs)

[![NPM downloads](http://img.shields.io/npm/dm/react-babylonjs.svg?style=flat-square)](https://www.npmjs.com/package/react-babylonjs)



## How to Install



```sh

$ npm i react-babylonjs @babylonjs/core @babylonjs/gui

```



OR



```sh

$ yarn add react-babylonjs @babylonjs/core @babylonjs/gui

```



_No third party dependencies outside of React + babylon.js_



### Babylon.js 4.x

> Babylon.js 4.x is not currently compatible (follow peer dependency warnings) with @latest version. The last version compatible with both 4.x and 5.x was 3.0.31.

```sh

# Babylonjs.4.x only

$ yarn add [email protected]

```



## Models



If you are using 3D models ensure you have added the `@babylonjs/loaders` NPM.

It is not a direct dependency, but registers loaders as plugins via imports with

side effects:



- Register **all** model types `import @babylonjs/loaders;`

- OBJ `import '@babylonjs/loaders/OBJ';`

- glTF `import '@babylonjs/loaders/glTF';`



_(more instructions on model loading in ES6

[here](https://doc.babylonjs.com/divingDeeper/developWithBjs/treeShaking#loaders)

)_



# Usage Styles



`react-babylonjs` tries to remain unopinionated about how you integrate

BabylonJS with React. This module provides a 100% declarative option and/or you

can customise by adding code. There are lots of escape hatches where you can

switch to imperative coding and direct access to objects.



## Connecting the pieces



If you are new to React or babylon.js (or both) there is some learning ahead.

The babylon.js documentation site is really useful for understanding the basics

of lighting, cameras, etc. This project aims to make easy to integrate those

into React using JSX.



Here we re-use a `SpinningBox` component that can be clicked or hovered. These

reusable components can be used to compose a declarative scene. We are using

hooks for the clicking, hovering and spinning.



![Connecting the pieces](https://raw.githubusercontent.com/brianzinn/react-babylonjs/master/packages/react-babylonjs/docs/images/react-babylonjs-boxes.gif)



```jsx

import React, { useRef, useState } from 'react'

import {

  Engine,

  Scene,

  useBeforeRender,

  useClick,

  useHover,

} from 'react-babylonjs'

import { Vector3, Color3 } from '@babylonjs/core'



const DefaultScale = new Vector3(1, 1, 1)

const BiggerScale = new Vector3(1.25, 1.25, 1.25)



const SpinningBox = (props) => {

  // access Babylon scene objects with same React hook as regular DOM elements

  const boxRef = useRef(null)



  const [clicked, setClicked] = useState(false)

  useClick(() => setClicked((clicked) => !clicked), boxRef)



  const [hovered, setHovered] = useState(false)

  useHover(

    () => setHovered(true),

    () => setHovered(false),

    boxRef

  )



  // This will rotate the box on every Babylon frame.

  const rpm = 5

  useBeforeRender((scene) => {

    if (boxRef.current) {

      // Delta time smoothes the animation.

      var deltaTimeInMillis = scene.getEngine().getDeltaTime()

      boxRef.current.rotation.y +=

        (rpm / 60) * Math.PI * 2 * (deltaTimeInMillis / 1000)

    }

  })



  return (

    

      

    

  )

}



export const SceneWithSpinningBoxes = () => (

  


    

      

        

        

        

        

      

    

  


)

```



[code sandbox for above](https://codesandbox.io/s/epic-darwin-tohk0)



## Hooks, Shadows and Physics (and optionally TypeScript, too)



You can declaratively use many features together - here only the button click

handler actually has any code - and we have declarative Physics, GUI, Lighting

and Shadows. demo:

[Bouncy demo](https://brianzinn.github.io/react-babylonjs/?path=/story/physics--bouncy-playground-story)



```jsx

import React, { useRef } from 'react';

// full code at https://github.com/brianzinn/create-react-app-typescript-babylonjs



const App: React.FC = () => {

  let sphereRef = useRef>();



  const onButtonClicked = () => {

    if (sphereRef.current) {

      sphereRef.current.physicsImpostor!.applyImpulse(

        Vector3.Up().scale(10),

        sphereRef.current.getAbsolutePosition()

      );

    }

  };



  return (

    

      

        

        

        

          

        

        

          

          

            

              

                  

                    

                      

                    

                  

              

            

          

        



        

          

        

        

      

    

  );

}

```



## React Native



No online examples for native, but you can integrate using

`EngineCanvasContext.Provider`:



```jsx

import React, { useState } from 'react';

import { View } from 'react-native';



import { EngineView, useEngine } from '@babylonjs/react-native';

import { Camera } from '@babylonjs/core';

import { EngineCanvasContext, Scene } from 'react-babylonjs';



const EngineScreen: FunctionComponent = (props: ViewProps) => {



  const engine = useEngine();

  const [camera, setCamera] = useState();



  return (

    

      

        {engine &&

          

             setCamera(camera)}

            />

            

            { /* rest of declarative scene/components here */ }

          

        }

      

      

    

  );

};

```



## Developer Experience and Fast Refresh



With declarative (TSX/JSX) coding and fast refresh, you experience the same

development workflow in 3D - ie: save changes in your editor and see them

immediately in the browser. Note in this capture when the light is dimmed that

the state changes persist even **after** code updates and scene refresh.



![babylon.js Fast Refresh](https://raw.githubusercontent.com/brianzinn/react-babylonjs/master/packages/react-babylonjs/docs/images/react-babylonjs-hmr.gif)



## API



This project uses code generation, which allows fast reconciliation and

excellent typings support.



> [react-babylonjs API](packages/react-babylonjs/docs/api.md)



## Release History and changes



> [Changes and commit history](packages/react-babylonjs/docs/changes.md)



## Storybook



~50 sample web pages with viewable source code on

[github pages](https://brianzinn.github.io/react-babylonjs/).



## Example Projects



- [Create React App (JavaScript)](https://github.com/brianzinn/create-react-app-babylonjs)

  CRA JavaScript implementation. Github pages has live examples of typical and

  declarative usage some with Redux.

- [Create React App (TypeScript)](https://github.com/brianzinn/create-react-app-typescript-babylonjs)

  CRA 3 TypeScript. Examples of physics, shadows, etc.



## Contributors



- Huge shout out to [Konsumer](https://github.com/konsumer) that helped bring

  this project to the next level. The ideas and code sandboxes from issue #6

  inspired the code generation and HOC + Context API integration.

- [seacloud9](https://github.com/seacloud9) for adding

  [storybook](https://brianzinn.github.io/react-babylonjs/),

  [GSAP demo](https://brianzinn.github.io/react-babylonjs/?path=/story/integrations--gsap-timeline),

  [dynamic terrain](https://brianzinn.github.io/react-babylonjs/?path=/story/babylon-basic--dynamic-terrain)

  (extension) &

  [PIXI demo](https://brianzinn.github.io/react-babylonjs/?path=/story/integrations--pixi-story).

- [hookex](https://github.com/hookex) has made the largest contribution :)

  Proper texture handling

  [demo](https://brianzinn.github.io/react-babylonjs/?path=/story/textures--image-texture),

  Node parenting,

  [demo](https://brianzinn.github.io/react-babylonjs/?path=/story/babylon-basic--transform-node)

  Full Screen GUI

  [demo](https://brianzinn.github.io/react-babylonjs/?path=/story/gui--gui-full-screen),

  Effect Layers

  [glow demo](https://brianzinn.github.io/react-babylonjs/?path=/story/special-fx--glow-layer),

  behaviors

  [demo](https://brianzinn.github.io/react-babylonjs/?path=/story/behaviors--pointer-drag-behavior),

  useHover & useClick hooks

  [demo](https://brianzinn.github.io/react-babylonjs/?path=/story/hooks--use-hover-event)

  and react-spring integration

  [demo](https://brianzinn.github.io/react-babylonjs/?path=/story/integrations--react-spring).

  Author of `react-babylon-spring` -

  https://github.com/hookex/react-babylon-spring.

- [dennemark](https://github.com/dennemark) add support for

  `CascadedShadowGenerator`, `createPortal` and `Html` (project HTML in scene -

  ported from `drei`). Also, stories for

  [Snippet Material](https://brianzinn.github.io/react-babylonjs/?path=/story/babylon-basic--snippet-material)

  and

  ["tunnel" zustand integration](https://brianzinn.github.io/react-babylonjs/?path=/story/integrations--zustand-tunnel).

  Added `RenderOnDemand` to customize render loops.

- [kencyke](https://github.com/kencyke) created a cool multi-canvas + cloud

  point repo that insipired creation of `` as host

  element.

- [flostellbrink](https://github.com/flostellbrink) fixed the

  `react-babylon-spring` integration and added GH action for Storybook

  ([github pages](https://brianzinn.github.io/react-babylonjs))

- [voronp](https://github.com/voronp) add `isPaused` Engine prop to skip rendering



> Thanks also to all the people who have contributed with

> issues/questions/discussions. All the great ideas and requests are why this

> project evolved beyond an experiment.



Made with ♥