Lazy Physics (#86)

* Add physics context and integrate into Application and RigidBody components

- Introduced PhysicsProvider to manage physics state and loading.
- Updated ApplicationWithoutCanvas to wrap children with PhysicsProvider.
- Enhanced RigidBody component to check for physics context and handle errors.
- Removed direct dependency on global Ammo instance in favor of context management.

* Update package dependencies and improve error handling in RigidBody component

- Added sync-ammo as a peer dependency in package.json and package-lock.json.
- Updated error message in RigidBody component to guide users on installing sync-ammo if not already done.
- Cleaned up package.json by removing unnecessary dependencies section.

* Enhance physics components and error handling

- Removed outdated comment from physics documentation.
- Updated PhysicsProvider to accept an app prop and manage physics instance count for cleanup.
- Improved error handling in Collision and RigidBody components to use warnOnce utility for better user guidance.
- Modified useComponent hook to handle null component types gracefully.
- Introduced warnOnce utility for logging warnings without repetition.

* Add callout for enabling physics in Collision and RigidBody documentation

- Introduced an info callout in both Collision and RigidBody documentation to guide users on installing `sync-ammo` and enabling physics in the Application.
- Removed outdated note in RigidBody documentation for clarity.

* Update packages/lib/src/contexts/physics-context.tsx

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

* Update PhysicsProvider to include app dependency in effect hook

- Modified the useEffect hook in PhysicsProvider to include the app dependency for improved state management.

* Add info callout for enabling physics in RigidBody documentation

- Included a callout in the RigidBody documentation to inform users about installing `sync-ammo` and enabling physics in the Application.
- This enhances user guidance and improves clarity in the documentation.

---------

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

Author: marklundin

package-lock.json

@@ -1,5 +1,11 @@
 # Collision
 
+import { Callout } from 'nextra/components'
+ 
+<Callout type="info" emoji="️💡">
+  Enable physics by installing `npm i sync-ammo` and enabling physics on the Application using`<Application usePhysics/>`.
+</Callout>
+
 The `Collision` component attaches a PlayCanvas [Collision Component](https://api.playcanvas.com/classes/Engine.CollisionComponent.html) to an [`Entity`](/api/entity).
 
 It allows an [`Entity`](/api/entity) to participate in collision detection with other entities that have collision components. This is useful for physics simulations, trigger zones, and other gameplay mechanics that require detecting when objects intersect.

packages/docs/src/app/docs/api/components/collision/page.mdx

@@ -1,13 +1,15 @@
 # Rigidbody
 
+import { Callout } from 'nextra/components'
+
+<Callout type="info" emoji="️💡">
+  Enable physics by installing `npm i sync-ammo` and enabling physics on the Application using`<Application usePhysics/>`.
+</Callout>
+
 The `Rigidbody` component enables physics for an [`Entity`](/api/entity), allowing it to interact with the global physics simulation. You can apply forces, torques, and other physics behaviours to an entity with a `Rigidbody` component and it will respond accordingly.
 
 You can learn more about how physics work in PlayCanvas in the [Physics docs](https://developer.playcanvas.com/user-manual/physics/).
 
-> [!NOTE]
->
-> To use physics you must enable it on the Application using`<Application usePhysics/>`. See the [Application docs](/api/application) for more information.
-
 ## Usage
 
 ```jsx

packages/docs/src/app/docs/api/components/rigidbody/page.mdx

@@ -12,8 +12,6 @@ export const ShapeCollider = ({ children, scale = 1, material, type = 'sphere',
 
 export const Physics = () => {
 
-    // This is a simple physics example and close port of this awesome r3f example - https://codesandbox.io/p/sandbox/bestservedbold-christmas-baubles-forked-wqyzx5 
-
     const app = useApp();
     const matA = useMaterial({ diffuse: "#c0a0a0", emissive: "red" });
     const matB = useMaterial({ });

packages/docs/src/content/physics.mdx

@@ -79,16 +79,19 @@
     "peerDependencies": {
         "playcanvas": "^2.3.3",
         "react": "^18.3.1",
-        "react-dom": "^18.3.1"
+        "react-dom": "^18.3.1",
+        "sync-ammo": "^0.1.2"
+    },
+    "peerDependenciesMeta": {
+        "sync-ammo":{
+            "optional": true
+        }
     },
     "publishConfig": {
         "access": "public"
     },
     "devDependencies": {
         "pkg-pr-new": "^0.0.41",
         "typescript": "5.8.2"
-    },
-    "dependencies": {
-        "sync-ammo": "^0.1.2"
     }
 }

packages/lib/package.json

@@ -1,5 +1,4 @@
 import React, { FC, PropsWithChildren, useLayoutEffect, useMemo, useRef, useState } from 'react';
-import * as Ammo from 'sync-ammo';
 import {
   FILLMODE_NONE,
   FILLMODE_FILL_WINDOW,
@@ -14,6 +13,7 @@ import {
 import { AppContext, ParentContext } from './hooks';
 import { PointerEventsContext } from './contexts/pointer-events-context';
 import { usePicker } from './utils/picker';
+import { PhysicsProvider } from './contexts/physics-context';
 
 interface GraphicsOptions {
   /** Boolean that indicates if the canvas contains an alpha buffer. */
@@ -102,7 +102,6 @@ export const ApplicationWithoutCanvas: FC<ApplicationWithoutCanvasProps> = ({
   usePhysics = false,
   ...otherProps
 }) => {
-
   const graphicsDeviceOptions = {
     alpha: true,
     depth: true,
@@ -126,10 +125,6 @@ export const ApplicationWithoutCanvas: FC<ApplicationWithoutCanvasProps> = ({
   useLayoutEffect(() => {
     const canvas = canvasRef.current;
     if (canvas && !appRef.current) {
-
-      // @ts-expect-error The PC Physics system expects a global Ammo instance
-      if (usePhysics) globalThis.Ammo = Ammo.default
-
       const localApp = new PlayCanvasApplication(canvas, {
         mouse: new Mouse(canvas),
         touch: new TouchDevice(canvas),
@@ -146,13 +141,8 @@ export const ApplicationWithoutCanvas: FC<ApplicationWithoutCanvasProps> = ({
 
     return () => {
       if (!appRef.current) return;
-      
       appRef.current.destroy();
       appRef.current = null;
-
-      // @ts-expect-error Clean up the global Ammo instance
-      if (usePhysics && globalThis.Ammo) delete globalThis.Ammo;
-
       setApp(null);
     };
   }, [canvasRef, fillMode, resolutionMode, ...Object.values(graphicsDeviceOptions)]);
@@ -167,12 +157,14 @@ export const ApplicationWithoutCanvas: FC<ApplicationWithoutCanvasProps> = ({
   if (!app) return null;
 
   return (
-    <AppContext.Provider value={appRef.current}>
-      <PointerEventsContext.Provider value={pointerEvents}>
-        <ParentContext.Provider value={appRef.current?.root as PcEntity}>
-          {children}
-        </ParentContext.Provider>
-      </PointerEventsContext.Provider>
-    </AppContext.Provider>
+    <PhysicsProvider enabled={usePhysics} app={app}>
+      <AppContext.Provider value={appRef.current}>
+        <PointerEventsContext.Provider value={pointerEvents}>
+          <ParentContext.Provider value={appRef.current?.root as PcEntity}>
+            {children}
+          </ParentContext.Provider>
+        </PointerEventsContext.Provider>
+      </AppContext.Provider>
+    </PhysicsProvider>
   );
 };

packages/lib/src/Application.tsx

@@ -1,15 +1,42 @@
 "use client"
 
-import { FC } from "react";
-import { useComponent } from "../hooks";
+import { FC, useEffect } from "react";
+import { useComponent, useParent } from "../hooks";
+import { usePhysics } from "../contexts/physics-context";
+import { warnOnce } from "../utils/warn-once";
 
 type CollisionProps = {
     [key: string]: unknown;
+    type?: string;
 }
 
 export const Collision: FC<CollisionProps> = (props) => {
+    const entity = useParent();
+    const { isPhysicsEnabled, isPhysicsLoaded, physicsError } = usePhysics();
 
-    useComponent("collision", props);
-    return null
-    
+    useEffect(() => {
+        if (!isPhysicsEnabled) {
+            warnOnce(
+                'The `<Collision>` component requires `usePhysics` to be set on the Application. ' +
+                'Please add `<Application usePhysics/>` to your root component.',
+                false // Show in both dev and prod
+            );
+        }
+
+        if (physicsError) {
+            warnOnce(
+                `Failed to initialize physics: ${physicsError.message}. ` +
+                "Run `npm install sync-ammo` in your project, if you haven't done so already.",
+                false // Show in both dev and prod
+            );
+        }
+    }, [isPhysicsEnabled, physicsError]);
+
+    // If no type is defined, infer if possible from a render component
+    const type = entity.render && props.type === undefined ? entity.render.type : props.type;
+
+    // Always call useComponent - it will handle component lifecycle internally
+    useComponent(isPhysicsLoaded ? "collision" : null, { ...props, type });
+
+    return null;
 }

packages/lib/src/components/Collision.tsx

@@ -1,24 +1,45 @@
-import { FC } from "react";
+import { FC, useEffect } from "react";
 import { useComponent, useParent } from "../hooks";
+import { usePhysics } from "../contexts/physics-context";
+import { warnOnce } from "../utils/warn-once";
 
 type RigidBodyProps = {
     [key: string]: unknown;
     type?: string;
 }
 
 export const RigidBody: FC<RigidBodyProps> = (props) => {
-
     const entity = useParent();
+    const { isPhysicsEnabled, isPhysicsLoaded, physicsError } = usePhysics();
+
+    useEffect(() => {
+        if (!isPhysicsEnabled) {
+            warnOnce(
+                'The `<RigidBody>` component requires `usePhysics` to be set on the Application. ' +
+                'Please add `<Application usePhysics/>` to your root component.',
+                false // Show in both dev and prod
+            );
+        }
+
+        if (physicsError) {
+            warnOnce(
+                `Failed to initialize physics: ${physicsError.message}. ` +
+                "Run `npm install sync-ammo` in your project, if you haven't done so already.",
+                false // Show in both dev and prod
+            );
+        }
+    }, [isPhysicsEnabled, physicsError]);
 
     // @ts-expect-error Ammo is defined in the global scope in the browser
-    if(!globalThis.Ammo && process.env.NODE_ENV !== 'production' ) {
+    if(isPhysicsLoaded && !globalThis.Ammo ) {
         throw new Error('The `<RigidBody>` component requires `usePhysics` to be set on the Application. `<Application usePhysics/>` ')
     }
 
     // If no type is defined, infer if possible from a render component
     const type = entity.render && props.type === undefined ? entity.render.type : props.type;
 
-    useComponent("rigidbody", { ...props, type } );
-    return null
-    
+    // Always call useComponent - it will handle component lifecycle internally
+    useComponent(isPhysicsLoaded ? "rigidbody" : null, { ...props, type });
+
+    return null;
 }

packages/lib/src/components/RigidBody.tsx

@@ -0,0 +1,88 @@
+import React, { createContext, useContext, useEffect, useState } from 'react';
+import { AppBase } from 'playcanvas';
+
+interface PhysicsContextType {
+  isPhysicsEnabled: boolean;
+  isPhysicsLoaded: boolean;
+  physicsError: Error | null;
+}
+
+const PhysicsContext = createContext<PhysicsContextType>({
+  isPhysicsEnabled: false,
+  isPhysicsLoaded: false,
+  physicsError: null,
+});
+
+// Track how many Application instances are using physics
+let physicsInstanceCount = 0;
+
+export const usePhysics = () => useContext(PhysicsContext);
+
+interface PhysicsProviderProps {
+  children: React.ReactNode;
+  enabled: boolean;
+  app: AppBase;
+}
+
+export const PhysicsProvider: React.FC<PhysicsProviderProps> = ({ children, enabled, app }) => {
+  const [isPhysicsLoaded, setIsPhysicsLoaded] = useState(false);
+  const [physicsError, setPhysicsError] = useState<Error | null>(null);
+  
+  useEffect(() => {
+    if (!enabled) {
+      setIsPhysicsLoaded(false);
+      setPhysicsError(null);
+      return;
+    }
+
+    const loadPhysics = async () => {
+      try {
+        // @ts-expect-error The PC Physics system expects a global Ammo instance
+        if (!globalThis.Ammo) {
+          const Ammo = await import('sync-ammo');
+          // @ts-expect-error The PC Physics system expects a global Ammo instance
+          globalThis.Ammo = Ammo.default;
+        }
+        
+        // Only initialize the library if not already done so
+        if(!app.systems.rigidbody?.dispatcher) {
+          app.systems.rigidbody?.onLibraryLoaded();
+        }
+
+        setIsPhysicsLoaded(true);
+        setPhysicsError(null);
+        physicsInstanceCount++;
+
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error('Failed to load physics library');
+        setPhysicsError(err);
+        setIsPhysicsLoaded(false);
+      }
+    };
+
+    loadPhysics();
+
+    return () => {
+      // Only clean up Ammo if this is the last instance using physics
+      if (enabled) {
+        physicsInstanceCount--;
+        if (physicsInstanceCount === 0) {
+          // @ts-expect-error Clean up the global Ammo instance
+          if (globalThis.Ammo) delete globalThis.Ammo;
+        }
+      }
+    };
+  }, [enabled, app]);
+
+  return (
+    <PhysicsContext.Provider
+      value={{
+        isPhysicsEnabled: enabled,
+        isPhysicsLoaded,
+        physicsError,
+      }}
+    >
+      {children}
+    </PhysicsContext.Provider>
+  );
+}; 

packages/lib/src/contexts/physics-context.tsx

@@ -7,12 +7,16 @@ type ComponentProps = {
   [key: string]: unknown;
 }
 
-export const useComponent = (ctype: string, props: ComponentProps): void => {
+export const useComponent = (ctype: string | null, props: ComponentProps): void => {
   const componentRef = useRef<Component | null>();
   const parent : Entity = useParent();
   const app : Application = useApp();
 
   useLayoutEffect(() => {
+    if(!ctype) {
+      return;
+    }
+
     if (parent) {
       // Only add the component if it hasn't been added yet
       if (!componentRef.current) {
@@ -38,6 +42,10 @@ export const useComponent = (ctype: string, props: ComponentProps): void => {
   // Update component props
   useLayoutEffect(() => {
 
+    if(!ctype) {
+      return
+    }
+
     const comp: Component | null | undefined = componentRef.current
     // Ensure componentRef.current exists before updating props
     if (!comp) return;
@@ -48,5 +56,5 @@ export const useComponent = (ctype: string, props: ComponentProps): void => {
 
     Object.assign(comp, filteredProps)
 
-  }, [props]);
+  }, [props, ctype]);
 };