WebGL: Interacting with browser scripting

When building content for the web, you might need to communicate with other elements on your web page. Or you might want to implement functionality using Web APIs which Unity does not currently expose by default. In both cases, you need to directly interface with the browser’s JavaScript engine. Unity WebGL provides different methods to do this.

Calling between JavaScript code from Unity

The first is the same as for the Web Player. You can use the Application.ExternalCall() and Application.ExternalEval() functions to invoke JavaScript code on the embedding web page. To call methods on GameObjects in your content from browser JavaScript, you can use the following code:

SendMessage ('MyGameObject', 'MyFunction', 'foobar');

Calling JavaScript functions from a plugin

The other way to use browser JavaScript in your project is to add your JavaScript sources to your project, and then call those functions directly from your script code. To do so, place files with JavaScript code using the .jslib extension (as the normal .js would be picked up by the UnityScript compiler) into a “Plugins/WebGL” folder in your Assets folder. The file needs to have a syntax like this:

Assets/Plugins/WebGL/MyPlugin.jslib

var MyPlugin = {
    Hello: function()
    {
        window.alert("Hello, world!");
    },
    HelloString: function(str)
    {
        window.alert(Pointer_stringify(str));
    },
    PrintFloatArray: function(array, size)
    {
        for(var i=0;i<size;i++)
            console.log(HEAPF32[(array>>2)+size]);
    },
    AddNumbers: function(x,y)
    {
        return x + y;
    },
    StringReturnValueFunction: function()
    {
        var returnStr = "bla";
        var buffer = _malloc(lengthBytesUTF8(returnStr) + 1);
        writeStringToMemory(returnStr, buffer);
        return buffer;
    },
    BindWebGLTexture: function(texture)
    {
        GLctx.bindTexture(GLctx.TEXTURE_2D, GL.textures[texture]);
    }
};

mergeInto(LibraryManager.library, MyPlugin);

그러면 다음과 같이 C# 스크립트에서 이러한 함수를 호출할 수 있습니다.

using UnityEngine;
using System.Runtime.InteropServices;

public class NewBehaviourScript : MonoBehaviour {

    [DllImport("__Internal")]
    private static extern void Hello();

    [DllImport("__Internal")]
    private static extern void HelloString(string str);

    [DllImport("__Internal")]
    private static extern void PrintFloatArray(float[] array, int size);

    [DllImport("__Internal")]
    private static extern int AddNumbers(int x, int y);

    [DllImport("__Internal")]
    private static extern string StringReturnValueFunction();

    [DllImport("__Internal")]
    private static extern void BindWebGLTexture(int texture);

    void Start() {
        Hello();
        
        HelloString("This is a string.");
        
        float[] myArray = new float[10];
        PrintFloatArray(myArray, myArray.Length);
        
        int result = AddNumbers(5, 7);
        Debug.Log(result);
        
        Debug.Log(StringReturnValueFunction());
        
        var texture = new Texture2D(0, 0, TextureFormat.ARGB32, false);
        BindWebGLTexture(texture.GetNativeTextureID());
    }
}

Simple numeric types can be passed to JavaScript in function parameters without requiring any conversion. Other data types will be passed as a pointer in the emscripten heap (which is really just a big array in JavaScript). For strings, you can use the Pointer_stringify helper function to convert to a JavaScript string. To return a string value you need to call malloc_ to allocate some memory and the writeStringToMemory__ helper function to write a JavaScript string to it. If the string is a return value, then the il2cpp runtime will take care of freeing the memory for you. For arrays of primitive types, emscripten provides different ArrayBufferViews into it’s heap for different sizes of integer, unsigned integer or floating point representations of memory: HEAP8, HEAPU8, HEAP16, HEAPU16, HEAP32, HEAPU32, HEAPF32, HEAPF64. To access a texture in WebGL, emscripten provides the GL.textures array which maps native texture IDs from Unity to WebGL texture objects. WebGL functions can be called on emscripten’s WebGL context, GLctx.

Calling C++ functions from a plugin

Unity 에디터는 emscripten을 사용하여 C++ 코드에서 JavaScript로 소스를 컴파일하기 때문에 C 또는 C++ 코드로 플러그인을 작성하고 C#에서 함수를 호출할 수 있습니다. 따라서 위 예의 jslib 파일 대신 아래와 같은 C 파일이 프로젝트에 포함될 수 있습니다. 이 파일은 자동으로 스크립트로 컴파일되고 위의 JavaScript 예처럼 이 파일에서 함수를 호출할 수 있습니다.

C++(.cpp)로 플러그인을 구현하는 경우 이름 맹글링 문제를 방지하기 위해 함수가 C 링크로 선언되도록 해야 합니다.

Assets/Plugins/WebGL/MyPlugin.c

#include <stdio.h>

void Hello ()
{
    printf("Hello, world!\n");
}

int AddNumbers (int x, int y)
{
    return x + y;
}

Customizing Compatibility Checks or Error handlers

Unity will write some JavaScript code to builds by default, which will check platform compatibility and handles errors. This code will display warning messages when running on unsupported platforms, like when trying to run Unity WebGL content on mobile devices. It will also parse error and exception strings from the browser, to check for known errors and display error dialogs with more comprehensive error messages.

You can customize this handling, for instance, if you want to suppress the warning messages when running on mobile devices. To do so, open the generated index.html, and replace this code with actual JavaScript function implementations for errorhandler and/or compatibilitycheck:

  var Module = {
    TOTAL_MEMORY: 268435456,
    errorhandler: null,
    compatibilitycheck: null,
  };

The compatibilitycheck function will just be called at startup, and you can put any code in here to show messages when you detect that the content is not supported.

The errorhandler function will be called when the page invokes its window.onerror event handler, and uses the same parameters. Return “true” from this function to resume execution, and “false” to pass the error to Unity’s default error handler.

예:

  var Module = {
    TOTAL_MEMORY: 268435456,
    errorhandler: function(err, url, line) {
        alert("error " + err + " occurred at line " + line);

        // return true so Unity's error handler is not executed.
        return true;
    },
    compatibilitycheck: function() {
        // check compatibility ...
    }
  };