UnityWebGL.js provides an easy solution for embedding Unity WebGL
builds in your webApp
or Vue.js
project, with two-way communication and interaction between your webApp and Unity application with advanced API's.
based on react-unity-webgl
- 📦 No framework restrictions, support any web project.
- 📬 two-way communication and interaction (
webApp
&Unity
). - 💌 Built-in event-listening mechanism.
- 🧲 On-demand import vue component. (Supports Vue@2.x & Vue@3.x)
npm install unity-webgl
https://cdn.jsdelivr.net/npm/unity-webgl/dist/index.global.js
# vue component
https://cdn.jsdelivr.net/npm/unity-webgl/vue/index.global.js
🚨 Reminder:
You can only communicate and interact with the web application once theUnity
instance has been successfully created (i.e. themounted
event is triggered).
It is recommended to add a loading when opening a page, wait for Unity resources to finish loading and close it.
html demo
<canvas id="canvas" style="width: 100%; height: 100%"></canvas>
<button onclick="postMessage()">postMessage</button>
<button onclick="onFullscreen()">Fullscreen</button>
<button onclick="onUnload()">Unload</button>
<button onclick="onReload()">Reload</button>
<script>
var unityContext = new UnityWebgl('#canvas', {
loaderUrl: '/Build/unity.loader.js',
dataUrl: "/Build/unity.data",
frameworkUrl: "/Build/unity.framework.js",
codeUrl: "/Build/unity.wasm",
streamingAssetsUrl: "StreamingAssets",
companyName: "DefaultCompany",
productName: "Unity",
productVersion: "0.1",
})
unityContext
.on('progress', (progress) => console.log('Loaded: ', progress))
.on('mounted', () => {
// ⚠️ Resources are loaded and ready to communicate with unity
unityContext.send('mainScene', 'init', {})
console.log('Unity Instance created.')
})
.on('unmounted', () => console.log('Unity Instance unmounted.'))
function postMessage() {
unityContext.send('objectName', 'methodName', {
id: 'B0001',
name: 'Building#1',
location: [150, 75]
})
}
function onUnload() {
unityContext.unload()
}
function onReload() {
unityContext.reload({
loaderUrl: '/Build2/unity.loader.js',
dataUrl: "/Build2/unity.data",
frameworkUrl: "/Build2/unity.framework.js",
codeUrl: "/Build2/unity.wasm",
})
}
function onFullscreen() {
unityContext.setFullscreen(true)
}
</script>
You can also:
var unityContext = new UnityWebgl({
loaderUrl: '/Build/unity.loader.js',
dataUrl: "/Build/unity.data",
frameworkUrl: "/Build/unity.framework.js",
codeUrl: "/Build/unity.wasm"
})
unityContext.create(document.querySelector('#canvas'))
Vue demo
<script setup>
import UnityWebgl from 'unity-webgl';
import VueUnity from 'unity-webgl/vue'
const unityContext = new UnityWebgl({
loaderUrl: '/Build/OUT_BIM.loader.js',
dataUrl: "/Build/OUT_BIM.data",
frameworkUrl: "/Build/OUT_BIM.framework.js",
codeUrl: "/Build/OUT_BIM.wasm",
})
unityContext.on('device', () => alert('click device ...'))
</script>
<template>
<VueUnity :unity="unityContext" width="800" height="600" />
</template>
unityContext = new UnityWebgl(
canvas: HTMLCanvasElement | string,
config: IUnityConfig,
bridge?: string
)
Or
// 1. Initialize UnityWebgl
unityContext = new UnityWebgl(
config: IUnityConfig,
bridge?: string
)
// 2. Create unity instance and render on canvas
unityContext.create(canvas: HTMLCanvasElement | string)
Rendering Unity's canvas elements
- type :
string | HTMLCanvasElement
The name of the bridge to communicate with Unity. It mounts on window and is used to collect registered methods for Unity to call.
- type :
string
- default :
__UnityLib__
Initializes the configuration of the Unity application.
The configuration must contain the four most basic properties
loaderUrl
,dataUrl
,frameworkUrl
,codeUrl
, which are the resource files needed to initialize the Unity application.
Property | Type | Description |
---|---|---|
loaderUrl ⭐️ |
string | The url to the build json file generated by Unity |
dataUrl ⭐️ |
string | The url to the build data file generated by Unity |
frameworkUrl ⭐️ |
string | The url to the framework file generated by Unity |
codeUrl ⭐️ |
string | The url to the unity code file generated by Unity |
streamingAssetsUrl |
string | The url where the streaming assets can be found |
memoryUrl |
string | External memory file |
symbolsUrl |
string | Providing debugging symbols |
companyName |
string | The applications company name |
productName |
string | The applications product name |
productVersion |
string | The applications product version |
devicePixelRatio |
number | Uncomment this to override low DPI rendering on high DPI displays. see MDN@devicePixelRatio |
matchWebGLToCanvasSize |
boolean | Uncomment this to separately control WebGL canvas render size and DOM element size. see unity3d@matchWebGLToCanvasSize |
webglContextAttributes |
object | This object allow you to configure WebGLRenderingContext creation options. see MDN@WebGLRenderingContext |
UnityWebgl Instance Methods
Create Unity instances and render them on the canvas.
-
canvasElement
: canvas canvas elements
Quits the Unity instance and clears it from memory so that Unmount from the DOM.
The
unmounted
event will be triggered after the operation is completed.
Reload Unity resources and rebuild the Unity application instance.
-
config
: The configuration of Unity application, @see
⭐️ Sends a message to the UnityInstance to invoke a public method.
-
objectName
: Where objectName is the name of an object in your scene. -
methodName
: methodName is the name of a C-Sharp method in the script, currently attached to that object. -
params
: Parameters can be any type of value or not defined at all.
⭐️ Register an event or method to listen for the trigger event or for the Unity script to call.
Enables or disabled the fullscreen mode of the UnityInstance.
Allows you to asynchronously request that the mouse pointer be locked to the Canvas element of your Unity application.
Takes a screenshot of the canvas and returns a data URL containing image data.
-
dataType
: the type of the image data -
quality
: the quality of the image
The registration event is executed only once
Cancel listening event
Trigger listening event
Clear listening event
Events triggered by a Unity instance from creation to destruction.
Before Unity resources start loading. (The Unity instance has not been created yet.)
unityContext.on('beforeMount', (unityContext) => {})
Unity resource loading. (Show loading progress)
unityContext.on('progress', (number) => {})
The Unity instance is successfully created and rendered. (At this point the webApp and Unity can communicate with each other)
unityContext.on('mounted', (unityContext) => {})
Before the Unity instance exits.
unityContext.on('beforeUnmount', (unityContext) => {})
The Unity instance has been exited and cleared from memory.
unityContext.on('unmounted', () => {})
The Unity instance starts to reload.
unityContext.on('reload', (unityContext) => {})
Error messages caught by Unity instances during creation.
unityContext.on('error', (error) => {})
Vue components, compatible with vue2.x
and vue3.x
.
-
unity
: UnityWebgl instance. -
width
: canvas element width, default:100%
-
height
: canvas element height, default:100%
-
tabindex
: Set the Canvas element tabindex.
1, First, you should register a showDialog
method, which be bind to the __UnityLib__
global object by default.
// # in webApp
const unityContext = new UnityWebgl()
// Register functions
unityContext.on('showDialog', (data) => {
console.log(data)
$('#dialog').show()
})
// you also can call function.
unityContext.emit('showDialog', data)
2, In the Unity project, add the registered showDialog
method to the project, and then call those functions directly from your script code. To do so, place files with JavaScript code using the .jslib
extension under a “Plugins” subfolder in your Assets folder. The plugin file needs to have a syntax like this:
// javascript_extend.jslib
mergeInto(LibraryManager.library, {
// this is you code
showDialog: function (str) {
// var data = Pointer_stringify(str);
var data = UTF8ToString(str); // In Unity 2021.2 onwards
// '__UnityLib__' is a global function collection.
__UnityLib__.showDialog(data);
},
Hello: function () {
window.alert("Hello, world!");
}
});
Then you can call these functions from your C# scripts like this:
using UnityEngine;
using System.Runtime.InteropServices;
public class NewBehaviourScript : MonoBehaviour {
[DllImport("__Internal")]
private static extern void Hello();
[DllImport("__Internal")]
private static extern void showDialog(string str);
void Start() {
Hello();
showDialog("This is a string.");
}
}
const Unity = new UnityWebgl()
/**
* Sends a message to the UnityInstance to invoke a public method.
* @param {string} objectName Unity scene name.
* @param {string} methodName public method name.
* @param {any} params an optional method parameter.
*/
Unity.send(objectName, methodName, params)
// e.g. Initialize Building#001 data
Unity.send('mainScene', 'init', {
id: 'b001',
name: 'building#001',
length: 95,
width: 27,
height: 120
})
- feat: Add
reload
method and event. - perf: Optimize the
create
andunload
methods.
- feat: Add configuration and changes to the global object
bridge
. - feat: Unify events from creation to destruction of Unity applications.
- Adds
beforeMount
,mounted
,beforeUnmount
,unmounted
events; - Remove
created
,destroyed
events.
- Adds
- perf: Simplify the built-in event listener.
- perf: Optimize built-in vue components.
- perf: update typescript types.
- perf: Unified error message alert.
- docs: Optimize the use of documentation.
- fix: Repair SPA unload error
- feat: Rewrite in Typescript
- feat: Vue components are compatible with vue2.x and vue3.x
- perf: Introducing vue components on demand
- fix: Fix createUnityInstance multiple times
- fix: Fix vue component width/height size problem