improve docs and readme, fix typings, add error callback

Author: Philipp Molitor

.eslintrc.js

@@ -26,7 +26,7 @@ module.exports = {
     tsconfigRootDir: __dirname,
     project: ['./tsconfig.json'],
   },
-  ignorePatterns: ['build/**'],
+  ignorePatterns: ['dist/**'],
   globals: {
     React: true,
     JSX: true,

.npmignore

@@ -7,6 +7,13 @@ src/
 .husky/
 .prettierrc
 .eslintrc.js
+.eslintcache
+tsconfig.json
+
+# jest
+__tests__/*
+*.test.ts
+*.test.tsx
 
 # npm/yarn
 yarn*.log

README.md

@@ -21,7 +21,7 @@ TODO
 NPM
 
 ```
-npm install --save-dev react-unity-renderer
+npm install --save react-unity-renderer
 ```
 
 Yarn
@@ -32,9 +32,9 @@ yarn add react-unity-renderer
 
 **Version compatability**
 
-| NPM version | Unity version     | `package.json` dependency             |
-| ----------- | ----------------- | ------------------------------------- |
-| `1.2020`    | `2020` and `2021` | `"react-unity-renderer": "1.2020.*",` |
+| Unity version     | NPM version |
+| ----------------- | ----------- |
+| `2020` and `2021` | `2020.*`    |
 
 ## Example usage
 
@@ -76,8 +76,10 @@ export const UnityGameComponent: VFC = (): JSX.Element => {
   return (
     <UnityRenderer
       context={ctx}
+      // optional state information callbacks
       onUnityProgressChange={(p) => setProgress(p)}
       onUnityReadyStateChange={(s) => setReady(s)}
+      onUnityError={(e) => console.error(e)}
       // <UnityRenderer> has every prop (except ref) from HTMLCanvasElement.
       // This means you can use something like style!
       // Also it works perfectly with styled-components.
@@ -145,7 +147,9 @@ function fetchLoaderConfig(baseUrl: string): Promise<UnityLoaderConfig> {
   let result: AxiosResponse<UnityLoaderConfig>;
 
   try {
+    // this disables caching!
     const url = `${baseUrl}/build.json?t=${new Date().getTime()}`;
+
     result = await axios.get<UnityLoaderConfig>(url);
   } catch (ex) {
     // network or request error

package.json

@@ -1,8 +1,9 @@
 {
   "name": "react-unity-renderer",
-  "version": "1.2020.1",
+  "version": "2020.0.0",
   "description": "React Unity Renderer allows to interactively embed Unity WebGL builds into a React powered project.",
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "author": "Philipp Molitor <philipp@molitor.cloud>",
   "license": "MIT",
   "repository": "git://github.com/PhilippMolitor/react-unity-renderer.git",
@@ -16,7 +17,7 @@
   ],
   "scripts": {
     "watch": "tsc --build ./tsconfig.json --watch",
-    "build": "tsc --build ./tsconfig.json",
+    "build": "rimraf dist && tsc --build ./tsconfig.json",
     "test": "echo \"no tests defined yet\" && exit 1",
     "lint": "eslint --fix ./src/",
     "lint:staged": "lint-staged",
@@ -31,7 +32,8 @@
     ]
   },
   "devDependencies": {
-    "@types/react": "^17.*",
+    "@types/react": "^16.8.0",
+    "@types/react-dom": "^16.8.0",
     "@typescript-eslint/eslint-plugin": "^4.15.2",
     "eslint": "^7.20.0",
     "eslint-config-airbnb-typescript": "^12.0.0",
@@ -45,9 +47,11 @@
     "husky": "^5.1.1",
     "lint-staged": "^10.5.4",
     "prettier": "^2.2.1",
+    "rimraf": "^3.0.2",
     "typescript": "^4.*"
   },
   "peerDependencies": {
-    "react": ">= 17"
+    "react": "^16.8.0, >= 17",
+    "react-dom": "^16.8.0, >=17"
   }
 }

src/components/UnityRenderer.ts

@@ -13,6 +13,7 @@ export type UnityRendererProps = Omit<
   context: UnityContext;
   onUnityProgressChange?: (progress: number) => void;
   onUnityReadyStateChange?: (ready: boolean) => void;
+  onUnityError?: (error: Error) => void;
 };
 
 /**
@@ -29,9 +30,10 @@ export const UnityRenderer: VFC<UnityRendererProps> = ({
   context,
   onUnityProgressChange,
   onUnityReadyStateChange,
+  onUnityError,
   ...canvasProps
 }: UnityRendererProps): JSX.Element | null => {
-  const [service] = useState<UnityLoaderService>(new UnityLoaderService());
+  const [loader, setLoader] = useState<UnityLoaderService>();
 
   // We cannot actually render the `HTMLCanvasElement`, so we need the `ref`
   // for Unity and a `JSX.Element` for React rendering.
@@ -68,16 +70,15 @@ export const UnityRenderer: VFC<UnityRendererProps> = ({
    * @returns {Promise<void>} A Promise resolving on successful mount of the
    * Unity instance.
    */
-  async function mountUnityInstance(): Promise<void> {
-    if (!renderer) return;
-
+  async function mount(): Promise<void> {
     // get the current loader configuration from the UnityContext
     const c = context.getConfig();
 
     // attach Unity's native JavaScript loader
-    await service.attachLoader(c.loaderUrl);
-    const nativeUnityInstance = await window.createUnityInstance(
-      renderer,
+    await loader!.execute(c.loaderUrl);
+
+    const instance = await window.createUnityInstance(
+      renderer!,
       {
         dataUrl: c.dataUrl,
         frameworkUrl: c.frameworkUrl,
@@ -91,20 +92,24 @@ export const UnityRenderer: VFC<UnityRendererProps> = ({
     );
 
     // set the instance for further JavaScript <--> Unity communication
-    context.setInstance(nativeUnityInstance);
+    context.setInstance(instance);
   }
 
   // on canvas change
   useEffect(() => {
-    if (renderer)
-      mountUnityInstance().catch((e) => {
-        // eslint-disable-next-line no-console
-        console.error('failed to mount unity instance: ', e);
+    if (loader && renderer)
+      mount().catch((e) => {
+        if (onUnityError) onUnityError(e);
+        if (onUnityProgressChange) onUnityProgressChange(0);
+        if (onUnityReadyStateChange) onUnityReadyStateChange(false);
       });
-  }, [renderer]);
+  }, [loader, renderer]);
 
   // on mount
   useEffect(() => {
+    // create the loader service
+    setLoader(new UnityLoaderService());
+
     // create the renderer and let the ref callback set its handle
     setCanvas(
       createElement('canvas', {
@@ -117,7 +122,8 @@ export const UnityRenderer: VFC<UnityRendererProps> = ({
     return () => {
       context.shutdown(() => {
         // remove the loader script from the DOM
-        service.detachLoader();
+        if (loader) loader.unmount();
+
         // reset progress / ready state
         if (onUnityProgressChange) onUnityProgressChange(0);
         if (onUnityReadyStateChange) onUnityReadyStateChange(false);

src/context.ts

@@ -1,24 +1,62 @@
 import './global';
 import { UnityLoaderConfig } from './interfaces/config';
 
+export type UnityEventCallback = (...params: any) => void;
+
+/**
+ * Defines a Unity WebGL context.
+ *
+ * The context is responsible for the initial startup parameters of the
+ * `UnityRenderer`, as well as receiving events and emitting RPCs to Unity.
+ *
+ */
 export class UnityContext {
+  private config: UnityLoaderConfig;
+
   private instance?: UnityInstance;
 
-  private config: UnityLoaderConfig;
+  private eventCallbacks: { [name: string]: UnityEventCallback } = {};
 
+  /**
+   * Creates a new `UnityContext` and registers the global event callback.
+   *
+   * @param {UnityLoaderConfig} config A loader configuration object.
+   */
   constructor(config: UnityLoaderConfig) {
     this.config = config;
-    if (!window.UnityBridge) window.UnityBridge = {};
+
+    // callback is needed so it can access the actual eventCallbacks object
+    if (!window.UnityBridge)
+      window.UnityBridge = (name: string) => this.bridgeCallback(name);
   }
 
+  /**
+   * Retrieves the currently activte loader configuration.
+   *
+   * @returns {UnityLoaderConfig} The current loader configuration object.
+   */
   public getConfig(): UnityLoaderConfig {
     return this.config;
   }
 
-  public setInstance(unityInstance: UnityInstance): void {
-    this.instance = unityInstance;
+  /**
+   * Sets the Unity instance this `UnityContext` is responsible for.
+   *
+   * @param {UnityInstance} instance The running Unity instance
+   */
+  public setInstance(instance: UnityInstance): void {
+    this.instance = instance;
   }
 
+  /**
+   * Shuts down the running Unity instance, then unregisters the existing
+   * event handlers.
+   *
+   * @param {() => void} onShutdownFinished Callback to execute when the
+   * shutdown has been completed.
+   *
+   * @returns {void} void
+   */
   public shutdown(onShutdownFinished?: () => void): void {
     if (!this.instance) return;
 
@@ -36,34 +74,69 @@ export class UnityContext {
       );
   }
 
-  public emitUnityEvent(
+  /**
+   * Emits a remote procedure call towards the running Unity instance.
+   *
+   * @param {string} objectName The `GameObject` on which to call the method.
+   * @param {string} methodName The name of the method which should be invoked.
+   * @param {(string | number)} value The value to pass to the method
+   * as the first parameter.
+   * @returns {void} void
+   */
+  public emit(
     objectName: string,
     methodName: string,
-    value?: string | number | boolean
+    value?: string | number
   ): void {
     if (!this.instance) return;
 
     this.instance.SendMessage(objectName, methodName, value);
   }
 
-  public on<T extends (...params: any) => void = () => void>(
-    name: string,
-    callback: T
-  ): void {
-    window.UnityBridge[name] = callback;
-  }
-
-  public off(name: string) {
-    if (name in window.UnityBridge) window.UnityBridge[name] = () => undefined;
+  /**
+   * Delegates an event handler to handle an event (from Unity) by using a
+   * callback function.
+   *
+   * @param {string} name The (unique) name of the event.
+   * @param {UnityEventCallback} callback The callback which should be invoked
+   * upon the occurence of this event.
+   */
+  public on<T extends UnityEventCallback>(name: string, callback: T): void {
+    this.eventCallbacks[name] = callback;
   }
 
+  /**
+   * Enables or disables fullscreen mode.
+   *
+   * @param {booolean} enabled Whether to enable or disable fullscreen.
+   * @returns {void} void
+   */
   public setFullscreen(enabled: boolean): void {
     if (!this.instance) return;
     this.instance.SetFullscreen(enabled ? 1 : 0);
   }
 
+  /**
+   * The internal handler for any incoming event.
+   * Logs a warning for events with names that are not registered.
+   *
+   * @param {string} name The name of the event.
+   * @returns {UnityEventCallback} The  callback which should
+   * handle the event.
+   */
+  private bridgeCallback(name: string): UnityEventCallback {
+    if (this.eventCallbacks && this.eventCallbacks[name])
+      return this.eventCallbacks[name];
+
+    // eslint-disable-next-line no-console
+    console.warn(`called event "${name}" which currently is not registered`);
+    return () => undefined;
+  }
+
+  /**
+   * Unregisters all event handlers.
+   */
   private unregisterAllEventHandlers() {
-    if (!window.UnityBridge || typeof window.UnityBridge !== 'object') return;
-    Object.keys(window.UnityBridge).forEach((k) => this.off(k));
+    this.eventCallbacks = {};
   }
 }

src/global.ts

@@ -1,8 +1,6 @@
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 interface Window {
-  UnityBridge: {
-    [event: string]: (...params: any) => void;
-  };
+  UnityBridge: (name: string) => (...params: any) => void;
 
   createUnityInstance(
     element: HTMLCanvasElement,

src/index.ts

@@ -1,4 +1,4 @@
 /* eslint-disable import/no-cycle */
-export { UnityContext } from './context';
+export { UnityContext, UnityEventCallback } from './context';
 export { UnityRenderer, UnityRendererProps } from './components/UnityRenderer';
 export { UnityLoaderConfig } from './interfaces/config';

src/loader.ts

@@ -3,7 +3,15 @@ export class UnityLoaderService {
 
   private script?: HTMLScriptElement;
 
-  public attachLoader(url: string): Promise<void> {
+  /**
+   * Creates a new `<script>` tag in the DOM which executes the Unity WebGL
+   * loader.
+   *
+   * @param {string} url The url of the Unity WebGL loader script.
+   * @returns {Promise<void>} A `Promise` that resolves on successful
+   * script execution.
+   */
+  public execute(url: string): Promise<void> {
     // eslint-disable-next-line consistent-return
     return new Promise<void>((resolve, reject): void => {
       // already loaded
@@ -27,7 +35,10 @@ export class UnityLoaderService {
     });
   }
 
-  public detachLoader(): void {
+  /**
+   * Removes the loaders `<script>` tag from the DOM.
+   */
+  public unmount(): void {
     this.script?.remove();
   }
 }

tsconfig.json

@@ -19,5 +19,5 @@
     "jsx": "react-jsx"
   },
   "include": ["src", ".eslintrc.js", "typings/**/*.d.ts"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/**/*.test.tsx"]
 }