nuxt-unity-webgl

nuxt-unity-webgl introduces component and utilities for unity WebGL container.

Features

• ⛰  Add the unity canvas to your site easily

Quick Setup

1. Add nuxt-unity-webgl dependency to your project

# Using pnpm
pnpm add -D nuxt-unity-webgl

# Using yarn
yarn add --dev nuxt-unity-webgl

# Using npm
npm install --save-dev nuxt-unity-webgl

2. Add nuxt-unity-webgl to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-unity-webgl'],
})

That's it! You can now use NuxtUnityWebGL in your Nuxt app ✨

Basic usage

You can get NuxtUnity by calling useNuxtUnityOrThrow() or useNuxtUnity() composables.

<script lang="ts" setup>
useProvideNuxtUnity(undefined, (unity) => {
  // eslint-disable-next-line no-console
  console.log(unity)
})
const { NuxtUnity, loaded, SendMessage } = useNuxtUnityOrThrow()
const callUnityFunction = () => {
  // scalar or json object are enable as argument
  SendMessage('GameObject', 'HelloMethod', { message: 'hello' })
}
const nuxtApp = useNuxtApp()

nuxtApp.$nuxtUnityEvent('nuxt-unity:ready').on(({ providerId, unityInstance }) => {
  // eslint-disable-next-line no-console
  console.log(providerId, unityInstance)
})
</script>

<template>
  <div class="container">
    <NuxtUnity
      width="500px"
      height="500px"
      unity-loader="/unity/Build.loader.js"
      :config="{
        dataUrl: '/unity/Build.data',
        frameworkUrl: '/unity/Build.framework.js',
        codeUrl: '/unity/Build.wasm',
      }"
      :resizable="true"
      :refresh-delay-time="100"
    ></NuxtUnity>
  </div>
  <button @click="callUnityFunction">SendMessage</button>
</template>

And you can send messages to the unity game object with SendMessage().

// HelloController.cs
using System;
using UnityEngine;
using System.Runtime.InteropServices;

public class HelloController : MonoBehaviour
{
    [DllImport("__Internal")]
    private static extern void JSLibFunction();

    [Serializable]
    public class HelloProps
    {
        public string message;
    }

    public void hello(string json)
    {
        HelloProps props = JsonUtility.FromJson<HelloProps>(json);
        Debug.Log(props.message);
        JSLibFunction();
    }
}

emit or handle some events via $nuxtUnityEvent in .jslib.

// Sample.jslib
mergeInto(LibraryManager.library, {
  JSLibFunction: function () {
    $nuxtUnityEvent.emit({ event: 'hello', data: { message: 'Hello from unity jslib' } })
  },
})

Composables

useProvideNuxtUnity(initialValue, callback)

Injects unity store.

// initialValue: unity instance
// callback    : (unityInstance) => void
useProvideNuxtUnity(undefined, (unity) => {
  console.log(unity) // The unity instance
})

useNuxtUnity()

Return the store, it is nullable. We uses createInjectionState of VueUse, so see VueUse Documents in more details.

• NuxtUnity - NuxtUnity vue component
• unity - Unity instance initialized by createUnityInstance()
• loading - Loading state of the unity instance
• loaded - Loaded state of the unity instance
• quitted - Quitted state of the unity instance
• quit - Function to quit unity
• error - Error if unity loading fails
• SendMessage - Utility function to send the unity game object

useNuxtUnityOrThrow()

Return the store. If the store is null, error thrown.

Unity Component Attributes

width

• Type: string
• Required: true

Canvas width px.

height

• Type: string
• Required: true

Canvas height px.

unityLoader

• Type: string
• Required: true

Unity loader script.

config

• Type: Object
• Required: true

Configuration passed to an utity instance.

onProgress

• Type: Function
• Required: false
• Default:

;(progress: number) => {
  console.log(`unity loading... ${progress * 100}%`)
}

Callback function called in loading.

resizable

• Type: Boolean
• Required: false

Enable auto resizing canvas when window resizing. true is enable.

refreshDelayTime

• Type: Number
• Required: false
• Default: 200

Delay millseconds time to resize canvas after window resized.

onQuit

• Type: Boolean
• Required: false
• Default:

;() => {
  console.log('quit unity')
}

Callback function called on onBeforeUnmount lifecycle hook.

Plugin

You can use $nuxtUnityEvent plugin in your components or unity .jslib scripts.

const { $nuxtUnityEvent } = useNuxtApp()
$nuxtUnityEvent('eventName').on(({ event }) => console.log(event))
$nuxtUnityEvent('eventName').emit({ event: 'hello', data: { message: 'message' } })

• $nuxtUnityEvent - eventmit object
  • nuxt-unity:ready - Hook called when unity instance created
  • nuxt-unity:quit - Hook called when unity instance quitted

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release