Hello! If you are a game developer looking to create a game hosted on the Internet Computer blockchain, you are in luck.
I created a simple Unity project to demonstrate wallet integration and acquiring NFTs - just for you, now you can start working on the really "fun" parts of your game without worrying about how to call browser Javascript from Unity C#.
You can view a demo of this wallet integration at:
ti5gm-bqaaa-aaaai-ab7oa-cai.raw.ic0.app
The project code is located at:
github.com/tommygames/ic-unity-template
NOTE: This project integrates an npm module called react-unity-webgl to allow Unity C# to communicate with browser Javascript for Plug Wallet integration. If you do not need wallet integration or Javascript interoperability, do not follow this guide as there are easier ways to deploy a simple Unity game to IC.
If you want to see how I set up the project from scratch, skip to the Creating an IC Unity Project from Scratch section; if you just want to download and deploy the Unity project, skip to the Deploying an IC Unity Project section; if you want to see how the code works, read the “How It Works” section below.
How it works
Plug Wallet integration requires 2 features to work:
Unity C# Dispatching events to browser Javascript
Browser Javascript dispatches events to Unity
For both of these we use an npm module called react-unity-webgl, the documentation for which can be found here:
npmjs.com/package/react-unity-webgl
For the first feature, we use the .jslib plugin in Unity to write pseudo-Javascript (often called UnityScript), read more about it here:
docs.unity3d.com/Manual/webgl-interactingwithbrowserscripting.html
If you have the react-unity-webgl module installed, these .jslib plugins can dispatch events to the React browser Javascript by calling dispatchReactUnityEvent("EventName"), which you can see implemented in the PlugUtils.jslib file in the Unity project.
To call these functions, you must import them into C#, an example of which can be seen in the PlugUtilsInternal class in the PlugUtils.cs file.
For the second functionality, we call unityContext.send("GameObjectName", "FunctionName", jsonData) from the React javascript code, you can see its implementation in the PlugUtils.js class of our React application.
This will call the specified function on the specified GameObject, for my example I have a GameObject called ReactApi in the MainScene and the script contains a function called HandleCallback.
Since I want to have callbacks whenever Unity talks to the browser Javascript, I stored a dictionary of callbacks associated with their indexes in the ReactApi.cs file, this way, any communication between Unity and React must go through the ReactApi file and the callbacks will be triggered when JSON data is returned.
Once the JSON data is returned, I use Json.NET to deserialize the data into an object, which is defined in the WalletDataTypes.cs file.
If the JSON data is deserialized successfully, it displays it to the UI, and that’s how everything works.
Deploy IC Unity project
1. Download the project file from the following URL:
github.com/tommygames/ic-unity-template
2. Make sure you have the Dfinity container smart contract SDK installed (I used version 0.9.3 in this project):
smartcontracts.org/docs/developers-guide/install-upgrade-remove.html
3. cd into the ic_unity_template folder inside the Unity project (which contains the dfx project).
4. Run npm install and ensure all node modules are installed correctly, you may have to follow specific instructions to ensure the dab-js node module is installed correctly, instructions can be found here:
docs.dab.ooo/nft-list/getting-started
5. Run dfx start --background inside the ic_unity_template folder to start the local IC environment in the background, run dfx deploy to deploy the IC container to the local IC environment, after the deployment is complete, it will tell you a URL where you can access the project.
6. To deploy the project to the mainnet public blockchain network, you need to cd into the ic_unity_template folder and run dfx deploy --network=ic. After deployment, it will tell you the container ID of the ic_unity_template_assets container. You can access the project by visiting the following URL:
https://.raw.ic0.app
Note: It is important to include the "raw" keyword in the URL because Unity files are very large and can only be served using this keyword.
If you make changes to your Unity project and rebuild it, make sure to name your build unity_build.
Once the build is complete, drag the Build, TemplateData, and StreamingAssets (if present) folders into your src/ic_unity_template_assets/assets folder (you can ignore the index.html file), and then you can redeploy to your container.
Thanks for reading this far, that’s how to deploy a sample Unity project with react-unity-webgl integration for calling between Javascript and C#, I hope you enjoyed reading and I wish you good luck in your game development adventures, feel free to reach out to me on Twitter (@tommyinvests), I’m the lead developer of Plethora games.
Creating an IC Unity project from scratch
1. Create a new Unity project.
2. Download and install the Dfinity container smart contract SDK:
smartcontracts.org/docs/developers-guide/install-upgrade-remove.html
3. dfx is the main command line tool for starting a new Dfinity project. It automatically populates the project with template code. Documentation can be found here:
smartcontracts.org/docs/developers-guide/cli-reference.html
4. Open a command line and cd into your Unity project folder, then run dfx new project-name-goes-here to create a new template project named "project-name-goes-here", which will create a new dfx project in your Unity project folder.
Note: You don’t have to create dfx projects in the Unity project folder, you can also put them in separate folders.
5. Next, you need to modify the template dfx project to be compatible with the React web framework.
6. We will be using the React framework as a wrapper around the Unity project to allow messages to be sent between the React javascript code and the Unity C#, this makes wallet integration possible and also gives you the flexibility to overlay web components (in React) on top of your game in the future if you wish.
7. I followed this Dfinity guide to make my project compatible with React:
smartcontracts.org/docs/developers-guide/tutorials/custom-frontend.html
Note: You do not need to follow all the steps in the guide, just the following:
Run npm install --save react react-dom in your project folder
In your project folder run npm install --save-dev typescript ts-loader
Open webpack.config.js and add the following code above the plugins section:
Create a new file called tsconfig.json in the root directory of your project and paste the following code into it:
8. Once the dfx project is set up to be compatible with React, you need to create the React project files. I started a default React project using the "Create React App" command line tool:
reactjs.org/docs/create-a-new-react-app.html
9. Once your React project is created, copy your index.html, index.js, index.css, App.js, App.css, and any other relevant files from your React project’s scr folder into your project’s src/project_name_assets/src folder. This is where all of your private files will go. You’ll also notice there’s a folder next to the assets folder called src. This is where all of your public files will go, including your Unity build files.
10. Once you have copied the React files into your dfx project, you will need to make sure the following npm modules are installed for your project.
11. The react-unity-webgl module is very important because it allows us to send events between React and Unity, these events will allow Unity to interact with the browser Javascript and connect to the Plug Wallet, you can find its documentation here:
npmjs.com/package/react-unity-webgl
You can install it by running the following command in the dfx project folder:
After installation, modify your App.js file as described in the react-unity-webgl documentation. The basic implementation of App.js looks like this:
12. The dab-js module is a library created by Psychedelic to help us query their NFT database, which will allow us to get all the NFTs currently in the user's Plug wallet.
Note: The installation process for this npm module is a bit complicated. Before downloading the module, you will need to create a Github access token and log in. Please follow the instructions here:
docs.dab.ooo/nft-list/getting-started
13. Finally, you need to make sure your @dfinity/agent, @dfinity/principal, and @dfinity/candidnpm modules are using version 0.9.3 or lower, this is because the dab-js module currently only supports these versions or lower due to principal ID encoding changes, you can run the following command to ensure the version:
14. Now you need to build your Unity project, open Unity and go to File->Build Settings and switch to the WebGL platform.
15. Then go to Edit->Project Settings and set “Compression Format” to Disabled. IC container currently does not support Gzip or Brotli compression formats.
16. Finally, go back to the build settings and click the "Build" button. The build name you specify will also change the prefix of the build files. Let's call ours "BestGame". Once the build is complete, drag the Build, TemplateData, and StreamingAssets (if present) folders into the src/project_name_assets/assets folder in your dfx project (you can ignore the index.html file). You will then need to go back to step 11 and edit your App.js to have the correct file paths for the build files. If our build name was "BestGame", then our App.js file would look like this:
17. Once this is done you are ready to upload your game to IC, cd into your dfx project folder and run dfx start --background this will start the local IC environment in the background, then run dfx deploy this will deploy your IC Unity game to the local IC environment, once it is done it will give you a URL where you can access your game.
18. To deploy your IC game to the mainnet public blockchain network, you need to cd into the dfx project folder and run dfx deploy --network=ic, after deployment, it will tell you the container ID of the project_name_assets container, and you can access your game by visiting the following URL:
https://.raw.ic0.app
Note: It is important to include the "raw" keyword in the URL because Unity files are very large and can only be served using this keyword.
Thanks for reading this far, that’s how you can create a Unity project with react-unity-webgl integration and deploy it to a container for calling between Javascript and C#, I hope you enjoyed reading and I wish you good luck in your game development adventures, feel free to reach out to me on Twitter (@tommyinvests), I’m the lead developer of Plethora games.
IC content you care about
Technology Progress | Project Information | Global Activities
Collect and follow IC Binance Channel
Get the latest news