meqn / unitywebgl.js

An easy solution for embedding Unity WebGL builds in webApp or Vue.js project, with two-way communication between your webApp and Unity. 🏣 在webApp 或 Vue.js 项目中嵌入 Unity WebGL，并支持通过API在 webApp 和 Unity 之间进行双向通信。

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

Features

• 📦 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 [email protected] & [email protected])

Install

npm

npm install unity-webgl

browser

https://cdn.jsdelivr.net/npm/unity-webgl/dist/index.global.js

# vue component
https://cdn.jsdelivr.net/npm/unity-webgl/vue/index.global.js

Usage

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

html

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

• [email protected] Live
• [email protected] Live

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>

API

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)

canvas

Rendering Unity's canvas elements

• type : string | HTMLCanvasElement

bridge

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__

config

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

Methods

UnityWebgl Instance Methods

create(canvasElement: HTMLCanvasElement | string): void

Create Unity instances and render them on the canvas.

• canvasElement : canvas canvas elements

unload(): Promise<void>

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(config): void

Reload Unity resources and rebuild the Unity application instance.

• config: The configuration of Unity application, @see

send(objectName: string, methodName: string, params?: any)

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

on(eventName: string, eventListener: Function)

⭐️ Register an event or method to listen for the trigger event or for the Unity script to call.

setFullscreen(enabled: boolean): void

Enables or disabled the fullscreen mode of the UnityInstance.

requestPointerLock(): void

Allows you to asynchronously request that the mouse pointer be locked to the Canvas element of your Unity application.

takeScreenshot(dataType: 'image/png' | 'image/jpeg' | 'image/webp', quality?: number)

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

once(eventName: string, eventListener: Function)

The registration event is executed only once

off(eventName: string)

Cancel listening event

emit(eventName: string)

Trigger listening event

clear()

Clear listening event

Events

Events triggered by a Unity instance from creation to destruction.

beforeMount

Before Unity resources start loading. (The Unity instance has not been created yet.)

unityContext.on('beforeMount', (unityContext) => {})

progress

Unity resource loading. (Show loading progress)

unityContext.on('progress', (number) => {})

mounted

The Unity instance is successfully created and rendered. (At this point the webApp and Unity can communicate with each other)

unityContext.on('mounted', (unityContext) => {})

beforeUnmount

Before the Unity instance exits.

unityContext.on('beforeUnmount', (unityContext) => {})

unmounted

The Unity instance has been exited and cleared from memory.

unityContext.on('unmounted', () => {})

reload

The Unity instance starts to reload.

unityContext.on('reload', (unityContext) => {})

error

Error messages caught by Unity instances during creation.

unityContext.on('error', (error) => {})

Vue component

Vue components, compatible with vue2.x and vue3.x.

props

• unity : UnityWebgl instance.
• width : canvas element width, default: 100%
• height : canvas element height, default: 100%

Communication

• WebGL: Interacting with browser [e-mail]

Calling JavaScript functions from Unity scripts

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.");
  }
}

Calling Unity scripts functions from JavaScript

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

ChangeLog

v3.5.0

🚀 Features

• feat: Add reload method and event.
• perf: Optimize the create and unload methods.

v3.4.0

🚀 Features

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

🐞 Bug Fixes

• fix: Repair SPA unload error

v3.0.0

🚀 Features

• feat: Rewrite in Typescript
• feat: Vue components are compatible with vue2.x and vue3.x
• perf: Introducing vue components on demand

🐞 Bug Fixes

• fix: Fix createUnityInstance multiple times
• fix: Fix vue component width/height size problem

v2.x

• v2.x Docs

v1.x

• v1.x Docs

unitywebgl.js's Issues

监听不到unity暴露出的方法

用C#开发的unity。
在web端使用window.xxx能监听到，使用插件的on('xxx')监听不到什么原因？

请问下，这种导出的unity目录还适用这个库吗

这是unity目录

loaderUrl,dataUrl,frameworkUrl,codeUrl这些和我目录下的文件好像都对应不上

Unity webgl Manual

https://github.com/Meqn/UnityWebGL.js/wiki/Document

Document

• Unity webgl Manual
• 使用 WebGL 模板
• WebGL：与浏览器脚本交互

中文教程

• Unity WebGL 开发指南
• Unity WebGL 与 JS通信
• 前端JS脚本调用Unity内的函数

UnityContext.Send not working

I am developing a Unity game that will run in the browser. It runs fine but I need to call a C# function from my Vue component and send a string to the WebGL app. For some reason, this does not work. If I provide the Scene name as an argument, I get an error that the scene does not exist. If I provide the GameObject name, I get an error that the method I'm calling doesn't exist. I initally had the unityContext.send function called right after I instantiate the unityContext variable but that didn't work either so I set it up as a button to see if it's a loading thing where the function was being called before objects in the scene had loaded. It doesn't work more in this format when I click on the button... Any help would be greatly appreciated!

This is what my Vue component currently looks like:

