🏣 An easy solution for embedding Unity WebGL builds in webApp or Vue.js project, with two-way communication between your webApp and Unity.

Mervin

Last update: Jan 1, 2023

Overview

unity-webgl

Unity WebGL provides an easy solution for embedding Unity WebGL builds in your webApp or Vue.js project, with two-way communication between your webApp and Unity application with advanced API's.

UnityWebgl.js 提供了一种简单的解决方案，用于在 webApp 或 Vue.js （支持Vue2.x & Vue3.x）项目中嵌入 Unity WebGL，并通过API在 webApp 和 Unity 之间进行双向通信。

based on react-unity-webgl

Features

💊 Simple and flexible to use
📮 two-way communication (webApp, Unity)
🛠 Built-in event handler
🧬 Available for Vue.js ([email protected] & [email protected])

Install

npm & ESM

npm install unity-webgl

To make unity-webgl/vue work for Vue 2 (<2.7.0), you need to have @vue/composition-api installed:

npm i -D @vue/composition-api

browser

https://cdn.jsdelivr.net/npm/unity-webgl/dist/UnityWebgl.min.js

# vue component
https://cdn.jsdelivr.net/npm/unity-webgl/dist/VueUnity.min.js

Usage

in example.html

<canvas id="canvas" style="width: 100%; height: 100%">canvas>

<button onclick="onDestroy()">Destroybutton>
<button onclick="onLoad()">Reloadbutton>
<button onclick="onFullscreen()">Fullscreenbutton>

<script>
var Unity = new UnityWebgl('#canvas', {
  loaderUrl: '/Build/unity.loader.js',
  dataUrl: "/Build/unity.data",
  frameworkUrl: "/Build/unity.framework.js",
  codeUrl: "/Build/unity.wasm"
})

Unity
  .on('progress', percent => console.log('Unity Loaded: ', percent))
  .on('created', () => console.log('Unity Instance: created.'))
  .on('destroyed', () => console.log('Unity Instance: Destroyed.'))

function postMessage() {
  Unity.send('objectName', 'methodName', {
    id: 'B0001',
    name: 'Building#1',
    location: [150, 75]
  })
}

function onDestroy() {
  Unity.destroy()
}

function onLoad() {
  Unity.create('#canvas')
}

function onFullscreen() {
  Unity.setFullscreen(true)
}
script>

You can also:

var Unity = new UnityWebgl({
  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",
})

Unity.create(document.querySelector('#canvas'))

Vue

Vue 2.x

<template>
  <VueUnity :unity="unityContext" width="800" heighht="600" />
template>

<script>
  import UnityWebgl from 'unity-webgl'
  import VueUnity from 'Unity-webgl/vue'

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

  Unity.on('device', () => alert('click device ...'))

  export default {
    components: {
      VueUnity
    },
    data() {
      return {
        unityContext: Unity
      }
    }
  }
script>

Vue 3.x

import UnityWebgl from 'Unity-webgl'; import VueUnity from 'Unity-webgl/vue' 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", }) Unity.on('device', () => alert('click device ...')) ">

<script setup lang="ts">
import UnityWebgl from 'Unity-webgl';
import VueUnity from 'Unity-webgl/vue'

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

Unity.on('device', () => alert('click device ...'))
script>

<template>
  <VueUnity :unity="Unity" width="800" heighht="600" />
template>

API

unityContext = new UnityWebgl(canvasElement: HTMLCanvasElement | string, options: IUnityConfig)

Options

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
companyName?: string
The applications company name
productName?: string
The applications product name
productVersion?: string
The applications product version
webglContextAttributes?: IWebGLContextAttributes
This object allow you to configure WebGLRenderingContext creation options. see MDN@WebGLRenderingContext
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

Methods

create(canvasElement: HTMLCanvasElement | string)
send(objectName: string, methodName: string, params?: any)
Sends a message to the UnityInstance to invoke a public method.
setFullscreen(enabled: boolean)
Enables or disabled the fullscreen mode of the UnityInstance.
destroy()
Quits the Unity Instance and clears it from memory.

on(eventName: string, eventListener: Function)
Use instance.on() to register a method for Unity-script call.
once(eventName: string, eventListener: Function)
off(eventName: string)
clear()
emit(eventName: string)

Events

progress
loading progress.

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

loaded
loading completed.
```
 unityContext.on('loaded', () => {})
```
created
Unity Instance is created.
```
 unityContext.on('created', () => {})
```
destroyed
Quits the Unity Instance and clears it from memory.
```
 unityContext.on('destroyed', () => {})
```

Vue component

props

unity: UnityWebgl
width?: string|number , default: 100%
height?: string|number , default: 100%

Communication

1. Calling JavaScript functions from Unity scripts

从 Unity 脚本调用 JavaScript 函数

First, you should register a showDialog method, which be bind to the __UnityLib__ global object by default.

先在前端项目中通过 Unity.on() 注册 showDialog 方法，该方法会默认绑定在全局对象__UnityLib__上。

// # in webApp

const Unity = new UnityWebgl()
// Register functions
Unity.on('showDialog', (data) => {
  console.log(data)
  $('#dialog').show()
})

// you also can call function.
Unity.emit('showDialog', data)
// or
window[Unity.global_name].showDialog(data) // 📢 Unity.global_name = __UnityLib__

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:

在Unity项目中，将注册的showDialog方法添加到项目中。注意 📢 ：请使用 .jslib 扩展名将包含 JavaScript 代码的文件放置在 Assets 文件夹中的“Plugins”子文件夹下。插件文件需要有如下所示的语法：

// javascript_extend.jslib

mergeInto(LibraryManager.library, {
  // this is you code
  showDialog: function (str) {
    var data = Pointer_stringify(str);
    // '__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.");
    }
}

2. Calling Unity scripts functions from JavaScript

使用 JavaScript 调用 Unity 脚本函数

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

Comments

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-

请大佬不吝赐教

opened by orangeagain 10

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

opened by ppVis 4
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?

opened by OctopussyO 3

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?

opened by OctopussyO 2

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

opened by buddy94 1
assign required value to attribute before event emitted.

When I want to access unityInstace attribute in UnityWebGL instance right in created event,I found the attribute is null. I need to use setTimeout to wait 1ms to unityInstace, which doesn't make sense. So I suggest this update.

opened by RadianSmile 1
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

opened by ittoh0819 1
Unity webgl Manual
https://github.com/Meqn/UnityWebGL.js/wiki/Document

Document

Unity webgl Manual

使用 WebGL 模板

WebGL：与浏览器脚本交互

中文教程

Unity WebGL 开发指南

Unity WebGL 与 JS通信

前端JS脚本调用Unity内的函数

documentation
opened by Meqn 0