This project provides Babylon Native integration into React Native.
Babylon React Native is in the early phase of its development, and has the following limitations:
- Android and iOS support only - support for Windows is planned, but the timeline is currently unknown.
- Touch input only - mouse, keyboard, and controllers are not yet supported.
- Single view only - multiple views are not yet supported (only a single view can be displayed).
It is also worth noting that Babylon React Native relies heavily on newer React Native constructs including JSI to get the performance characteristics required for real time rendering. JSI allows for direct synchronous communication between native code and JavaScript code, but is incompatible with "remote debugging." If you need to debug your JavaScript code that uses Babylon React Native, you should enable Hermes and use "direct debugging" (e.g. chrome://inspect or edge://inspect). See the React Native documentation for more info.
See the package usage for installation instructions and/or the Playground app's App.tsx for example usage.
This quick overview will help you get started developing in the Babylon React Native repository. We support development on Windows and MacOS, but assume the use of PowerShell in the instructions below (unless otherwise noted).
If you are interested in making contributions, be sure to also review CONTRIBUTING.md.
Step 1 for all development environments and targets is to clone the repo. Use a git-enabled terminal to follow the steps below.
git clone https://github.com/BabylonJS/BabylonReactNative
Babylon React Native makes extensive use of submodules to supply its dependencies, so it's also necessary to set up the submodules.
cd BabylonReactNative
git submodule update --init --recursive
The Playground sample/test app is a standard React Native app, and as such also makes extensive use of NPM packages to supply its dependencies, so it's also necessary to install these packages.
cd Apps/Playground
npm install
For iOS, CocoaPods are also used, and these must be installed.
cd Apps/Playground/ios
pod install --repo-update
Required Tools: Android Studio (including NDK 21.3.6528147), CMake, Ninja, JDK 13
- The
PATH
environment variable must include the path to adb (typically ~/Library/Android/sdk/platform-tools/). - The
PATH
environment variable must include the path to Ninja, or Ninja must be installed via a package manager. - The
ANDROID_HOME
environment variable must be defined (typically ~/Library/Android/sdk). - The
ANDROID_SDK_ROOT
environment variable must be defined (typically ~/Library/Android/sdk). - The
ANDROID_AVD_HOME
environment variable must be defined if you plan to use Android emulators (typically ~/.android/avd). - The
JAVA_HOME
environment variable must be defined to point to the correct version of the JDK (typically /usr/libexec/java_home -v 13).
You can typically configure your environment by editing ~/.zshrc
and adding the following:
export PATH=$PATH:~/Library/Android/sdk/platform-tools/
export PATH=$PATH:~/path_to_ninja_binary/ # Only for manual installations of Ninja (not package manager-based installations).
export ANDROID_HOME=~/Library/Android/sdk
export ANDROID_SDK_ROOT=~/Library/Android/sdk
export ANDROID_AVD_HOME=~/.android/avd
export JAVA_HOME=$(/usr/libexec/java_home -v 13)
Required Tools: Android Studio (including NDK 21.3.6528147), CMake, Ninja, Visual Studio 2019
- The
PATH
environment variable must include the path to adb (typically %LOCALAPPDATA%/Android/sdk/platform-tools/). - The
PATH
environment variable must include the path to Ninja, or Ninja must be installed via a package manager. - The
ANDROID_HOME
environment variable must be defined (typically %LOCALAPPDATA%/Android/sdk). - The
JAVA_HOME
environment variable must be defined (typically %ProgramFiles%/Android/Android Studio/jre).
Required Tools: Android Studio (including NDK 21.3.6528147)
With Ubuntu, you can install needed packages by this command:
sudo apt-get install adb ninja-build openjdk-14-jdk android-sdk
Update PATH with this commands:
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
Troubleshootings:
- If the Metro server is not started with
npm run android
, you can start it manually by runningnpm run start
in a terminal. - Android Studio is the tool of choice for downloading the various versions of NDK.
- If something goes wrong with the build
npm run android --verbose
can give some hints. - If the emulator is not launched by the build, you can run
~/Android/Sdk/emulator/emulator @name_of_your_image
.
On either Mac or Windows, NPM is used to build and run the Playground sample/test app from the command line. Open a command prompt at the root of the BabylonReactNative repo if you don't have one already open.
cd Apps/Playground
npm run android
After having run the above commands, you can also open Apps/Playground/android
in Android Studio and run the app from there.
iOS can only be built on a Mac. Additionally, CMake
must manually be run to generate the XCode project that the Playground XCode workspace includes.
pushd Apps/Playground/node_modules/@babylonjs/react-native/ios
cmake -G Xcode -DCMAKE_TOOLCHAIN_FILE=../submodules/BabylonNative/Dependencies/ios-cmake/ios.toolchain.cmake -DPLATFORM=OS64COMBINED -DENABLE_ARC=0 -DENABLE_BITCODE=1 -DDEPLOYMENT_TARGET=12 -DENABLE_GLSLANG_BINARIES=OFF -DSPIRV_CROSS_CLI=OFF -DENABLE_PCH=OFF .
popd
cd Apps/Playground
npm run ios
After having run the above commands, you can also open Apps/Playground/ios/Playground.xcworkspace
in XCode and run the app from there.
UWP can only be built on a PC. CMake
must be manually run to generate project definitions for BabylonNative dependencies.
- Run
npm install
in Apps\Playground. - Run
npm install
in Package. - Run
npx gulp buildUWP
in Package. This command will run cmake and build BabylonNative dependencies. It may take a while to complete. - In Apps\Playground, run
npm run windows
.
Note: if you experience build issues for Apps\Playground related to autolinking, try running
npx react-native autolink-windows
in the Apps\Playground folder. You can also runnpm run windows-verbose
to view logging.
When making local changes, the following manual test steps should be performed within the Playground app to prevent regressions. These should be checked on Android and iOS, and ideally in both debug and release, but minimally in release.
- Basic rendering - launch the Playground app and make sure the model loaded and is rendering at 60fps.
- Animation - make sure the loaded model is animating.
- Input handling - swipe across the display and make sure the model rotates around the y-axis.
- Display rotation - rotate the device 90 degrees and make sure the view rotates and renders correctly.
- View replacement - tap the Toggle EngineView button twice to replace the render target view.
- Engine dispose - tap the Toggle EngineScreen button twice to dispose and re-instantiate the Babylon engine.
- Suspend/resume - switch to a different app and then back to the Playground and make sure it is still rendering correctly.
- Fast refresh (debug only) - save the App.tsx file to trigger a fast refresh.
- Dev mode reload (debug only) - in the Metro server console window, press the
R
key on the keyboard to reload the JS engine and make sure rendering restarts successfully. - XR mode - tap the Start XR button and make sure XR mode is working.
- XR display rotation - rotate the device 90 degrees and make sure the view rotates and renders correctly.
- XR view replacement - tap the Toggle EngineView button twice to replace the render target view.
- XR suspend/resume - switch to a different app and then back to the Playground and make sure it is still rendering correctly.
If you want to test using a local build of the NPM package with your own React Native app, you can do so with a gulp
command on a Mac (this requires a Mac as it builds binaries for both iOS and Android).
cd Package
npm install
gulp pack
The NPM package will be built into the Package
directory where the gulp
command was run. Once the local NPM package has been built, it can be installed into a project using npm
.
cd <directory of your React Native app>
npm install <root directory of your BabylonReactNative clone>/Package/Assembled/babylonjs-react-native-0.0.1.tgz
If you wish to test the locally-built NPM packages with the apps in the PackageTest
directory, before running npm install
be sure to run:
cd Apps\PackageTest\<package test app version>
npm uninstall @babylon/react-native
# If you're also updating the react-native-windows package:
npm uninstall @bablyon/react-native-windows
This will allow the local package dependencies to update without the package-lock.json file worrying about new content without a new version number. You can then run the above command to install the locally-built NPM modules located in Package/Assembled
.
If you want to consume @babylonjs/react-native
as source in your React Native app (for debugging or for iterating on the code when making a contribution), you can install the package source directory as an npm package.
cd <directory of your React Native app>
npm install <root directory of your BabylonReactNative clone>/Modules/@babylonjs/react-native
cd ios
pod install
This will create a symbolic link in your node_modules
directory to the @babylonjs/react-native
source directory. However, this also requires a custom metro.config.js
as the Metro bundler does not support symbolic links by default. See the GitHub issue on this for a solution.
For iOS the XCode project needs to be generated with CMake
as described above and added to your xcworkspace
.
If you believe you have found a security vulnerability in this repository, please see SECURITY.md.
We have seen issues when using npm 7+ to install local symbolic linked npm packages. For this reason, we suggest using npm 6.13 for BabylonReactNative development. To install npm 6.13, run the following command:
npm install -g npm@6.13