WebGL: взаимодействие со скриптами браузера

Unity · Версия 2020.3 LTS · Manual

WebGL: взаимодействие со скриптами браузера

При создании контента для Интернета вам может понадобиться взаимодействовать с другими элементами на вашей веб-странице. Или вы можете захотеть реализовать функциональность с помощью веб-API, которые Unity в настоящее время не предоставляет по умолчанию. В обоих случаях вам необходимо напрямую взаимодействовать с движком JavaScript браузера. Unity WebGLJavaScript API, который отображает 2D- и 3D-графику в веб-браузере. Вариант сборки Unity WebGL позволяет Unity публиковать контент в виде программ JavaScript, использующих технологии HTML5 и API рендеринга WebGL для запуска контента Unity в веб-браузере. Подробнее
См. в Словарь
предлагает различные способы сделать это.

Вызов функций JavaScript из сценариев Unity

Рекомендуемый способ использования браузерного JavaScript в вашем проекте – добавить в проект исходные коды JavaScript, а затем вызвать эти функции непосредственно из кода скрипта. Для этого поместите файлы с кодом JavaScript с расширением .jslib в подпапку «Плагины» в папке «Активы». Файл плагина должен иметь такой синтаксис:

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

Простые числовые типы можно передавать в JavaScript в параметрах функции без необходимости преобразования. Другие типы данных передаются как указатель в куче emscripten (которая в JavaScript представляет собой просто большой массив). Для строк можно использовать вспомогательную функцию UTF8ToString для преобразования в строку JavaScript. Чтобы вернуть строковое значение, вам нужно вызвать _malloc, чтобы выделить немного памяти, и вспомогательную функцию stringToUTF8, чтобы записать в нее строку JavaScript. . Если строка является возвращаемым значением, то il2cppразработанный Unity сервер сценариев, который можно использовать в качестве альтернативы Mono при сборке проектов для некоторых платформ. Подробнее
См. Словарь
. Среда выполнения позаботится об освобождении памяти за вас. Для массивов примитивных типов emscripten предоставляет различные ArrayBufferView в свою кучу для различных размеров целочисленных, целочисленных без знака или представлений с плавающей запятой память: HEAP8, HEAPU8, HEAP16, HEAPU16, HEAP32, HEAPU32, HEAPF32, HEAPF64. Чтобы получить доступ к текстуре в WebGL, emscripten предоставляет массив GL.textures, который сопоставляет собственные идентификаторы текстур из Unity с объектами текстуры WebGL. Функции WebGL можно вызывать в контексте WebGL emscripten, GLctx.

Для получения дополнительной информации о том, как взаимодействовать с JavaScript, см. документация по emscripten (откроется другой сайт).

Кроме того, обратите внимание, что в папке установки Unity есть несколько подключаемых модулей, которые вы можете использовать в качестве справки, в PlaybackEngines/WebGLSupport/BuildTools/lib и PlaybackEngines/WebGLSupport/BuildTools/Emscripten/src/library*.

Видимость кода

Начиная с Unity 5.6 весь код сборки выполняется в своей области. Этот подход позволяет встроить ваш контент на произвольную страницу, не вызывая конфликтов с кодом встраиваемой страницы, и позволяет встроить более одной сборки на одну и ту же страницу.

Если у вас есть весь ваш код JavaScript в виде плагинов .jslib внутри вашего проекта, тогда этот код JavaScript будет выполняться в той же области видимости, что и скомпилированная сборка, и ваш код должен работать так же. как и в предыдущих версиях Unity. Например, следующие объекты и функции должны быть непосредственно видны из кода подключаемого модуля JavaScript: Module, SendMessage, HEAP8, ccall и т. д..

Однако, если вы планируете вызывать внутренние функции JavaScript из глобальной области действия страницы встраивания, вы должны использовать переменную unityInstance в индексе вашего шаблона WebGL. Сделайте это после успешного создания экземпляра движка Unity, например:

  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.

Вызов функций сценариев Unity из JavaScript

Иногда вам нужно отправить некоторые данные или уведомление в сценарий Unity из JavaScript браузера. Рекомендуемый способ сделать это — вызвать методы для GameObjectsосновного объекта в сценах Unity, который может представлять персонажей, реквизит, декорации. , камеры, путевые точки и многое другое. Функциональность GameObject определяется прикрепленными к нему компонентами. Подробнее
См. Словарь
в вашем контенте. Если вы выполняете вызов из подключаемого модуля JavaScript, встроенного в ваш проект, вы можете использовать следующий код:

MyGameInstance.SendMessage(objectName, methodName, value);

Где objectName — имя объекта в вашей сцене; methodName — это имя метода в скрипте, который в данный момент присоединен к этому объекту; значение может быть строкой, числом или может быть пустым. Например:

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

Вызов функций C из скриптов Unity

Unity компилирует ваши исходные коды в JavaScript из кода C/C++ с помощью emscripten, поэтому вы также можете писать плагины в коде C/C++ и вызывать эти функции из C#. Таким образом, вместо файла jslib в приведенном выше примере у вас может быть файл C/C++ в вашем проекте — он автоматически скомпилируется с вашими скриптами, и вы сможете вызывать из него функции, как в приведенном выше примере JavaScript.< /p>

Если вы используете C++ (.cpp) для реализации подключаемого модуля, вы должны убедиться, что функции объявлены со связью C, чтобы избежать проблем с искажением имен:

#include 

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

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

  • Pointer__stringify() заменен на UTF8ToString в 2021.2 и более поздних версиях
  • unity.Instance заменен на createUnityInstance в 2020.1
  • Исправлена ошибка в примере кода.
  • Экземпляр WebGL переименован из gameInstance в unityInstance в 2019.1

Обновлено 17 ноября 2026 г.