unity-webgl

[ English | 中文 ]

unity-webgl 提供了一个简单的解决方案，用于将 Unity WebGL 构建嵌入到 Web 应用程序中，同时为 Unity 和 WebApp 应用之间的双向通信和交互提供 API。

🚨 提醒

v4.x 版本进行了较大更新，API 不兼容 v3.x及之前版本。升级请参考 变更信息

Based on react-unity-webgl

Features

• 📦 集成简单，无框架限制
• 📩 支持 WebApp 与 Unity 双向通信和交互
• ⏰ 全面的事件处理机制
• 🧲 内置 vue 组件 (vue2/3)

Installation

npm

npm install unity-webgl

browser

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

Quick Start

• Live Demo
• vue3 Demo

🚨 提醒：
仅在 Unity 实例成功创建后（触发 mounted 事件时）才能进行 Web 应用程序的通信和交互。 建议在页面打开时添加加载进度条。

import UnityWebgl from 'unity-webgl'

const unityContext = new UnityWebgl('#canvas', {
	loaderUrl: 'path/to/unity.loader.js',
	dataUrl: 'path/to/unity.data',
	frameworkUrl: 'path/to/unity.framework.js',
	codeUrl: 'path/to/unity.code',
})

unityContext
	.on('progress', (progress) => console.log('Loaded: ', progress))
	.on('mounted', () => {
		// ⚠️ unity实例已创建，可与unity侧进行通信
		unityContext.sendMessage('GameObject', 'ReceiveRole', 'Tanya')
	})

// 供unity 端调用
unityContext.addUnityListener('gameStart', (msg) => {
	console.log('from Unity : ', msg)
})
// window.dispatchUnityEvent('gameStart', '{score: 0}')

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

	const unityContext = new UnityWebgl({
		loaderUrl: 'path/to/unity.loader.js',
		dataUrl: 'path/to/unity.data',
		frameworkUrl: 'path/to/unity.framework.js',
		codeUrl: 'path/to/unity.code',
	})

	unityContext.addUnityListener('gameStart', (msg) => {
		console.log('from Unity : ', msg)
	})
</script>

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

API

Constructor

new UnityWebgl(canvas: HTMLCanvasElement | string, config?:UnityConfig)

// or

const unityContext = new UnityWebgl(config: UnityConfig)
unityContext.create(canvas: HTMLCanvasElement | string)

• canvas : 渲染Unity的画布元素或选择器。
• config : 初始化 Unity 应用程序的配置项。

config

初始化 Unity 应用程序的配置项。

| Property | Type | Description | Required | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | -------- | | loaderUrl | string | Unity 资源加载器文件 | ✅ | | dataUrl | string | 包含资源数据和场景的文件 | ✅ | | frameworkUrl | string | 包含运行时和插件代码的文件 | ✅ | | codeUrl | string | 包含原生代码的 WebAssembly 二进制文件 | ✅ | | streamingAssetsUrl | string | 流媒体资源的 URL | 可选 | | memoryUrl | string | 生成的框架文件的 URL | 可选 | | symbolsUrl | string | 生成的 Unity 代码文件的 URL | 可选 | | companyName | string | 元数据：公司名称 | 可选 | | productName | string | 元数据：产品名称 | 可选 | | productVersion | string | 元数据：产品版本 | 可选 | | devicePixelRatio | number | 画布设备像素比率. @seedevicePixelRatio | 可选 | | matchWebGLToCanvasSize | boolean | 禁用 WebGL 画布大小自动同步. @seematchWebGLToCanvasSize | 可选 | | webglContextAttributes | object | WebGL 渲染上下文选项. @seeWebGLRenderingContext | 可选 |

Methods

Instance methods :

⭐️ create(canvas: HTMLCanvasElement | string): void;

在指定画布上创建 Unity WebGL 实例。

• canvas : canvas画布元素

await unityContext.create('#canvas')

⭐️ unload(): Promise<void>;

卸载 Unity WebGL 实例。

