브라우저 스크립팅과 상호작용

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 doesn’t 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.

Unity 스트립트에서 JavaScript 함수 호출

The recommended way of using 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 in the Assets folder > Plugins subfolder. The plugin file needs to have a syntax like this:

mergeInto(LibraryManager.library, {

  Hello: function () {
    window.alert("Hello, world!");
  },

  HelloString: function (str) {
    window.alert(UTF8ToString(str));
  },

  PrintFloatArray: function (array, size) {
    for(var i = 0; i < size; i++)
    console.log(HEAPF32[(array >> 2) + i]);
  },

  AddNumbers: function (x, y) {
    return x + y;
  },

  StringReturnValueFunction: function () {
    var returnStr = "bla";
    var bufferSize = lengthBytesUTF8(returnStr) + 1;
    var buffer = _malloc(bufferSize);
    stringToUTF8(returnStr, buffer, bufferSize);
    return buffer;
  },

  BindWebGLTexture: function (texture) {
    GLctx.bindTexture(GLctx.TEXTURE_2D, GL.textures[texture]);
  },

});

그러면 다음과 같이 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(1, 1, TextureFormat.ARGB32, false);
        BindWebGLTexture(texture.GetNativeTexturePtr());
    }
}

세부 사항:

• 단순 숫자 타입은 전환하지 않고도 함수 파라미터의 JavaScript에 전달할 수 있습니다.다른 데이터 타입은 JavaScript에 있는 큰 배열일 뿐인 emscripten 힙에서 포인터로서 전달할 수 있습니다.
• 문자열의 UTF8ToString 헬퍼 함수를 사용하여 JavaScript 문자열로 전환할 수 있습니다.
• 문자열 값을 반환하려면 _malloc를 호출하여 일부 메모리를 할당하고 stringToUTF8 헬퍼 함수를 호출하여 JavaScript 문자열을 작성해야 합니다.문자열이 반환 값인 경우 IL2CPP 런타임이 가용 메모리를 늘리는 작업을 자동으로 처리합니다.
• 프리미티브 타입 배열의 경우 emscripten은 다음과 같은 여러 정수 크기, 서명되지 않은 정수 또는 부동 소수점 메모리 표현에 대해 각기 다른 ArrayBufferViews를 힙에 제공합니다.HEAP8, HEAPU8, HEAP16, HEAPU16, HEAP32, HEAPU32, HEAPF32, HEAPF64
• WebGL에서 텍스처에 액세스하기 위해 emscripten은 Unity의 기본 텍스처 ID를 WebGL 텍스처 오브젝트에 매핑하는 GL.textures 배열을 제공합니다.WebGL 함수는 emscripten의 WebGL 컨텍스트인 GLctx에서 호출할 수 있습니다.

JavaScript와 인터랙션하는 방법에 대한 자세한 내용은 emscripten 문서를 참조하십시오.

In addition, there are several plugins in the Unity installation folder that you can use as reference: PlaybackEngines/WebGLSupport/BuildTools/lib and PlaybackEngines/WebGLSupport/BuildTools/Emscripten/src/library*.

코드 가시성

권장하는 접근 방식은 모든 빌드 코드를 자체 범위에서 실행하는 것입니다.이렇게 하면 내장한 페이지 코드와 충돌을 일으키지 않고도 임의 페이지에 콘텐츠를 내장할 수 있으며, 동일한 페이지에 두 개 이상의 빌드를 내장할 수 있습니다.

모든 JavaScript 코드가 .jslib 플러그인 형태로 프로젝트 안에 있는 경우 이 JavaScript 코드는 컴파일된 빌드와 같은 스코프 안에서 실행되고, 코드는 이전 Unity 버전과 동일한 방법으로 작동합니다. 예를 들어 Module, SendMessage, HEAP8, ccall 등과 같은 오브젝트와 함수는 JavaScript 플러그인 코드에서 직접 볼 수 있습니다.

However, if you are planning to call the internal JavaScript functions from the global scope of the embedding page, you must use the unityInstance variable in your WebGL Template index.html. Do this after the Unity engine instantiation succeeds, for example:

  var myGameInstance = null;
    script.onload = () => {
      createUnityInstance(canvas, config, (progress) => {...}).then((unityInstance) => {
        myGameInstance = unityInstance;
        …

Then, you can send a message to the build using myGameInstance.SendMessage(), or access the build Module object using myGameInstance.Module.

JavaScript에서 Unity 스크립트 함수 호출

The recommended way of sending data or notification to the Unity script from the browser’s JavaScript is to call methods on GameObjects in your content. If you are making the call from a JavaScript plugin, embedded in your project, you can use the following code:

MyGameInstance.SendMessage(objectName, methodName, value);

여기에서 objectName 은 씬에 있는 오브젝트의 이름이고, methodName 은 해당 오브젝트에 현재 연결된 스크립트에 있는 메서드의 이름이고, value 는 문자열 또는 숫자이거나 비어 있을 수 있습니다. 예:

MyGameInstance.SendMessage('MyGameObject', 'MyFunction');
MyGameInstance.SendMessage('MyGameObject', 'MyFunction', 5);

MyGameInstance.SendMessage('MyGameObject', 'MyFunction', 'MyString');

If you would like to make a call from the global scope of the embedding page, see the Code Visibility section.

Unity 스트립트에서 C 함수 호출

Unity compiles your sources into JavaScript from C/C++ code using emscripten, so you can also write plugins in C/C++ code, and call these functions from C#. Therefore, instead of the .jslib file in the example above, you could have a C/C++ file in your project, which is automatically get compiled with your scripts, and you can call functions from it, just like in the JavaScript example above.

If you are using C++ (.cpp) to implement the plugin, then you must ensure the functions are declared with C linkage to avoid name mangling issues:

# include <stdio.h>

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

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

참고:Unity는 Emscripten 버전 2.0.19 툴체인을 사용하고 있습니다.

---

• 2021.2 이상에서 Pointer__stringify()를 UTF8ToString으로 교체함

• 2020.1에서 unity.Instance가 createUnityInstance로 대체됨

• 코드 예제에서 오류 수정

• 2019.1에서 WebGL 인스턴스의 이름이 gameInstance에서 unityInstance로 변경됨