unity-webgl

[ English | 中文 ]

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 the Unity instance has been successfully created (i.e. the mounted event is triggered).
It is recommended to add a loading when opening a page, wait for Unity resources to finish loading and close it.

<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>

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@2.x Live
• Vue@3.x Live

<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.

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.

• WebGL: Interacting with browser scripting@Unity3d.Docs

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 and unload 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.
• 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

• v2.x Docs

• v1.x Docs