diff --git a/Modules/@babylonjs/react-native/README.md b/Modules/@babylonjs/react-native/README.md index 5d975cd6f..e7ba4869f 100644 --- a/Modules/@babylonjs/react-native/README.md +++ b/Modules/@babylonjs/react-native/README.md @@ -1,117 +1,183 @@ # Babylon React Native +Babylon React Native brings [Babylon.js](https://github.com/BabylonJS/Babylon.js) to React Native through [Babylon Native](https://github.com/BabylonJS/BabylonNative). Since 2.0.0, a single `@babylonjs/react-native` package contains the native sources for Android, iOS, and Windows. Windows support remains experimental. + ## Usage This quick overview will help you understand the constructs provided by Babylon React Native and how to use them in a React Native application. +### Installation + +The latest stable release is **2.0.7**. In an existing React Native application using the [versions below](#supported-versions), install the package and its peer dependencies: + +```sh +npm install @babylonjs/react-native@2.0.7 @babylonjs/core@^9.0.0 react-native-permissions@^5.4.1 +``` + +Use the React version required by your React Native application. React Native 0.81 requires **Node.js 20.19.4 or later**. Follow the platform configuration below before building the app. + +To load formats such as glTF, also install `@babylonjs/loaders` at the same version as `@babylonjs/core` and import it in your application. + ### Dependencies -This package has several **peer dependencies**. If these dependencies are unmet, `npm install` will emit warnings. Be sure to add these dependencies to your project. +The package declares `@babylonjs/core` (>=9.0.0), `react`, `react-native`, and `react-native-permissions` (>=3.0.0) as **peer dependencies**. Add them to your application and resolve any peer dependency errors or warnings during installation. + +`useEngine` uses `react-native-permissions` to request camera access for XR and native camera use. Follow the [react-native-permissions setup instructions](https://github.com/zoontek/react-native-permissions#setup): enable the `Camera` permission handler in your iOS `Podfile`, provide `NSCameraUsageDescription` in `Info.plist`, and declare `android.permission.CAMERA` in `AndroidManifest.xml` when using these features. + +The native camera and XR plugins can be [disabled at build time](#plugins-selection), but `react-native-permissions` is still a declared peer dependency and is imported by the JavaScript module. + +### Supported Versions + +These are the resolved React Native versions in the committed Playground lockfiles at each release tag, not the lower bounds of manifest ranges. The permissive `react` and `react-native` peer dependency ranges do **not** guarantee that every newer React Native version is compatible. -The `react-native-permissions` dependency is required for XR capabilities of Babylon.js (to request camera permissions automatically). Be sure to follow the `react-native-permissions` [instructions](https://github.com/react-native-community/react-native-permissions#setup) to update your `Podfile` and `Info.plist` (iOS) and/or `AndroidManifest.xml` (Android). These plugins can be disabled and by such, dependency to `react-native-permissions` is not needed anymore (see below). +| Babylon React Native version | React Native (iOS / Android) | React Native Windows | +| ---------------------------- | --------------------------- | -------------------- | +| 2.0.7 / master | 0.81.6 | 0.81.35 | +| 2.0.6 | 0.81.6 | 0.81.35 | +| 2.0.5 | 0.81.6 | 0.81.21 | +| 2.0.0 - 2.0.4 | 0.79.4 | 0.79.1 | -### React Native minimum version +For 2.0.6 and 2.0.7, the Windows Playground locks React Native 0.81.6 with **React Native Windows pinned to 0.81.35** to match the published NuGet packages; 0.81.4 is only the lower bound of the manifest's `^0.81.4` React Native range. Windows project generation uses the legacy renderer and Hermes. -| BabylonReactNative version | iOS / Android | Windows | -| -------------------------- | -------------------- | ----------------------------- | -| next / main | react-native 0.81.6+ | react-native-windows 0.81.4+ | -| 2.0.0 - 2.0.2 | react-native 0.79.4 | react-native-windows 0.79.1 | +The Babylon.js column below records the package's `@babylonjs/core` peer dependency. The Babylon Native commits are the source pins in `Package/gulpfile.js` at the corresponding release tags. + +| Babylon React Native version | Babylon.js peer dependency | Babylon Native commit | +| ---------------------------- | -------------------------- | --------------------- | +| 2.0.7 / master | >=9.0.0 | [f4d9efbeeabcfec24105373b99e54fe147669fc1](https://github.com/BabylonJS/BabylonNative/commit/f4d9efbeeabcfec24105373b99e54fe147669fc1) | +| 2.0.6 | >=9.0.0 | [feb0227be8890ec5dcd28c6bfc18275a98bf8d45](https://github.com/BabylonJS/BabylonNative/commit/feb0227be8890ec5dcd28c6bfc18275a98bf8d45) | +| 2.0.5 | >=9.0.0 | [ce2edf0851e0c8483559832a4f8eb9d39c6b2f53](https://github.com/BabylonJS/BabylonNative/commit/ce2edf0851e0c8483559832a4f8eb9d39c6b2f53) | +| 2.0.4 | >=9.0.0 | [ce2edf0851e0c8483559832a4f8eb9d39c6b2f53](https://github.com/BabylonJS/BabylonNative/commit/ce2edf0851e0c8483559832a4f8eb9d39c6b2f53) | +| 2.0.3 | >=9.0.0 | [ce2edf0851e0c8483559832a4f8eb9d39c6b2f53](https://github.com/BabylonJS/BabylonNative/commit/ce2edf0851e0c8483559832a4f8eb9d39c6b2f53) | +| 2.0.2 | >=9.0.0 | [887a0446c2ce5d379d931d802071cf6f9e008c6a](https://github.com/BabylonJS/BabylonNative/commit/887a0446c2ce5d379d931d802071cf6f9e008c6a) | +| 2.0.1 | >=5.53.1 | [3ccba7a6f741705ce611819aefacbbb8062393e7](https://github.com/BabylonJS/BabylonNative/commit/3ccba7a6f741705ce611819aefacbbb8062393e7) | +| 2.0.0 | >=5.53.1 | [9a50d722d493524e1b315dd48fed6b0ed6d062c8](https://github.com/BabylonJS/BabylonNative/commit/9a50d722d493524e1b315dd48fed6b0ed6d062c8) | + +2.0.7 updates Babylon Native and its JsRuntimeHost dependency, and removes obsolete `minz` library links from the iOS podspec and Windows project. The Babylon.js and React Native baselines are unchanged from 2.0.6. + +See the [release notes](https://github.com/BabylonJS/BabylonReactNative/releases) for changes and the [repository README](https://github.com/BabylonJS/BabylonReactNative#contributing) for local development and packaging instructions. ### Android Configuration -The minimum Android SDK version is 21. This must be set as `minSdkVersion` in the consuming project's `build.gradle` file. +Use the SDK, NDK, and JDK required by your React Native version. For React Native 0.81, the effective minimum is **Android API 24**, even though this module's standalone Gradle fallback is API 21. Set `minSdkVersion` in the consuming project's `build.gradle` accordingly; do not lower React Native's minimum. + +The supported Android ABIs are `armeabi-v7a`, `arm64-v8a`, and `x86_64`. The 32-bit `x86` ABI is not supported and is filtered out of `reactNativeArchitectures`; use an `x86_64` or `arm64-v8a` emulator instead. + +#### ARCore + +The module defaults to ARCore **1.22.0**. Since 2.0.4, consuming apps can override it in their root `android/build.gradle`, for example: + +```groovy +ext.arcoreVersion = '1.56.0' +``` + +The Playground uses 1.56.0. The native build resolves the actually selected ARCore AAR, including when Gradle dependency resolution overrides the declared version. This can help resolve duplicate-class conflicts involving older ARCore versions and `installreferrer`. + +Since 2.0.6, the module declares ARCore as optional in its Android manifest. Applications that require AR should configure their own manifest and check device support; camera permission setup is still required for XR. + +The Android Gradle configuration also avoids applying `kotlin-android` when the Kotlin extension is already registered, including by Android Gradle Plugin 9's built-in Kotlin support. This does not change the React Native compatibility baselines above. ### iOS Configuration -The minimum deployment target version is 16. This must be set as `iOS Deployment Target` in the consuming project's `project.pbxproj`, and must also be set as `platform` in the consuming project's `Podfile`. -Make sure `pod install` is called from the ios folder after npm install. +The minimum deployment target is **iOS 16.0** for the current package. Set the app's `iOS Deployment Target` and the `Podfile` platform to at least `16.0`: -#### Workspace -In your app workspace, add a reference to BabylonReactNative project by adding these lines: +```ruby +platform :ios, '16.0' ``` + +After `npm install`, run `pod install` from your app's `ios` directory. The npm postinstall generates `Build/iOS/ReactNativeBabylon.xcodeproj` on macOS; it does not install CocoaPods dependencies. + +#### Workspace +In your app workspace, add a reference to the Babylon React Native project by adding these lines: +```xml ``` -to your app `xcworkspace/content.xcworkspacedata` file. +to your app's `.xcworkspace/contents.xcworkspacedata` file. The path shown assumes the workspace is in the app's `ios` directory. #### CMake To disable post install CMake generation, set this variable before running `npm install`: -``` +```sh export BABYLON_NO_CMAKE_POSTINSTALL=1 ``` -To use the system cmake (e.g. a Homebrew or system install) instead of the cmake bundled in the npm package, set this variable before running `npm install`: -``` +Since 2.0.3, you can use a system CMake (e.g. a Homebrew installation) instead of the `cmake-runtime` 3.31.0 dependency. Set this variable before running `npm install`: +```sh export BABYLON_USE_SYSTEM_CMAKE=1 ``` -To override the iOS deployment target used by the generated `ReactNativeBabylon.xcodeproj` (defaults to `16.0`), set this variable before running `npm install` so it matches your app's Podfile `platform :ios` value: -``` +Since 2.0.4, you can override the iOS deployment target used by the generated `ReactNativeBabylon.xcodeproj` (defaults to `16.0`). Set this variable before running `npm install` so it matches your app's `Podfile` platform: +```sh export BABYLON_IOS_DEPLOYMENT_TARGET=16.0 ``` -The previous default of iOS 12 caused Xcode 26's Clang to crash while compiling `DeviceImpl_iOS.mm`; the default is now `16.0` and this variable lets you raise it further (or, at your own risk, lower it) without patching the deployment target from a Podfile `post_install` hook. +The previous iOS 12 default caused Xcode 26's Clang to crash while compiling `DeviceImpl_iOS.mm`. The override changes the generated native project only; it does not lower the podspec's iOS 16 minimum or change your app's deployment target. + +If you skipped project generation or changed these settings after installation, regenerate it on macOS from your app root: + +```sh +node node_modules/@babylonjs/react-native/postinstall.js +``` + +Unset `BABYLON_NO_CMAKE_POSTINSTALL` first if it was enabled, then rerun `pod install` after regenerating the project. ### Plugins selection -Plugins can be disabled at build time. They are all enabled by default and disabling is done with environment variables: +The NativeCamera and NativeXR plugins are enabled by default. For Android and iOS, disable them with environment variables set before generating/building the native project: To disable Camera plugin: -``` +```sh export BABYLON_NATIVE_PLUGIN_NATIVECAMERA=0 ``` For Native XR: -``` +```sh export BABYLON_NATIVE_PLUGIN_NATIVEXR=0 ``` -### Platform Native Packages - -Starting with BabylonReactNative NPM 2.0.0+, one single package is available for iOS, Android and Windows versus multiple packages before. +Keep the variables set when running `pod install` and native builds. Disabling plugins does not remove the JavaScript peer dependency on `react-native-permissions`. -Babylon.js minimal version: +### Windows Configuration -|BabylonReactNative version | Babylon.js version | BabylonNative commit | -| ----------- | ------------------------ | --- | -|2.0.2 | 9.0.0 | 17d3e4e6b1233547d7ccfdf89da04c327340f8fc -|2.0.0 | 8.3.0 | 6c25966e8f8c0f3a0c13fdf77064f1bde790391f +Windows support is experimental. The 2.0.6 and 2.0.7 integrations use React Native Windows **0.81.35** and its matching NuGet packages. Keep the React Native Windows npm version aligned with its published NuGet version rather than allowing npm to select a newer release independently. +The module's MSBuild project builds the embedded Babylon Native sources using CMake and the React Native Windows project's generated C++/WinRT projections. See the [repository's Windows instructions](https://github.com/BabylonJS/BabylonReactNative#universal-windows-platform-uwp) and [packaged-consumer build workflow](https://github.com/BabylonJS/BabylonReactNative/blob/master/.github/workflows/test_windows.yml) for the current UWP, legacy-renderer, NuGet, and C++20 configuration. ### `useEngine` `useEngine` is a **custom React hook** that manages the lifecycle of a Babylon engine instance in the context of an owning React component. `useEngine` creates an engine instance **asynchronously** which is used to create and configure scenes. Typically scene initialization code should exist in a `useEffect` triggered by an `engine` state change. For example: ```tsx +import React, { useEffect } from 'react'; import { useEngine } from '@babylonjs/react-native'; -import { Engine, Scene } from '@babylonjs/core'; +import { Scene } from '@babylonjs/core'; -const MyComponent: FunctionComponent = (props: MyComponentProps) => { +const MyComponent = () => { const engine = useEngine(); useEffect(() => { if (engine) { const scene = new Scene(engine); // Setup the scene! + return () => scene.dispose(); } }, [engine]); - return ( - <> - - ); + return null; } ``` +`useEngine` initially returns `undefined` and disposes the engine when its owning component unmounts. Dispose scenes created by an effect in that effect's cleanup. + ### `EngineView` `EngineView` is a **custom React Native view** that presents a `camera` from a Babylon `scene`. A `camera` therefore is assigned to the `EngineView`. For example: ```tsx +import React, { useEffect, useState } from 'react'; import { useEngine, EngineView } from '@babylonjs/react-native'; -import { Engine, Scene, Camera } from '@babylonjs/core'; +import { Scene, Camera, MeshBuilder } from '@babylonjs/core'; -const MyComponent: FunctionComponent = (props: MyComponentProps) => { +const MyComponent = () => { const engine = useEngine(); const [camera, setCamera] = useState(); @@ -119,8 +185,10 @@ const MyComponent: FunctionComponent = (props: MyComponentProp if (engine) { const scene = new Scene(engine); scene.createDefaultCamera(true); + scene.createDefaultLight(true); + MeshBuilder.CreateBox('box', {}, scene); setCamera(scene.activeCamera!); - // Setup the scene! + return () => scene.dispose(); } }, [engine]); @@ -139,14 +207,16 @@ e.g. ```tsx ``` -To configure anti-aliasing, a property called `antiAliasing` can be changed to a value of 0 or 1 (disable anti-aliasing, default), 2, 4, 8 or 16 (anti-aliasing samples). +To configure anti-aliasing, set `antiAliasing` to 0 or 1 (disabled; the default is 0), or to 2, 4, 8, or 16 (MSAA sample count). e.g. ```tsx - + ``` +Use `displayFrameRate` to control the FPS overlay (enabled by default in development builds). On Android and iOS, the `onInitialized` callback receives an `EngineViewCallbacks` object with `takeSnapshot(): Promise`, which returns a base64-encoded JPEG. Snapshots are not implemented on Windows. + Note: Currently only one `EngineView` can be active at any given time. Multi-view will be supported in a future release. The Android specific `androidView` property can help set the type of the view used for rendering. Depending on user needs and performance, refer to the table below. [`TextureView`](https://developer.android.com/reference/android/view/TextureView) can be inserted anywhere in the view hierarchy, but is less efficient. [`SurfaceView`](https://developer.android.com/reference/android/view/SurfaceView) can only be fully above or fully below the rest of the UI, but is more efficient. diff --git a/README.md b/README.md index e57a08678..de563b0d9 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Babylon React Native brings the power and flexibility of [Babylon.js](https://gi ### Limitations -1. Android and iOS only - support for Windows is experimental. -1. Touch input only - mouse, keyboard, and controllers are not yet supported. +1. Android and iOS are supported; support for Windows is experimental. +1. Touch input is supported on Android and iOS; Windows also supports mouse input. Keyboard and controller input are not yet supported. 1. Single view only - multiple views are not yet supported (only a single view can be displayed). ### What is Supported from Babylon.js @@ -23,7 +23,22 @@ React Native applications targeting [JavaScriptCore on iOS](https://reactnative. ### Other -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](https://reactnative.dev/docs/hermes) for more info. +Babylon React Native uses JSI for direct synchronous communication between native code and JavaScript code. Debugging must keep JavaScript running on the device: browser-based remote JavaScript debugging is incompatible with JSI. For Hermes applications, use [React Native DevTools](https://reactnative.dev/docs/0.81/react-native-devtools). + +## Supported Versions + +The latest stable npm release is **[@babylonjs/react-native 2.0.7](https://www.npmjs.com/package/@babylonjs/react-native/v/2.0.7)**. Since 2.0.0, a single package contains the sources for Android, iOS, and Windows; separate platform packages are no longer needed. + +2.0.7 updates Babylon Native to [f4d9efbeeabcfec24105373b99e54fe147669fc1](https://github.com/BabylonJS/BabylonNative/commit/f4d9efbeeabcfec24105373b99e54fe147669fc1), including its JsRuntimeHost dependency update, and removes obsolete `minz` library links from the iOS and Windows builds. The Babylon.js and React Native baselines are unchanged from 2.0.6. + +| Package version | Babylon.js peer dependency | React Native (Android / iOS) | React Native Windows | +| --------------- | -------------------------- | ---------------------------- | -------------------- | +| 2.0.7 / master | >=9.0.0 | 0.81.6 | 0.81.35 | +| 2.0.6 | >=9.0.0 | 0.81.6 | 0.81.35 | + +The React Native versions above are the resolved Playground lockfile baselines, not a guarantee of compatibility with every newer release. For 2.0.6 and 2.0.7, the Windows Playground locks React Native 0.81.6 with React Native Windows 0.81.35; 0.81.4 is only the lower bound of the manifest's `^0.81.4` React Native range. Windows support remains experimental; its npm version is pinned to match the published React Native Windows NuGet packages. + +See the [package README](Modules/@babylonjs/react-native/README.md#supported-versions) for earlier releases and the Babylon Native commit used by each release, and the [release notes](https://github.com/BabylonJS/BabylonReactNative/releases) for changes. ## Usage @@ -35,7 +50,7 @@ Note: Official support for React Native frameworks, like Expo, is not provided b ## Contributing -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](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell) in the instructions below (unless otherwise noted). +This quick overview will help you get started developing in the Babylon React Native repository. Android development is possible on Windows, macOS, and Linux; iOS requires macOS, and Windows builds require Windows. The cross-platform commands below use [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) unless otherwise noted. If you are interested in making contributions, be sure to also review [CONTRIBUTING.md](CONTRIBUTING.md). @@ -45,117 +60,129 @@ The following section will describe how to build locally a package and how to de ### **Preparing a new Repo** -**Required Tools:** [git](https://git-scm.com/), [Node.js (16.13.0+)](https://nodejs.org/en/download/) +**Required Tools:** [git](https://git-scm.com/), [Node.js (20.19.4+)](https://nodejs.org/en/download/), and [CMake](https://cmake.org/) on `PATH`. The Windows CI builds use Node.js 22. Install the platform-specific tools described below before running setup. Step 1 for all development environments and targets is to clone the repo. Use a git-enabled terminal to follow the steps below. -``` +```powershell git clone https://github.com/BabylonJS/BabylonReactNative +cd BabylonReactNative ``` -Run setup_dev.js script : +From a fresh checkout, run the developer setup script: -``` +```powershell cd Package node setup_dev.js ``` This will also automatically do the following to prepare your repo for development: -- Update git submodules to fetch Babylon Native and its dependencies +- Install the build tools, Playground dependencies, and module dependencies +- Download the Babylon Native commit pinned in `Package/gulpfile.js` and use CMake to assemble its dependency sources (no git submodule setup is required) +- Compile the TypeScript module and copy the generated files back into the local module - [macOS only] Run CMake to generate the iOS Xcode project for Babylon React Native -- [macOS only] Run `pod install` to install cocoa pod dependencies -Finally run Playground Test App using: +The Playground uses `react-native-test-app`. From `Package`, launch Android with: -``` -cd Apps/Playground -npm run ios +```powershell +cd ..\Apps\Playground +npx react-native run-android ``` -or +For iOS, install the CocoaPods dependencies separately before launching (from `Package`, on macOS): +```powershell +cd ..\Apps\Playground\ios +pod install ``` -cd Apps/Playground -npm run android -``` + +Then open `Apps\Playground\ios\BRNPlayground.xcworkspace` in Xcode, select the `Playground` scheme, and run it on an iOS device or simulator. Use this workspace rather than the CLI-selected `Playground.xcworkspace`: it includes the CMake-generated Babylon Native project needed to build and link the native libraries. + +For Windows, use the manifest preparation and project generation steps in the [Windows section](#universal-windows-platform-uwp) instead. ### **Configuring a Mac Dev Environment** -**Required Tools:** [Android Studio](https://developer.android.com/studio/) (including NDK 23.1.7779620), [CMake](https://cmake.org/), [Ninja](https://ninja-build.org/), [JDK 13](https://www.oracle.com/java/technologies/javase-jdk13-downloads.html) +For iOS, install [Xcode](https://developer.apple.com/xcode/) with its command line tools and [CocoaPods](https://cocoapods.org/). The current module requires **iOS 16.0 or later** and includes fixes for Xcode 26. -- 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](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages). -- 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). +For Android, install [Android Studio](https://developer.android.com/studio/), [Ninja](https://ninja-build.org/), and **JDK 17**. Follow the [React Native 0.81 environment setup](https://reactnative.dev/docs/0.81/set-up-your-environment) and install the SDK, build tools, and NDK selected by the app's Gradle configuration rather than the older NDK 23 toolchain. -You can typically configure your environment by editing `~/.zshrc` and adding the following: +Add the following to `~/.zshrc` for Android development (these commands use zsh, not PowerShell): +```sh +export ANDROID_HOME="$HOME/Library/Android/sdk" +export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools" +export JAVA_HOME=$(/usr/libexec/java_home -v 17) ``` -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) -``` + +Ensure CMake and Ninja are also on `PATH`. ### **Configuring a Windows Dev Environment** -**Required Tools:** [Android Studio](https://developer.android.com/studio/) (including NDK 23.1.7779620), [CMake](https://cmake.org/), [Ninja](https://ninja-build.org/), [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) +For Android, install [Android Studio](https://developer.android.com/studio/), [Ninja](https://ninja-build.org/), and **JDK 17**. Follow the [React Native 0.81 environment setup](https://reactnative.dev/docs/0.81/set-up-your-environment) for SDK and NDK installation. -- 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](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages). -- 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). +For Windows/UWP builds, install [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) with the C++ and UWP development tools. The current CI uses Windows SDK **10.0.22621.0**. + +- Add CMake, Ninja, and `%LOCALAPPDATA%\Android\Sdk\platform-tools` to `PATH` as appropriate for your target. +- Set `ANDROID_HOME` to your SDK location (typically `%LOCALAPPDATA%\Android\Sdk`). +- Set `JAVA_HOME` to your JDK 17 installation, not an obsolete Android Studio `jre` directory. ### **Configuring a Linux Dev Environment** -**Required Tools:** [Android Studio](https://developer.android.com/studio/) (including NDK 23.1.7779620) +Linux can be used for Android development. Install [Android Studio](https://developer.android.com/studio/) and follow the [React Native 0.81 environment setup](https://reactnative.dev/docs/0.81/set-up-your-environment) for the SDK and NDK. -With Ubuntu, you can install needed packages by this command: +On Ubuntu, install the additional build tools with: -``` -sudo apt-get install adb ninja-build openjdk-14-jdk android-sdk +```sh +sudo apt-get install ninja-build openjdk-17-jdk cmake ``` -Update PATH with these commands: +Configure your shell with your SDK and JDK paths: +```sh +export ANDROID_HOME="$HOME/Android/Sdk" +export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools" +export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 ``` -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 -``` + +Adjust `JAVA_HOME` for your distribution and architecture. ### **Troubleshooting** -- If the Metro server is not started with `npm run android`, you can start it manually by running `npm run start` in a terminal. +- If Metro is not started with `npx react-native run-android`, run `npm start` from `Apps\Playground` in another 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 something goes wrong with the Android build, `npx react-native run-android --verbose` can give some hints. +- Use an `x86_64` or `arm64-v8a` Android emulator. The 32-bit `x86` ABI is not supported and is filtered out by the module's Gradle configuration. +- See the [package's Android configuration](Modules/@babylonjs/react-native/README.md#android-configuration) for ARCore version overrides and the [iOS configuration](Modules/@babylonjs/react-native/README.md#ios-configuration) for CMake and deployment target overrides. - If the emulator is not launched by the build, you can run `~/Android/Sdk/emulator/emulator @name_of_your_image`. - For other emulator issues, follow the [instructions](https://github.com/BabylonJS/BabylonNative/blob/master/Documentation/AndroidEmulator.md) from Babylon Native documentation. - Refer to the [Babylon Native documentation](https://github.com/BabylonJS/BabylonNative/tree/master/Documentation#babylon-native-documention) for additional information that may help troubleshoot issues. #### Universal Windows Platform (UWP) -UWP can only be built on a PC. `CMake` must be manually run to generate project definitions for BabylonNative dependencies. +Windows support is experimental and currently uses a UWP consumer with the legacy renderer, Hermes, and React Native Windows NuGet packages. From the repository root, prepare the Windows-specific Playground manifests **before** running developer setup: + +```powershell +Copy-Item Apps\Playground\package-windows.json Apps\Playground\package.json -Force +Copy-Item Apps\Playground\package-lock-windows.json Apps\Playground\package-lock.json -Force +cd Package +node setup_dev.js +cd ..\Apps\Playground +node generate-windows-test-app.mjs +``` + +These copies change tracked files locally; keep the Windows manifests and lockfiles in sync when intentionally updating dependencies. React Native Windows is pinned to **0.81.35** to match its published NuGet packages. + +Project generation enables autolinking and NuGet mode. The module's MSBuild project now generates and builds its embedded Babylon Native sources with CMake and reuses the app's C++/WinRT projections; there is no `gulp buildUWP` task. -1. Run `npm ci` in Apps\Playground\Playground. -1. Run `npm ci` in Package. -1. Run `npx gulp buildUWP` in Package. This command will run cmake and build BabylonNative dependencies. It may take a while to complete. -1. In Apps\Playground\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\Playground folder. You can also run `npm run windows-verbose` to view logging. +Use the [Windows source-build workflow](.github/workflows/windows.yml) as the reference for the current x64 Release build, including `UseExperimentalNuget=true`, `ReactNativeNuGet.targets`, and the generated test-app C++20 settings. The [packaged-consumer workflow](.github/workflows/test_windows.yml) checks the same integration using the npm tarball. ### **Testing in the Playground App** ### -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. +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. Run the XR checks on compatible physical ARCore/ARKit devices with camera permissions enabled. 1. **Basic rendering** - launch the Playground app and make sure the model loaded and is rendering at 60fps. 1. **Animation** - make sure the loaded model is animating. -1. **Input handling** - swipe across the display and make sure the model rotates around the y-axis. +1. **Input handling** - swipe across the display (or drag with the left mouse button on Windows) and make sure the model rotates around the y-axis. 1. **Display rotation** - rotate the device 90 degrees and make sure the view rotates and renders correctly. 1. **View replacement** - tap the *Toggle EngineView* button twice to replace the render target view. 1. **Engine dispose** - tap the *Toggle EngineScreen* button twice to dispose and re-instantiate the Babylon engine. @@ -175,33 +202,36 @@ Every change for a Pull Request will trigger the build of the NPM package. The a To get a `.tgz` that can be shared or published, follow these steps: -Prepare tools: +From a fresh checkout, install the packaging tools: -``` +```powershell cd Package -npm install +npm ci ``` -Prepare package dependencies -``` -cd ../Modules/@babylonjs/react-native -export BABYLON_NO_CMAKE_POSTINSTALL=1 -npm install +Install the module dependencies, skipping iOS project generation until the native sources have been assembled: + +```powershell +cd ..\Modules\@babylonjs\react-native +$env:BABYLON_NO_CMAKE_POSTINSTALL = "1" +npm ci +Remove-Item Env:\BABYLON_NO_CMAKE_POSTINSTALL ``` -Build BabylonNative source tree, build TypeScript copy mandatory files: +In a macOS/Linux shell, use `export BABYLON_NO_CMAKE_POSTINSTALL=1` and `unset BABYLON_NO_CMAKE_POSTINSTALL` instead of the PowerShell environment commands. -``` -cd Package +Download and assemble the Babylon Native source tree, copy the package files, compile TypeScript, and validate the assembled contents: + +```powershell +cd ..\..\..\Package npx gulp buildAssembled +cd Assembled +npm pack ``` -Package content is in `Package/Assembled` folder. -Run `npm pack` to make a .tgz. - -## Supported Versions +Package content and the resulting `.tgz` are in `Package\Assembled`. The module's source `package.json` uses a development placeholder version; the [publish workflow](.github/workflows/publish.yml) sets the package version from the release tag before publishing. -Package versions are listed on this npm.js page: [@babylonjs/react-native](https://www.npmjs.com/package/@babylonjs/react-native). Check supported Babylon.js version and corresponding BabylonNative dependency in package [README](Modules/@babylonjs/react-native/README.md) +The npm README is copied from `Modules\@babylonjs\react-native\README.md` by `copyCommonFiles` in `Package\gulpfile.js`. Update that file for package usage changes; npm receives the updated README when a new package version is published. ## Security