Update

.github/workflows/validate-documentation.yml

@@ -25,7 +25,7 @@ jobs:
           registry-url: https://registry.npmjs.org
       # Cache Node Module Dependencies
       - name: Cache Node Module Dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: "documentation/node_modules"
           key: nodemodules-${{ runner.os }}-${{ hashFiles('documentation/package-lock.json') }}

.github/workflows/validate-module.yml

@@ -23,7 +23,7 @@ jobs:
           registry-url: https://registry.npmjs.org
       # Cache Node Module Dependencies
       - name: Cache Node Module Dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: "module/node_modules"
           key: nodemodules-${{ runner.os }}-${{ hashFiles('module/package-lock.json') }}

documentation/docs/api/event-system.md

@@ -24,12 +24,12 @@ function removeEventListener(
 ```tsx title="Type Definition"
 function dispatchReactUnityEvent(
   eventName: string,
-  ...parameters: ReactUnityEventParameterType[]
+  ...parameters: UnityEventParameter[]
 ): void;
 ```
 
 ```tsx title="Type Definition"
-type ReactUnityEventParameter = string | number | undefined;
+type UnityEventParameter = any | undefined | void;
 ```
 
 ## Implementation

documentation/docs/api/get-metrics-info.md

@@ -0,0 +1,71 @@
+# Getting Metrics Info
+
+The `getMetricsInfo` function is used to retrieve information about the Unity Application's metrics, such as memory usage and frame rate. This can be useful for debugging and performance analysis.
+
+:::tip
+Use the built-in [Unity Metrics Info hook](/docs/api/use-unity-metrics-info) for a more convenient way to access metrics information in your React components.
+:::
+
+## Type Definition
+
+```tsx title="Type Definition"
+function getMetricsInfo(): UnityMetricsInfo | undefined;
+```
+
+## Implementation
+
+:::info
+The getMetricsInfo function is only available in Unity Builds created with Unity 6000.1 or later.
+:::
+
+Web builds can get quite large, and it can be useful to know how much memory is being used by the Unity Application. The `getMetricsInfo` function provides a way to retrieve this information. It returns an object containing various metrics, such as memory usage, frame rate, and more.
+
+To get started, destructure the getMetricsInfo function from the Unity Context.
+
+```jsx showLineNumbers title="Example: Destructuring the unload function"
+const { getMetricsInfo } = useUnityContext();
+```
+
+Next you'll be able to invoke the `getMetricsInfo` function to retrieve the metrics information. The function returns an object of type `UnityMetricsInfo`, which contains various properties related to the Unity Application's performance.
+
+```jsx showLineNumbers title="Example: Using the get metrics info function"
+async function handleClick() {
+  const metricsInfo = getMetricsInfo();
+}
+
+return <button onClick={handleClick}>Check metrics</button>;
+```
+
+## Example Usage
+
+A basic implementation could look something like this. In the following example we'll display a button which allows us to check the current frames per second (FPS) of the Unity Application. When the button is clicked, it will log the FPS to the console.
+
+```jsx showLineNumbers title="App.jsx"
+import React, { Fragment } from "react";
+import { Unity, useUnityContext } from "react-unity-webgl";
+
+function App() {
+  const { unityProvider, getMetricsInfo } = useUnityContext({
+    loaderUrl: "build/myunityapp.loader.js",
+    dataUrl: "build/myunityapp.data",
+    frameworkUrl: "build/myunityapp.framework.js",
+    codeUrl: "build/myunityapp.wasm",
+  });
+
+  function handleClickCheckFps() {
+    const metricsInfo = getMetricsInfo();
+    if (metricsInfo) {
+      console.log("FPS:", metricsInfo.fps);
+    } else {
+      console.warn("Metrics info is not available.");
+    }
+  }
+
+  return (
+    <Fragment>
+      <Unity unityProvider={unityProvider} />
+      <button onClick={handleClickCheckFps}>Check FPS</button>
+    </Fragment>
+  );
+}
+```

documentation/docs/api/print-err.md

@@ -0,0 +1,49 @@
+# Print Errors
+
+The Print Errors API lets you intercept all error output coming out of the Unity Module — runtime errors, JavaScript errors thrown from `jslib` files, and `Debug.LogError` calls from your C# code — before they reach the browser console.
+
+## Type Definition
+
+```tsx title="Type Definition"
+function printErr(message: string): void;
+```
+
+## Implementation
+
+By default, Unity routes its error output through `console.error`. When a `printErr` handler is provided to the Unity Config, Unity will call your handler instead of writing to the console directly. This is the counterpart to [Print](./print.md) and is the recommended channel for forwarding Unity errors into custom logging, error reporting (e.g. Sentry), or an in-app diagnostics panel.
+
+Both runtime problems thrown by the engine and `jslib`/JavaScript errors flow through this handler.
+
+:::info
+The handler is captured once during initialisation and passed to `createUnityInstance`. Changing the function reference after the Unity Instance has booted will not have any effect, so prefer a stable reference (for example via `useCallback` or a module-scope function).
+:::
+
+:::caution
+The handler replaces the default console output. If you still want messages in the browser console, call `console.error` from inside your handler.
+:::
+
+## Example Usage
+
+A basic implementation could look something like this. In the following example we'll forward every Unity error to both the console and an error reporting service.
+
+```jsx {5-8,15} showLineNumbers title="App.jsx"
+import React from "react";
+import { Unity, useUnityContext } from "react-unity-webgl";
+
+function App() {
+  function handlePrintErr(message) {
+    console.error("[Unity]", message);
+    errorReporter.captureMessage(message, { level: "error" });
+  }
+
+  const { unityProvider } = useUnityContext({
+    loaderUrl: "build/myunityapp.loader.js",
+    dataUrl: "build/myunityapp.data",
+    frameworkUrl: "build/myunityapp.framework.js",
+    codeUrl: "build/myunityapp.wasm",
+    printErr: handlePrintErr,
+  });
+
+  return <Unity unityProvider={unityProvider} />;
+}
+```

documentation/docs/api/print.md

@@ -0,0 +1,49 @@
+# Print
+
+The Print API lets you intercept all standard log output coming out of the Unity Module — both internal information messages from the loader and runtime, and `Debug.Log` calls from your C# code — before they reach the browser console.
+
+## Type Definition
+
+```tsx title="Type Definition"
+function print(message: string): void;
+```
+
+## Implementation
+
+By default, Unity routes its standard output through `console.log`. When a `print` handler is provided to the Unity Config, Unity will call your handler instead of writing to the console directly. This is useful for forwarding Unity logs into a custom logger, dev tools panel, telemetry sink, or in-app debug overlay.
+
+Both internal Unity messages (loader progress, framework diagnostics) and your own `Debug.Log` calls flow through this handler.
+
+:::info
+The handler is captured once during initialisation and passed to `createUnityInstance`. Changing the function reference after the Unity Instance has booted will not have any effect, so prefer a stable reference (for example via `useCallback` or a module-scope function).
+:::
+
+:::caution
+The handler replaces the default console output. If you still want messages in the browser console, call `console.log` from inside your handler.
+:::
+
+## Example Usage
+
+A basic implementation could look something like this. In the following example we'll forward every Unity log message to both the console and a telemetry function.
+
+```jsx {5-8,15} showLineNumbers title="App.jsx"
+import React from "react";
+import { Unity, useUnityContext } from "react-unity-webgl";
+
+function App() {
+  function handlePrint(message) {
+    console.log("[Unity]", message);
+    telemetry.capture({ severity: "info", message });
+  }
+
+  const { unityProvider } = useUnityContext({
+    loaderUrl: "build/myunityapp.loader.js",
+    dataUrl: "build/myunityapp.data",
+    frameworkUrl: "build/myunityapp.framework.js",
+    codeUrl: "build/myunityapp.wasm",
+    print: handlePrint,
+  });
+
+  return <Unity unityProvider={unityProvider} />;
+}
+```

documentation/docs/api/send-message.md

@@ -11,12 +11,12 @@ The send message function lets you asynchronously invoke a method in the Unity g
 function sendMessage(
   gameObjectName: string,
   methodName: string,
-  parameter?: ReactUnityEventParameterType
+  parameter?: UnityMessageParameter
 ): void;
 ```
 
 ```tsx title="Type Definition"
-type ReactUnityEventParameter = string | number | undefined;
+type UnityMessageParameter = string | number | undefined | void;
 ```
 
 ## Implementation
@@ -32,7 +32,7 @@ When invoking a C-Sharp method by sending a message, the name of the mono behavi
 :::
 
 :::warning
-Make sure the parameter matches the actual existence and type of the C-Sharp method you're trying to invoke. Not 
+Make sure the parameter matches the actual existence and type of the C-Sharp method you're trying to invoke. Not
 doing so may cause unintended behaviour or even a crash of the Unity Application.
 :::
 

documentation/docs/api/show-banner.md

@@ -0,0 +1,72 @@
+# Show Banner
+
+The Show Banner API allows you to intercept non-critical warnings and error messages from the Unity Instance and route them into your own UI instead of relying on Unity's default in-DOM banner.
+
+## Type Definition
+
+```tsx title="Type Definition"
+function showBanner(message: string, type?: UnityBannerType): void;
+```
+
+```tsx title="Type Definition"
+type UnityBannerType = "error" | "warning";
+```
+
+## Implementation
+
+When the Unity Instance encounters a non-critical issue it would normally display a banner directly in the DOM, above the canvas. By providing a `showBanner` handler to the Unity Config you take ownership of that signal — Unity will call your handler with the message and an optional type instead of rendering its own banner.
+
+This is the official way (supported since Unity 6.3) to surface Unity warnings and recoverable errors inside your React UI, for example as a toast, a banner of your own, or a telemetry event.
+
+- `message` is the human readable text Unity wanted to display.
+- `type` is `"error"` or `"warning"`. It may be `undefined` for messages that do not carry a severity.
+
+:::info
+The handler is captured once during initialisation and passed to `createUnityInstance`. Changing the function reference after the Unity Instance has booted will not have any effect, so prefer a stable reference (for example via `useCallback` or a module-scope function).
+:::
+
+## Example Usage
+
+A basic implementation could look something like this. In the following example we'll route warnings and errors to a piece of React state which renders a custom banner above the Unity canvas.
+
+```jsx {6-8,15} showLineNumbers title="App.jsx"
+import React, { useState } from "react";
+import { Unity, useUnityContext } from "react-unity-webgl";
+
+function App() {
+  const [banner, setBanner] = useState(null);
+
+  function handleShowBanner(message, type) {
+    setBanner({ message, type: type ?? "info" });
+  }
+
+  const { unityProvider } = useUnityContext({
+    loaderUrl: "build/myunityapp.loader.js",
+    dataUrl: "build/myunityapp.data",
+    frameworkUrl: "build/myunityapp.framework.js",
+    codeUrl: "build/myunityapp.wasm",
+    showBanner: handleShowBanner,
+  });
+
+  return (
+    <>
+      {banner && (
+        <div role="alert" data-severity={banner.type}>
+          {banner.message}
+        </div>
+      )}
+      <Unity unityProvider={unityProvider} />
+    </>
+  );
+}
+```
+
+When using TypeScript, the `UnityBannerType` is exported from the package so you can type your handler explicitly.
+
+```tsx showLineNumbers title="App.tsx"
+import { UnityBannerType } from "react-unity-webgl";
+
+function handleShowBanner(message: string, type?: UnityBannerType) {
+  // ...
+}
+```