react-unity-webgl

Documentation · Template Repository · Support the project · Discussion Board

Made with ♥ by Jeffrey Lanters

When bringing your Unity Application to the web, you might need to communicate with Components on a webpage, build interactive interfaces or might want to implement functionality using Web APIs which Unity does not expose. Combining Unity with React is a great way to achieve these goals. React Unity WebGL provides a modern solution for embedding Unity WebGL builds in your React Application while providing advanced APIs for two way communication and interaction between Unity and React.

A quick word

Hi there! I would like to say one more thing before you start bringing your awesome games to the web. My name is Jeffrey Lanters, I'm a Unity and Web developer with a passion for Open Source. The project you're looking at right now is one of my hobby projects. Maintaining and building this project is something I do in my spare time, and I have been doing so since 2017. React-Unity-WebGL will always remain free, but adding new features, maintaining it and keeping up-to-date with Unity's updates takes a lot of work and time. If you are able to, I would appreciate it greatly if you would consider sending a donation or becoming a sponsor to help me keep this project going.

Thanks for your time, happy coding!

Installation

Get started by installing React Unity WebGL using the Node Package Manager or Yarn in your JavaScript or TypeScript React project. If you don't have a React project yet, I recommend using Vite React template to get you started right away. Visit the installation documentation for more information.

Before installing the module, make sure you're installing a version which is compatible with your build's Unity version. When a new Unity version releases, I'll update the module as soon as possible in order to keep the compatibility up to date. If you are running into any issues, please consider opening an issue.

% npm install react-unity-webgl

Unity Version Compatibility

The web and Unity are evolving fast, to keep up with these changed the React Unity WebGL module has to adapt too while also keeping the module fast, lightweight and compatible. Starting at version 9 of the module, support for builds made with Unity versions prior to 2020 are no longer supported. If you're using an older version of Unity, or you'll have to maintain a project built with an older version of the module, you can use one of the legacy versions of React Unity WebGL. It however is recommended to update your project to a newer version of Unity in order to use all the latest features of React Unity WebGL.

Visit on the official website for more information and the documentation and API reference of older versions of React Unity WebGL.

Documentation

Learn everything you'll need to know about React Unity WebGL on the official website.

• The docs will teach you all of the basics and concepts of React Unity WebGL.
• Dive straight into the API reference to learn everything the module has to offer.
• When using an older version of Unity, you might want to check any of the legacy docs.
• Looking to share and showcase what you've built? Check out the made with page!
• Feel free to join the React Unity WebGL Community Discord to ask questions, contribute to the project, share your work or just hang out!

The source code of both the website and the module are contained within this mono-repo. Feel free to open a pull request to improve or add features to the any of these. Looking for a new feature, but not sure where to start? Feel free to spin up a new discussion.

Getting Started

The documentation consists of several examples, for both starting as well as more advanced users. You can find these in the quick start and advanced examples sections. To get you started, the most basic implementation should look something like this:

import React from "react";
import { Unity, useUnityContext } from "react-unity-webgl";

function App() {
  const { unityProvider } = useUnityContext({
    loaderUrl: "build/myunityapp.loader.js",
    dataUrl: "build/myunityapp.data",
    frameworkUrl: "build/myunityapp.framework.js",
    codeUrl: "build/myunityapp.wasm",
  });

  return <Unity unityProvider={unityProvider} />;
}

Simply rendering your Unity Application within your React Application is just the beginning! The Unity Context exposes a lot more fun functions and properties to play around with such as two way communication or requesting fullscreen or a pointerlock. The possibilities are endless, what's next is up to you!

Note that all of the URLs which can be provided to the Unity Config, including the ones mentioned above, are due to their enormous size not included into your bundle. You should place these files in a public directory within your project or use a CDN. This means the files behind these URLs are loaded during runtime and should be accessible by the browser via a public URL. To learn more about the Unity Config, head over to the Unity Config documentation.

Contributing

You're looking into contributing? Awesome! When wanting to contribute to either the module, or the documentation, this mono-repository has everything all you'll need to get you started. It is recommended to discuss the change you wish to make first via the discussion board before submitting a pull request.

For more information about contribution and the development and test-cycle, please head over to the documentation on the official website.

Happy coding!