<script setup>
import { shallowRef } from "vue";
import { useRouter, useRoute } from "vue-router";
import useTimelineStepper from "@/composables/timelinestepper";
import useSmileStore from "@/stores/smiledata"; // get access to the global store
import UnityWebgl from "unity-webgl";
import UnityVue from "unity-webgl/vue";

const router = useRouter();
const route = useRoute();
const smilestore = useSmileStore();

const { next, prev } = useTimelineStepper();

if (route.meta.progress) smilestore.global.progress = route.meta.progress;

// assign conditions here for testing
const conditions = ["level1"];

// load unity
const unityContext = new UnityWebgl({
  loaderUrl: "/unity/Build/creative-physical-reasoning.loader.js",
  dataUrl: "/unity/Build/creative-physical-reasoning.data",
  frameworkUrl: "/unity/Build/creative-physical-reasoning.framework.js",
  codeUrl: "/unity/Build/creative-physical-reasoning.wasm",
});

// setup event listener for button click
function loadData() {
  console.log("loadData");
  unityContext.send("Menu", "LoadAllLevels", JSON.stringify(conditions));
}

function finish(goto) {
  // smilestore.saveData()
  unityContext.unload();
  if (goto) router.push(goto);
}
</script>

<template>
  <div class="page">
    <UnityVue :unity="unityContext" width="1080" height="675" />
    <button class="button is-success is-light" id="finish" @click="finish(next())">
      next &nbsp;<FAIcon icon="fa-solid fa-arrow-right" />
    </button>
    <button class="button is-success is-light" id="loadData" @click="loadData()">
      load data
    </button>
  </div>
</template>

unity和浏览器交互有demo吗

或者说unity和vue3的交互

Operation error

Code cannot be run on unity2021，Can you provide a simple demo

Compile Error: Component name "Unity" should always be multi-word

您好，首先感谢您开源一个vue社区唯一的untiy webgl库！

不幸的是我按照 example.vue 里的代码编译会报错，复现步骤如下
1.新建一个vue2项目
2. 安装npm install unity-webgl
3. 把自带的 HelloWorld.vue 改成说明文档里的例子

<template>
  <Unity :unity="unityContext" width="800px" height="600px" />
</template>

<script>
import UnityWebgl from 'unity-webgl'

const Unity = new UnityWebgl({
  loaderUrl: 'Build/OUT_BIM.loader.js',
  dataUrl: "Build/OUT_BIM.data",
  frameworkUrl: "Build/OUT_BIM.framework.js",
  codeUrl: "Build/OUT_BIM.wasm"
})

export default {
  name: 'Unity',
  component: {
    Unity: UnityWebgl.vueComponent
  },
  data() {
    return {
      unityContext: Unity
    }
  }
}
</script>

然后 npm run serve 出现这么一个错误：

R:\html\hello-world\src\components\HelloWorld.vue
  16:9  error  Component name "Unity" should always be multi-word  vue/multi-word-

请大佬不吝赐教

Communicaton from Unity to Vue not working

Hi, thanks for your great plugin!

Everything is working fine except communication from unity to vue. I want to listen on a method listenToUnity() in Unity. My code in Vue looks like this:

Unity.on("listenToUnity", () => console.log("I am listening to unity."));

What do I have to do in Unity? Your docu says __UnityLib__.showDialog(data), but I dont understand what I should do..

Can you help me please?

ppVis

Can't install with Nuxt 3.6.5 and Vue 3.3.4

Hi, first off great work! I have this working well with a Vue2 project. I'm upgrading my project to Nuxt 3.6.5 which runs on Vue3.3.4 and am receiving the following error:

npm WARN config global --global, --local are deprecated. Use --location=global instead.
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: nuxt-app@undefined
npm ERR! Found: [email protected]
npm ERR! node_modules/vue
npm ERR! peer vue@"^3.3.4" from @nuxt/[email protected]
npm ERR! node_modules/@nuxt/vite-builder
npm ERR! @nuxt/vite-builder@"3.6.5" from [email protected]
npm ERR! node_modules/nuxt
npm ERR! dev nuxt@"^3.6.5" from the root project
npm ERR! 2 more (@nuxt/devtools, @nuxt/devtools-kit)
npm ERR! peer vue@">=2.7 || >=3" from @unhead/[email protected]
npm ERR! node_modules/@unhead/vue
npm ERR! @unhead/vue@"^1.1.30" from [email protected]
npm ERR! node_modules/nuxt
npm ERR! dev nuxt@"^3.6.5" from the root project
npm ERR! 2 more (@nuxt/devtools, @nuxt/devtools-kit)
npm ERR! 6 more (@vitejs/plugin-vue, @vitejs/plugin-vue-jsx, ...)
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! unity-webgl@"^3.5.1" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: [email protected]
npm ERR! node_modules/vue
npm ERR! peer vue@">= 2.5 < 2.7" from @vue/[email protected]
npm ERR! node_modules/@vue/composition-api
npm ERR! peerOptional @vue/composition-api@"^1.7.0" from [email protected]
npm ERR! node_modules/unity-webgl
npm ERR! unity-webgl@"^3.5.1" from the root project

