feat: add reanimated hook useSyncSharedValue & useDerivedValue (#306)

Added a reanimated example as well:



https://github.com/user-attachments/assets/4537a5f9-3e82-4635-9edd-089d1ed1102c

Main logic for this is to:

```tsx
import { useSharedValue, withSequence, withSpring, withTiming } from 'react-native-reanimated'
import {  useSyncSharedValue, useDerivedValue } from 'react-native-filament'

  // Create a reanimated shared value to drive the animation
  const animatedRotationY = useSharedValue(0) 

  // RNF works with rn-worklets-core (RNWC), so create a 
  // RNWC shared value thats synced with the reanimated shared value
  const rotationY = useSyncSharedValue(animatedRotationY)

  // This uses useDerivedValue from rn-filament to create a RNWC derived value (RNWC has no API for that yet)
  const rotation = useDerivedValue<Float3>(() => {
    'worklet'
    return [0, rotationY.value, 0]
  })

  // Run a animation:
  const spin = useCallback(() => {
    animatedRotationY.value = withSequence(withSpring(Math.PI * 2), withTiming(0, { duration: 0 }))
  }, [animatedRotationY])
```

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: hannojg

docs/docs/guides/GETTING_STARTED.mdx

@@ -5,8 +5,8 @@ sidebar_label: Getting Started
 slug: /guides
 ---
 
-import Tabs from '@theme/Tabs'
-import TabItem from '@theme/TabItem'
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 ## Installing the library
 
@@ -45,7 +45,7 @@ For react-native-worklets-core its necessary to add a plugin to your `babel.conf
   </TabItem>
 
   <TabItem value="w_rea">
-    You should already use the reaniamted babel pluginVersions, make sure to add the `processNestedWorklets` option to it:
+    You should already use the reanimated babel pluginVersions, make sure to add the `processNestedWorklets` option to it:
 
     ```js
     module.exports = {
@@ -60,16 +60,14 @@ For react-native-worklets-core its necessary to add a plugin to your `babel.conf
   </TabItem>
 </Tabs>
 
-
-
 3. Update your pods:
 
 ```sh
 cd ios && pod install
 ```
 
 4. Start Metro with clean cache:
-  
+
 ```sh
 npm start -- --reset-cache
 ```
@@ -83,9 +81,9 @@ The npm package of react-native-filament is quite huge, around ~400mb. That's be
 You'll likely import 3D related files when using react-native-filament. To make sure metro can resolve these files, you need to add the following to your `metro.config.js`:
 
 ```js
-const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
+const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");
 
-const defaultConfig = getDefaultConfig(__dirname)
+const defaultConfig = getDefaultConfig(__dirname);
 
 /**
  * Metro configuration
@@ -94,10 +92,10 @@ const defaultConfig = getDefaultConfig(__dirname)
  * @type {import('metro-config').MetroConfig}
  */
 const config = {
-    resolver: {
-        // This makes it possible to import .glb files in your code:
-        assetExts: [...(defaultConfig.resolver?.assetExts || []), 'glb']
-    }
+  resolver: {
+    // This makes it possible to import .glb files in your code:
+    assetExts: [...(defaultConfig.resolver?.assetExts || []), "glb"],
+  },
 };
 
 module.exports = mergeConfig(defaultConfig, config);
@@ -117,25 +115,28 @@ For seeing some 3D content on the screen in your app, you need the following thi
 - 📹 A camera through which the scene is observed and projected onto the view (the `<Camera>` component)
 
 ```jsx
-import { FilamentScene, FilamentView, DefaultLight, Model, Camera } from "react-native-filament";
+import {
+  FilamentScene,
+  FilamentView,
+  DefaultLight,
+  Model,
+  Camera,
+} from "react-native-filament";
 import MyModel from "./MyModel.glb";
 
 function MyScene() {
   return (
     <FilamentScene>
-
       {/* 🏞️ A view to draw the 3D content to */}
       <FilamentView style={{ flex: 1 }}>
+        {/* 💡 A light source, otherwise the scene will be black */}
+        <DefaultLight />
 
-          {/* 💡 A light source, otherwise the scene will be black */}
-          <DefaultLight />
-
-          {/* 📦 A 3D model */}
-          <Model source={MyModel} />
-
-          {/* 📹 A camera through which the scene is observed and projected onto the view */}
-          <Camera />
+        {/* 📦 A 3D model */}
+        <Model source={MyModel} />
 
+        {/* 📹 A camera through which the scene is observed and projected onto the view */}
+        <Camera />
       </FilamentView>
     </FilamentScene>
   );

docs/docs/guides/REANIMATED.mdx

@@ -0,0 +1,104 @@
+---
+id: reanimated
+title: Reanimated Integration
+sidebar_label: Reanimated Integration
+slug: /guides/reanimated
+---
+
+import useBaseUrl from "@docusaurus/useBaseUrl";
+
+:::warning
+Please make sure to follow the installation steps to configure your metro config to work with reanimated, worklets-core and react-native-filament:
+
+- [Installation Guide](./GETTING_STARTED.mdx)
+
+:::
+
+<a
+  href="https://github.com/margelo/react-native-filament/blob/main/package/example/Shared/src/ReanimatedRotation.tsx"
+  target="_blank"
+  rel="noopener noreferrer"
+>
+  <div class="image-container">
+    <svg xmlns="http://www.w3.org/2000/svg" width="283" height="535">
+      <image
+        href={useBaseUrl("img/demo-reanimated.gif")}
+        x="18"
+        y="33"
+        width="247"
+        height="469"
+      />
+      <image href={useBaseUrl("img/frame.png")} width="283" height="535" />
+    </svg>
+  </div>
+</a>
+
+## react-native-worklets-core VS reanimated
+
+react-native-filament is build with [`react-native-worklets-core`](https://npmjs.com/package/react-native-worklets-core) which is a library that provides shared values and worklets for React Native.
+It's API is very similar to reanimated's, but it is not reanimated!
+
+In general, you pass shared values **from `react-native-worklets-core`** to the `react-native-filament` components to animate things like the position, rotation, scale, etc.
+
+However, many times you want to create animations using reanimated's API like `withTiming`, `withSpring`, etc. and then pass the resulting shared values to the `react-native-filament` components.
+
+## Using reanimated with react-native-filament
+
+To use reanimated animations / shared values with react-native-filament, **you need to sync the shared values from reanimated to a shared value from `react-native-worklets-core`**.
+You can do that using the [`useSyncSharedValue`](../api/functions/useSyncSharedValue) hook:
+
+```jsx
+import { useSyncSharedValue } from "react-native-filament";
+import { useSharedValue, withTiming } from "react-native-reanimated";
+
+// Create a reanimated shared value to drive the animation
+const opacity = useSharedValue(0);
+
+// Sync the reanimated shared value to a worklets-core shared value
+const workletsCoreOpacity = useSyncSharedValue(opacity);
+
+// Drive the animation using reanimated
+opacity.value = withTiming(1, { duration: 1000 });
+
+// The worklets-core shared value will have the same value as the
+// reanimated shared value and can be used in react-native-filament components
+```
+
+### Using derived values
+
+Sometimes you want to create a derived value from a reanimated shared value and use it in react-native-filament components. react-native-filament provides the [`useDerivedValue`](../api/functions/useDerivedValue) hook for that.
+It works like the `useDerivedValue` hook from reanimated, but just for worklets-core shared values:
+
+```jsx
+import {
+  useSharedValue,
+  withSequence,
+  withSpring,
+  withTiming,
+} from "react-native-reanimated";
+import { useSyncSharedValue, useDerivedValue } from "react-native-filament";
+
+// Create a reanimated shared value to drive the animation
+const animatedRotationY = useSharedValue(0);
+
+// RNF works with rn-worklets-core (RNWC), so create a
+// RNWC shared value thats synced with the reanimated shared value
+const rotationY = useSyncSharedValue(animatedRotationY);
+
+// This uses useDerivedValue from rn-filament to create a RNWC derived value (RNWC has no API for that yet)
+const rotation =
+  useDerivedValue <
+  Float3 >
+  (() => {
+    "worklet";
+    return [0, rotationY.value, 0];
+  });
+
+// Run a animation:
+const spin = useCallback(() => {
+  animatedRotationY.value = withSequence(
+    withSpring(Math.PI * 2),
+    withTiming(0, { duration: 0 })
+  );
+}, [animatedRotationY]);
+```

docs/sidebars.ts

@@ -12,7 +12,8 @@ const sidebars: SidebarsConfig = {
       "guides/animator",
       "guides/images",
       "guides/physics",
-      "guides/instancing"
+      "guides/instancing",
+      "guides/reanimated"
     ],
     API: [
       "api/index",

docs/static/img/demo-reanimated.gif

@@ -20,6 +20,7 @@ import { ScaleEffect } from './ScaleEffect'
 import { ChangeMaterials } from './ChangeMaterials'
 import { SkyboxExample } from './SkyboxExample'
 import { MorphTargets } from './MorphTargets'
+import { ReanimatedRotation } from './ReanimatedRotation'
 
 function NavigationItem(props: { name: string; route: string }) {
   const navigation = useNavigation()
@@ -59,6 +60,7 @@ function HomeScreen() {
       <NavigationItem name="🤖 Multiple Instances" route="MultipleInstances" />
       <NavigationItem name="🔄 Animated Rotate" route="AnimatedRotate" />
       <NavigationItem name="🔄 Animated Rotate w/ Shared Values" route="AnimatedRotateSharedValues" />
+      <NavigationItem name="🐎 Reanimated Rotate" route="ReanimatedRotation" />
       <NavigationItem name="💰 Physics Coin" route="PhysicsCoin" />
       <NavigationItem name="😶‍🌫️ Fade Out" route="FadeOut" />
       <NavigationItem name="🌑 Cast Shadow" route="CastShadow" />
@@ -101,6 +103,7 @@ function App() {
           <Stack.Screen name="MultipleInstances" component={MultipleInstances} />
           <Stack.Screen name="AnimatedRotate" component={AnimatedRotate} />
           <Stack.Screen name="AnimatedRotateSharedValues" component={AnimatedRotateSharedValues} />
+          <Stack.Screen name="ReanimatedRotation" component={ReanimatedRotation} />
           <Stack.Screen name="PhysicsCoin" component={PhysicsCoin} />
           <Stack.Screen name="FadeOut" component={FadeOut} />
           <Stack.Screen name="CastShadow" component={CastShadow} />

package/example/Shared/src/App.tsx

@@ -0,0 +1,63 @@
+import * as React from 'react'
+import { Button, StyleSheet } from 'react-native'
+import {
+  FilamentScene,
+  FilamentView,
+  Camera,
+  Skybox,
+  DefaultLight,
+  Model,
+  ModelInstance,
+  Float3,
+  useSyncSharedValue,
+  useDerivedValue,
+} from 'react-native-filament'
+import DroneGlb from '~/assets/buster_drone.glb'
+import { useCallback } from 'react'
+import { useSharedValue, withSequence, withSpring, withTiming } from 'react-native-reanimated'
+
+function Renderer() {
+  const animatedRotationY = useSharedValue(0)
+  const rotationY = useSyncSharedValue(animatedRotationY)
+  const rotation = useDerivedValue<Float3>(() => {
+    'worklet'
+    return [0, rotationY.value, 0]
+  })
+
+  const spin = useCallback(() => {
+    animatedRotationY.value = withSequence(withSpring(Math.PI * 2), withTiming(0, { duration: 0 }))
+  }, [animatedRotationY])
+
+  return (
+    <>
+      <Button title="Spin" onPress={spin} />
+      <FilamentView style={styles.filamentView} enableTransparentRendering={false}>
+        <Camera />
+        <DefaultLight />
+        <Skybox colorInHex="#88defb" />
+
+        <Model source={DroneGlb} transformToUnitCube scale={[3, 3, 3]}>
+          {/* Note: we apply the rotation individually as the above transformations are multiplying, while the one for the rotation, shouldn't */}
+          <ModelInstance index={0} rotate={rotation} multiplyWithCurrentTransform={false} />
+        </Model>
+      </FilamentView>
+    </>
+  )
+}
+
+export function ReanimatedRotation() {
+  return (
+    <FilamentScene>
+      <Renderer />
+    </FilamentScene>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  filamentView: {
+    flex: 1,
+  },
+})

package/example/Shared/src/ReanimatedRotation.tsx

@@ -0,0 +1,39 @@
+// Copied from https://github.com/mrousavy/react-native-vision-camera/blob/main/package/src/dependencies/ModuleProxy.ts
+
+type ImportType = ReturnType<typeof require>
+
+/**
+ * Create a lazily-imported module proxy.
+ * This is useful for lazily requiring optional dependencies.
+ */
+export const createModuleProxy = <TModule>(getModule: () => ImportType): TModule => {
+  const holder: { module: TModule | undefined } = { module: undefined }
+
+  const proxy = new Proxy(holder, {
+    get: (target, property) => {
+      if (property === '$$typeof') {
+        // If inlineRequires is enabled, Metro will look up all imports
+        // with the $$typeof operator. In this case, this will throw the
+        // `OptionalDependencyNotInstalledError` error because we try to access the module
+        // even though we are not using it (Metro does it), so instead we return undefined
+        // to bail out of inlineRequires here.
+        // See https://github.com/mrousavy/react-native-vision-camera/pull/2953
+        return undefined
+      }
+
+      if (target.module == null) {
+        // lazy initialize module via require()
+        // caller needs to make sure the require() call is wrapped in a try/catch
+        target.module = getModule() as TModule
+      }
+      return target.module[property as keyof typeof holder.module]
+    },
+  })
+  return proxy as unknown as TModule
+}
+
+export class OptionalDependencyNotInstalledError extends Error {
+  constructor(name: string) {
+    super(`${name} is not installed!`)
+  }
+}

package/src/dependencies/ModuleProxy.ts

@@ -0,0 +1,21 @@
+// Copied from https://github.com/mrousavy/react-native-vision-camera/blob/main/package/src/dependencies/ReanimatedProxy.ts
+
+import type * as Reanimated from 'react-native-reanimated'
+import { createModuleProxy, OptionalDependencyNotInstalledError } from './ModuleProxy'
+
+type TReanimated = typeof Reanimated
+
+/**
+ * A proxy object that lazy-imports react-native-reanimated as soon as the
+ * caller tries to access a property on {@linkcode ReanimatedProxy}.
+ *
+ * If react-native-reanimated is not installed, accessing anything on
+ * {@linkcode ReanimatedProxy} will throw.
+ */
+export const ReanimatedProxy = createModuleProxy<TReanimated>(() => {
+  try {
+    return require('react-native-reanimated')
+  } catch (e) {
+    throw new OptionalDependencyNotInstalledError('react-native-reanimated')
+  }
+})