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

웹용 콘텐츠를 빌드할 때 웹 페이지의 다른 요소와 커뮤니케이션을 수행해야 할 수 있습니다. 또는 Unity가 기본적으로 노출하지 않는 웹 API를 사용하여 기능을 구현하고자 할 수도 있습니다. 두 경우 모두 브라우저의 JavaScript 엔진과 직접 연결해야 합니다. Unity 웹은 이를 위한 다양한 방법을 제공합니다.

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

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

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 배열을 제공합니다. Emscripten의 WebGL 컨텍스트인 GLctx에서 WebGL 함수를 호출할 수 있습니다.

JavaScript와 상호 작용하는 방법에 대한 자세한 내용은 Emscripten 기술 자료를 참조하십시오.

Unity 설치 폴더에는 참조할 수 있는 여러 플러그인이 있습니다. PlaybackEngines/WebGLSupport/BuildTools/lib 및 PlaybackEngines/WebGLSupport/BuildTools/Emscripten/src/library*가 있습니다.

코드 가시성

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

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

그러나 포함하는 페이지의 전역 범위에서 내부 JavaScript 함수를 호출하려는 경우 웹 템플릿 index.html에서 unityInstance 변수를 사용해야 합니다. 예를 들어 Unity 엔진 인스턴스화가 성공한 경우 다음을 수행합니다.

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

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

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

브라우저의 JavaScript에서 Unity 스크립트로 데이터 또는 알림을 전송하는 데 권장되는 방법은 콘텐츠의 게임 오브젝트에서 메서드를 호출하는 것입니다. 프로젝트에 포함된 JavaScript 플러그인에서 호출하는 경우 다음 코드를 사용할 수 있습니다.

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++ 파일이 프로젝트에 포함될 수 있습니다. 이 파일은 자동으로 스크립트로 컴파일되고 이 파일에서 함수를 호출할 수 있습니다.

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;
}

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