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

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 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.

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

브라우저 JavaScript를 프로젝트에 사용하려면 JavaScript 소스를 프로젝트에 추가한 다음 해당 함수를 스크립트 코드에서 직접 호출하는 방법이 권장됩니다. 이렇게 하려면 JavaScript 코드를 통해 .jslib 확장자를 사용하여 파일을 Assets 폴더의 “Plugins” 하위폴더에 저장해야 합니다. 플러그인 파일에는 다음과 같은 구문이 있어야 합니다.

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(0, 0, TextureFormat.ARGB32, false);
        BindWebGLTexture(texture.GetNativeTexturePtr());
    }
}

• You can pass simple numeric types to JavaScript in function parameters without doing any conversion. You can pass other data types as a pointer in the emscripten heap which is just a big array in JavaScript.
• For strings, you can use the UTF8ToString helper function to convert to a JavaScript string.
• To return a string value, call _malloc to allocate some memory and the stringToUTF8 helper function to write a JavaScript string to it. If the string is a return value, then the IL2CPP runtime automatically frees up the memory for you.
• For arrays of primitive types, emscripten provides different ArrayBufferViews into its 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. You can call WebGL functions on emscripten’s WebGL context, GLctx.

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

또한 Unity 설치 폴더에는 PlaybackEngines/WebGLSupport/BuildTools/lib 및 PlaybackEngines/WebGLSupport/BuildTools/Emscripten/src/library*에서 레퍼런스로 사용할 수 있는 여러 개의 플러그인이 있습니다.

코드 가시성

The recommended approach is to execute all the build code in its own scope. This allows you to embed your content on an arbitrary page without causing conflicts with the embedding page code, and lets you embed more than one build on the same page.

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

하지만 임베딩 페이지의 전역 범위에서 내부 JavaScript 함수를 호출하려는 경우 WebGL 템플릿 index.html에서 unityInstance 변수를 사용해야 합니다. Unity 엔진 인스턴스화가 성공한 후 이 작업을 수행하십시오. 예를 들면 다음과 같습니다.

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

그러면 myGameInstance.SendMessage()를 사용하여 메시지를 빌드로 전송하거나 myGameInstance.Module을 사용하여 빌드 모듈 오브젝트에 액세스할 수 있습니다.

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

Sometimes you need to send some data or notification to the Unity script from the browser’s JavaScript. The recommended way of doing it’s 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');

임베딩 페이지의 전역 스코프에서 호출하려면 아래의 코드 가시성 섹션을 참조하십시오.

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

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

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

# include <stdio.h>

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

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

Note: Unity is using the Emscripten version 2.0.19 toolchain.

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

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

• 코드 예제에서 오류 수정

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