I was trying to work on a fix with your repo, but when I clone it and run npm install I receive the following error:

npm WARN config global --global, --local are deprecated. Use --location=global instead.
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: undefined@undefined
npm ERR! Found: [email protected]
npm ERR! node_modules/vue
npm ERR! dev vue@"^3.2.38" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer vue@">= 2.5 < 2.7" from @vue/[email protected]
npm ERR! node_modules/@vue/composition-api
npm ERR! dev @vue/composition-api@"^1.7.0" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

I'd love to help get this working in Vue3 if possible. Any guidance would be appreciated.

Thanks again!

Typescript definitions request

I would love to have Typescript definitions.

Error with IOS and communication with javascript

Hello, I created a game with unity and WebGL. Everything works fine on every device except for iOS. For some reason when i try to emit some values from unity to a function in javascript IOS return me an error and unity crashes. The error: __UnityLib__unityStarted() is not a function unityStarted is my function tha needs to be called to communicate in javascript. Again it gives me this error only on an Ipad or Iphone.

For the frontend tecnologies i'am using Nuxt (vuejs)

Thanks in advance

Unity build loads twice

Hello!

We have an app with different games. User can select a game from map-page.
Each game uses unity. We have a wrapper component for unity.

The problem is that when you open the NEXT game unity build loads twice.

So, for example, you open the first game (unity build loads). Then you go to map-page and choose another game. When this another game page is opened the build loads twice for some reason.

Do you have any idea what could be the reason?

Can't build without type: "module" in this dependency

I'm getting the following error when building:

/vercel/path0/node_modules/.pnpm/[email protected][email protected]/node_modules/unity-webgl/dist/index.esm.js:380
export { UnityWebgl as default };
^^^^^^

SyntaxError: Unexpected token 'export'
    at internalCompileFunction (node:internal/vm:73:18)
    at wrapSafe (node:internal/modules/cjs/loader:1176:20)
    at Module._compile (node:internal/modules/cjs/loader:1218:27)
    at Module._extensions..js (node:internal/modules/cjs/loader:1308:10)
    at Module.load (node:internal/modules/cjs/loader:1117:32)
    at Module._load (node:internal/modules/cjs/loader:958:12)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:169:29)
    at ModuleJob.run (node:internal/modules/esm/module_job:194:25)

I can solve it by editing the package.json of unity-webgl to have "type": "module", or by doing this weird import:

import UnityWebgl from "unity-webgl/dist/index.js";
import UnityVue from "unity-webgl/vue/index.js";

My own package.json has type: module as I require it for unrelated things.

Am using Node.js 18

Even with the uncommon import strategy I still get a warning:
ReferenceError: window is not defined

[help] unity资源替换

我目前使用electron打包桌面程序，工具使用的是electron-vite，资源放在了resources目录下，打包后可以正常运行，但是不能替换unity资源内容，一旦进行替换就不能正确加载，根据开发者工具里的内容看像是loader.js被一并打包了，如果想要把unity的内容单独提取出来做热替换是否可行，如果可行我该怎么做，感谢

Unity Webgl: Unityloader already exists

Hello!

I use UnityWebGL with Vue.
I have a wrapper component for it.

In mounted hook:

this.UnityContext = new UnityWebgl('#canvas', {
      loaderUrl: '/unity/test-customizer/BuildWA.loader.js',
      dataUrl: '/unity/test-customizer/BuildWA.data',
      frameworkUrl: '/unity/test-customizer/BuildWA.framework.js',
      codeUrl: '/unity/test-customizer/BuildWA.wasm',
   })

this.$once('hook:beforeDestroy', function () {
      console.log('hook:beforeDestroy');
      this.UnityContext.destroy()
      this.UnityContext = null
})

beforeDestroy hook works. But when I navigate between pages that use UnityWebGL I still have this warning:

Unity Webgl: Unityloader already exists

Could you please explain, what am I doing wrong?

setFullscreen not work

Thank you for your great plugin!

Almost works properly.
But setFullscreen() is not working on My environment(Unity2020.3.24f1).

VueCode:
Unity.setFullScreen(true);

Error:
"TypeError: Unity.setFullScreen is not a function"

Please, Can you help me ?

ittoh0819

文档错误导致无法正确运行

文档中的vue2.x 以下语句
import VueUnity from 'Unity-webgl/vue'
大小写错误。
应该是 import VueUnity from 'unity-webgl/vue'

unitylib Pointer__stringify()

replaced Pointer__stringify() with UTF8ToString in 2021.2 onwards

Vue 2 sample has some issue on running

Hi, thanks for the effort for this plugin.
I tested the Vue 2 sample(https://stackblitz.com/edit/unity-webgl-vue2-demo?file=package.json) but I found that there is some issue might cause the webgl unable to render properly.


Can you help to check on this issue?
Thx in advance for the support.