Introduce useAppEvent hook and deprecate useFrame (#186)

* feat: introduce useAppEvent hook and deprecate useFrame

- Added a new `useAppEvent` hook for subscribing to PlayCanvas application events with flexible parameter signatures.
- Deprecated the `useFrame` hook, recommending the use of `useAppEvent('update', callback)` instead.
- Updated exports to reflect the changes and removed the old `useFrame` implementation.

* fix: add warning for deprecated useFrame hook

- Introduced a warning message in the `useFrame` function to inform users that it is deprecated and will be removed in a future release. Users are encouraged to use `useAppEvent('update', callback)` instead.

* feat: implement useAppEvent hook and deprecate useFrame

- Added the `useAppEvent` hook for subscribing to PlayCanvas application events, including 'update', 'prerender', and 'postrender'.
- Updated documentation to reflect the deprecation of the `useFrame` hook, providing migration guidance for users.
- Introduced tests for the `useAppEvent` hook to ensure proper registration and error handling.
- Removed the `useFrame` hook and its associated tests.

* refactor: enhance useAppEvent hook with improved type safety

- Simplified the event callback types by introducing a mapped type for event signatures.
- Updated the handler logic to differentiate between event types more clearly.
- Ensured proper cleanup of event listeners in the useEffect hook.
- Maintained deprecation warning for the useFrame hook, guiding users to use useAppEvent instead.

* fix: update import statement to include useAppEvent hook in the MDC rules

- Modified the import statement in the PlayCanvas React module to include the newly introduced `useAppEvent` hook, ensuring proper functionality and alignment with recent changes.

* refactor: replace useFrame with useAppEvent for rendering on camera change

- Updated the rendering logic in the `useRenderOnCameraChange` hook to utilize the `useAppEvent` hook instead of the deprecated `useFrame` hook, ensuring better alignment with the latest event handling practices in PlayCanvas.

* Update .changeset/vast-roses-wait.md

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: marklundin

.changeset/sour-mangos-train.md

@@ -0,0 +1,5 @@
+---
+"@playcanvas/blocks": patch
+---
+
+Updated internal api to use `useAppEvent`

.changeset/vast-roses-wait.md

@@ -0,0 +1,5 @@
+---
+"@playcanvas/react": minor
+---
+
+Deprecate useFrame and introduce useAppEvent API

packages/blocks/src/splat-viewer/hooks/use-render-on-camera-change.tsx

@@ -1,4 +1,4 @@
-import { useApp, useFrame } from "@playcanvas/react/hooks";
+import { useApp, useAppEvent } from "@playcanvas/react/hooks";
 import { Entity as PcEntity } from "playcanvas";
 import { useEffect, useRef } from "react";
 
@@ -51,7 +51,7 @@ export const useRenderOnCameraChange = (entity: PcEntity | null) => {
    * However if the canvas is not visible on the page it will take precedence.
    * Don't render if the canvas is not visible regardless of any animations.
    */
-  useFrame(() => {
+  useAppEvent('update', () => {
     if (!entity || !isVisible.current) return;
     const world = entity.getWorldTransform().data;
     const proj = entity.camera?.projectionMatrix?.data;

packages/docs/content/docs/api/hooks/index.mdx

@@ -54,6 +54,8 @@ const ParentEntity = () => {
 
 ## useFrame
 
+> **Deprecated**: The `useFrame` hook is deprecated and will be removed in a future release. Please use `useAppEvent('update', callback)` instead.
+
 The `useFrame` hook ties into the event loop and will be called on every frame whilst the component is mounted. Use this when you need to update a value or perform a calculation on every frame. This is better for performance than using react state updates.
 
 ```jsx
@@ -68,4 +70,55 @@ const MyComponent = () => {
 
   return <Entity ref={entityRef} />;
 }
+```
+
+## useAppEvent
+
+The `useAppEvent` hook provides a generic way to subscribe to PlayCanvas application events with proper TypeScript support. It supports different event types with their specific callback signatures.
+
+### Supported Events
+
+- **`'update'`**: Called every frame with delta time `(dt: number) => void`
+- **`'prerender'`**: Called before rendering with no parameters `() => void`
+- **`'postrender'`**: Called after rendering with no parameters `() => void`
+
+```jsx
+import { useAppEvent } from '@playcanvas/react/hooks'
+
+const MyComponent = () => {
+  const entityRef = useRef(null);
+
+  // Frame update with delta time (replaces useFrame)
+  useAppEvent('update', (dt) => {
+    entityRef.current.rotate(0, dt, 0);
+  });
+
+  // Pre-render hook
+  useAppEvent('prerender', () => {
+    console.log('About to render frame');
+  });
+
+  // Post-render hook
+  useAppEvent('postrender', () => {
+    console.log('Finished rendering frame');
+  });
+
+  return <Entity ref={entityRef} />;
+}
+```
+
+### Migration from useFrame
+
+To migrate from the deprecated `useFrame` hook:
+
+```jsx
+// Old way (deprecated)
+useFrame((dt) => {
+  // your frame logic
+});
+
+// New way
+useAppEvent('update', (dt) => {
+  // your frame logic
+});
 ```

packages/lib/.playcanvas-react.mdc

@@ -20,7 +20,7 @@ import { Application, Entity } from '@playcanvas/react'
 // /components add behaviours to Entities
 import { Light, Camera, Render, Gsplat, Screen, Collision, RigigBody, Anim } from '@playcanvas/react/components'
 // Hooks add functionality
-import { useModel, useSplat, useFrame, useParent, useApp } from '@playcanvas/react/hooks'
+import { useModel, useSplat, useAppEvent, useParent, useApp } from '@playcanvas/react/hooks'
 ```
 
 ## Rules for 3D Content

packages/lib/src/hooks/index.ts

@@ -6,5 +6,5 @@ export { useApp, AppContext } from './use-app.tsx';
 export { useParent, ParentContext } from './use-parent.tsx';
 export { useMaterial } from './use-material.tsx'
 export { useAsset, useSplat, useTexture, useEnvAtlas, useModel, useFont } from './use-asset.ts';
-export { useFrame } from './use-frame.tsx';
+export { useFrame, useAppEvent } from './use-app-event.ts';
 export type { AssetResult } from './use-asset.ts';

packages/lib/src/hooks/use-app-event.test.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+import { useAppEvent } from './use-app-event.ts';
+import { Application } from '../Application.tsx';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+/**
+ * Note that we can't test the actual firing of the callbacks in tests,
+ * because these events are not fire in the Null device type.
+ * 
+ * It's possible that we can run headless once we have a node-wgpu environment.
+ */
+
+describe('useAppEvent', () => {
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should register and unregister callbacks without throwing', () => {
+    const updateCallback = vi.fn();
+    const prerenderCallback = vi.fn();
+    const postrenderCallback = vi.fn();
+
+    const { unmount } = renderHook(() => {
+      useAppEvent('update', updateCallback);
+      useAppEvent('prerender', prerenderCallback);
+      useAppEvent('postrender', postrenderCallback);
+    }, {
+      wrapper: ({ children }) => <Application deviceTypes={["null"]}>{children}</Application>
+    });
+
+    // Should not throw during registration
+    expect(updateCallback).toBeDefined();
+    expect(prerenderCallback).toBeDefined();
+    expect(postrenderCallback).toBeDefined();
+
+    // Should not throw during cleanup
+    unmount();
+  });
+
+  it('should throw error if app is not available', () => {
+    const mockCallback = vi.fn();
+    expect(() => {
+      renderHook(() => useAppEvent('update', mockCallback));
+    }).toThrow('`useApp` must be used within an Application component');
+  });
+
+}); 

packages/lib/src/hooks/use-app-event.ts

@@ -0,0 +1,92 @@
+import { useEffect, useCallback } from "react";
+import { useApp } from "./use-app.tsx";
+import { warnOnce } from "../utils/validation.ts"
+
+/**
+ * Generic hook for subscribing to PlayCanvas application events.
+ * Supports events with different parameter signatures using TypeScript conditional types.
+ * 
+ * @param {'update' | 'prerender' | 'postrender'} event - The event name to subscribe to
+ * @param callback - The callback function to execute when the event fires
+ * 
+ * @example
+ * ```tsx
+ * // Event with delta time - TypeScript will enforce (dt: number) => void
+ * useAppEvent('update', (dt) => console.log('Frame time:', dt));
+ * 
+ * // Events with no parameters - TypeScript will enforce () => void
+ * useAppEvent('prerender', () => console.log('Pre-render'));
+ * useAppEvent('postrender', () => console.log('Post-render'));
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   // Frame update with delta time
+ *   useAppEvent('update', (dt) => {
+ *     console.log('Frame delta time:', dt);
+ *   });
+ * 
+ *   // App lifecycle events
+ *   useAppEvent('prerender', () => {
+ *     console.log('Pre-rendering');
+ *   });
+ * 
+ *   return null;
+ * }
+ * ```
+ */
+type EventCallbackMap = {
+  /**
+   * @param dt - The delta time since the last frame
+   * @returns void
+   */
+  update: (dt: number) => void;
+  /**
+   * @returns void
+   */
+  prerender: () => void;
+  /**
+   * @returns void
+   */
+  postrender: () => void;
+};
+
+type AppEventName = keyof EventCallbackMap;
+
+export function useAppEvent<T extends AppEventName>(
+  event: T,
+  callback: EventCallbackMap[T]
+): void {
+  const app = useApp();
+
+  const handler = useCallback((dt?: number) => {
+    if (event === 'update') {
+      (callback as (dt: number) => void)(dt!);
+    } else {
+      (callback as () => void)();
+    }
+  }, [callback, event]);
+
+  useEffect(() => {
+    if (!app) {
+      throw new Error("`useAppEvent` must be used inside an `<Application />` component");
+    }
+
+    app.on(event, handler);
+    return () => {
+      app.off(event, handler);
+    };
+  }, [app, handler, event]);
+}
+
+/**
+ * useFrame hook — registers a callback on every frame update.
+ * The callback receives the delta time (dt) since the last frame.
+ * 
+ * @deprecated Use useAppEvent('update', callback) instead
+ */
+export const useFrame = (callback: (dt: number) => void) => {
+  warnOnce("`useFrame` is deprecated and will be removed in a future release. Please use useAppEvent('update', callback) instead.")
+  return useAppEvent('update', callback);
+};