await unityContext.unload()

⭐️ sendMessage(objectName: string, methodName: string, value?: any): this;

向 Unity 场景中发送消息以调用公共方法。

• objectName: Unity场景中对象名称
• methodName: Unity脚本中方法名称
• value: 传递的值

unityContext.sendMessage('GameObject', 'gameStart', { role: 'Tanya' })

requestPointerLock(): void;

请求锁定 Unity 画布的指针。

takeScreenshot(dataType?: string, quality?: any): string | undefined;

对 Unity 画布进行屏幕截图并返回包含图像数据的数据 URL。

• dataType: 图像数据的类型
• quality: 图像的质量

const screenshot = unityContext.takeScreenshot('image/jpeg', 0.92)

setFullscreen(enabled: boolean): void;

切换全屏模式。

unityContext.setFullscreen(true)

Event methods :

on(name: string, listener: EventListener, options?: { once?: boolean }): this;

监听事件。

unityContext.on('progress', (progress) => {
	console.log('Progress:', progress)
})

off(name: string, listener?: EventListener): this;

移除事件监听器。

unityContext.off('progress', listener)

Unity Communication methods :

addUnityListener(name: string, listener: EventListener, options?: { once?: boolean }): this;

注册特定监听器供 Unity 端调用。

unityContext.addUnityListener('GameStarted', (level) => {
	console.log('Game started at level:', level)
})

// then call it in Unity
window.dispatchUnityEvent('GameStarted', 3)

removeUnityListener(name: string, listener?: EventListener): this;

移除注册的监听器。

unityContext.removeUnityListener('GameStarted', listener)

window.dispatchUnityEvent(name: string, ...args: any[])

在 Unity 端派发注册的监听器的方式。（在 unity 中调用 JS 的方法）

window.dispatchUnityEvent('GameStarted', 3)

Events

Unity 实例从创建到销毁过程中触发的事件。

| event name | description | | ----------------------------- | ----------------------- | | beforeMount(unityContext) | 创建 Unity 实例之前触发 | | mounted(unityContext) | 创建 Unity 实例后触发 | | beforeUnmount(unityContext) | 卸载 Unity 实例之前触发 | | unmounted() | 卸载 Unity 实例后触发 | | progress(val: number) | unity 资源加载进度更新 | | error(err: Event\|string) | 发生错误 | | debug(msg: string) | 来自 Unity 的调试消息 |

Unity-JavaScript Communication

• Unity官方文档：与浏览器脚本交互

1. Call Unity script functions from JavaScript

const unityContext = new UnityWebgl()

/**
 * @param {string} objectName name of an object in your scene.
 * @param {string} methodName public method name.
 * @param {any} value send value.
 */
unityContext.sendMessage('GameObject', 'StartGame', { role: 'Tanya' })

2. Call JavaScript functions from Unity scripts

1. 首先在 web 端通过 addUnityListener 注册供 Unity 调用的监听器。

unityContext.addUnityListener('gameStart', (level) => {
	console.log('Game started at level:', level)
})

2. 在Unity项目中，将注册的 gameStart 方法添加到项目中。

// javascript_extend.jslib
mergeInto(LibraryManager.library, {
	Hello: function () {
		window.alert('Hello, world!')
	},

	GameStart: function (level) {
		//window.alert(UTF8ToString(str));
		window.dispatchUnityEvent('gameStart', UTF8ToString(level))
	},
})

3. 在 C# 脚本中调用这些函数：

using UnityEngine;
using System.Runtime.InteropServices;

public class WebGLPluginJS : MonoBehaviour
{
    [DllImport("__Internal")]
    public static extern void Hello();

    [DllImport("__Internal")]
    public static extern void GameStart(string level);

    void Start()
    {
        Hello();
        GameStart("2");
    }
}

Issues

• 键盘输入和焦点处理
• 调试 WebGL 构建并排除故障
• WebGL 性能考虑因素

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues or questions, please file an issue on the GitHub repository.