Интеграция с React.js/Vue.js

Один из самых простых способов интегрировать сцену «Вердж3Д» в ваш проект это загрузить ее отдельно через элемент <iframe>. Но если вы хотите использовать ее непосредственно в своем приложении, то могут возникнуть некоторые трудности. Существует множество возможных конфигураций проекта со своими специфическими проблемами и особенностями. Данное руководство не может охватить их все и ориентировано только на такие популярные «Ява Скрипт»-фреймворки, как React.js и Vue.js.

В магазине ассетов «Вержд3Д» имеются готовые демки для React and Vue.js. Однако если вы хотите узнать, как сделать подобное приложение с нуля, читайте дальше.

«Вердж3Д» предлагает пример того, как сделать простой проект "Hello, world!" на React или Vue и интегрировать в него стандартное приложение «Вердж3Д». Файлы примеров находятся в папках manager/templates/Embeddable («Блендер»), manager/templates/Embeddable-Max («3дс Макс»), manager/templates/Embeddable-Maya («Майя») внутри дистрибутива «Вердж3Д».

Пример приложения «Вердж3Д» на React.js

Вот простая инструкция о том, как создать базовое приложение React.js + «Вердж3Д» с помощью утилиты Create React App. Вы можете найти копию этой инструкции в manager/templates/Embeddable/README.md внутри дистрибутива «Вердж3Д».

1) Создайте приложение React.js с помощью утилиты Create React App:


    npx create-react-app react-app-example

2) Перейдите в папку react-app-example и установите пакет verge3d:


    cd react-app-example
    npm i verge3d

3) Скопируйте в приложение следующие файлы из дистрибутива «Вердж3Д»:

содержимое папки manager/templates/Embeddable/public в react-app-example/public
содержимое папки manager/templates/Embeddable/src в react-app-example/src

или воспользуйтесь командами ниже:

Линукс / Мак ОС / Хром ОС

V3D_PATH и MY_PATH это папка дистрибутива «Вердж3Д» и папка приложения соответственно.


    V3D_PATH=/path/to/v3d/distribution
    MY_PATH=/path/to/my/react/app
    cp -r $V3D_PATH/manager/templates/Embeddable/public/* $MY_PATH/public/
    cp -r $V3D_PATH/manager/templates/Embeddable/src/* $MY_PATH/src/

Виндоус (PowerShell)

V3D_PATH и MY_PATH это папка дистрибутива «Вердж3Д» и папка приложения соответственно.


    $V3D_PATH = "path\to\v3d\distribution"
    $MY_PATH = "path\to\my\react\app"
    Copy-Item -Path "$V3D_PATH\manager\templates\Embeddable\public\*" -Destination "$MY_PATH\public" -Recurse
    Copy-Item -Path "$V3D_PATH\manager\templates\Embeddable\src\*" -Destination "$MY_PATH\src" -Recurse

4) Создайте файл react-app-example/src/V3DApp.js со следующем содержимым:


    import React from 'react';

    import { createApp } from './v3dApp/app';
    import './v3dApp/app.css';

    class V3DApp extends React.Component {
      #app = null;
      #PL = null;

      #uuid = window.crypto.randomUUID();
      #containerId = `v3d-container-${this.#uuid}`;
      #fsButtonId = `fullscreen-button-${this.#uuid}`;
      #sceneURL = 'v3dApp/app.gltf';

      async loadApp() {
        ({ app: this.#app, PL: this.#PL } = await createApp({
          containerId: this.#containerId,
          fsButtonId: this.#fsButtonId,
          sceneURL: this.#sceneURL,
        }));
      }

      disposeApp() {
        this.#app?.dispose();
        this.#app = null;

        // dispose Puzzles' visual logic
        this.#PL?.dispose();
        this.#PL = null;
      }

      reloadApp() {
        this.disposeApp();
        this.loadApp();
      }

      componentDidMount() {
        this.loadApp();
      }

      componentWillUnmount() {
        this.disposeApp();
      }

      render() {
        return <div id={this.#containerId}>
          <div
            id={this.#fsButtonId}
            className="fullscreen-button fullscreen-open"
            title="Toggle fullscreen mode"
          ></div>
        </div>;
      }
    }

    export default V3DApp;

5) Замените содержимое файла react-app-example/src/index.js следующим кодом:


    import React from 'react';
    import ReactDOM from 'react-dom/client';

    import V3DApp from './V3DApp';

    const root = ReactDOM.createRoot(document.getElementById('root'));
    root.render(<V3DApp/>);

6) Запустите сервер разработки, выполнив следующую команду в директории react-app-example:


    npm start

Приложение будет доступно по адресу http://localhost:3000/.

Пример приложения «Вердж3Д» на Vue.js

Вот простая инструкция о том, как создать базовое приложение Vue.js + «Вердж3Д» с помощью утилиты Vue CLI. Вы можете найти копию этой инструкцию в manager/templates/Embeddable/README.md внутри дистрибутива «Вердж3Д».

1) Создайте приложение Vue.js с помощью утилиты Vite:


    npm create vite@latest vue-app-example -- --template vue

2) Перейдите в папку vue-app-example и установите пакет verge3d:


    cd vue-app-example
    npm i verge3d

3) Скопируйте в приложение следующие файлы из дистрибутива «Вердж3Д»:

содержимое папки manager/templates/Embeddable/public в vue-app-example/public
содержимое папки manager/templates/Embeddable/src в vue-app-example/src

или воспользуйтесь командами ниже:

Линукс / Мак ОС / Хром ОС

V3D_PATH и MY_PATH это папка дистрибутива «Вердж3Д» и папка приложения соответственно.


    V3D_PATH=/path/to/v3d/distribution
    MY_PATH=/path/to/my/vue/app
    cp -r $V3D_PATH/manager/templates/Embeddable/public/* $MY_PATH/public/
    cp -r $V3D_PATH/manager/templates/Embeddable/src/* $MY_PATH/src/

Виндоус (PowerShell)

V3D_PATH и MY_PATH это папка дистрибутива «Вердж3Д» и папка приложения соответственно.


    $V3D_PATH = "path\to\v3d\distribution"
    $MY_PATH = "path\to\my\vue\app"
    Copy-Item -Path "$V3D_PATH\manager\templates\Embeddable\public\*" -Destination "$MY_PATH\public" -Recurse
    Copy-Item -Path "$V3D_PATH\manager\templates\Embeddable\src\*" -Destination "$MY_PATH\src" -Recurse

4) Создайте файл vue-app-example/src/components/V3DApp.vue, содержащий следующий код:


    <template>
      <div :id="containerId">
        <div
          :id="fsButtonId"
          class="fullscreen-button fullscreen-open"
          title="Toggle fullscreen mode"
        ></div>
      </div>
    </template>

    <script>
    import { createApp } from '../v3dApp/app';

    export default {
      name: 'V3DApp',

      created() {
        this.app = null;
        this.PL = null,

        this.uuid = window.crypto.randomUUID();
        this.containerId = `v3d-container-${this.uuid}`;
        this.fsButtonId = `fullscreen-button-${this.uuid}`;
        this.sceneURL = 'v3dApp/app.gltf';

        this.loadApp = async function() {
          ({ app: this.app, PL: this.PL } = await createApp({
            containerId: this.containerId,
            fsButtonId: this.fsButtonId,
            sceneURL: this.sceneURL,
          }));
        }

        this.disposeApp = function() {
          this.app?.dispose();
          this.app = null;

          // dispose Puzzles' visual logic
          this.PL?.dispose();
          this.PL = null;
        }

        this.reloadApp = function() {
          this.disposeApp();
          this.loadApp();
        }
      },

      mounted() {
        this.loadApp();
      },

      beforeUnmount() {
        this.disposeApp();
      },
    }
    </script>

    <style>
    @import '../v3dApp/app.css';
    </style>


    <template>
      <div :id="containerId">
        <div
          :id="fsButtonId"
          class="fullscreen-button fullscreen-open"
          title="Toggle fullscreen mode"
        ></div>
      </div>
    </template>

    <script>
    import { createApp } from '../v3dApp/app';

    export default {
      name: 'V3DApp',

      created() {
        this.app = null;
        this.PL = null,

        this.uuid = window.crypto.randomUUID();
        this.containerId = `v3d-container-${this.uuid}`;
        this.fsButtonId = `fullscreen-button-${this.uuid}`;
        this.sceneURL = 'v3dApp/app.gltf';

        this.loadApp = async function() {
          ({ app: this.app, PL: this.PL } = await createApp({
            containerId: this.containerId,
            fsButtonId: this.fsButtonId,
            sceneURL: this.sceneURL,
          }));
        }

        this.disposeApp = function() {
          this.app?.dispose();
          this.app = null;

          // dispose Puzzles' visual logic
          this.PL?.dispose();
          this.PL = null;
        }

        this.reloadApp = function() {
          this.disposeApp();
          this.loadApp();
        }
      },

      mounted() {
        this.loadApp();
      },

      beforeDestroy() {
        this.disposeApp();
      },
    }
    </script>

    <style>
    @import '../v3dApp/app.css';
    </style>

5) Замените vue-app-example/src/App.vue так, чтобы он выглядел следующим образом:


    <template>
      <V3DApp></V3DApp>
    </template>

    <script>
    import V3DApp from './components/V3DApp.vue';

    export default {
      name: 'App',
      components: {
        V3DApp,
      },
    }
    </script>

6) Запустите сервер разработки, выполнив следующую команду в каталоге vue-app-example:


    npm run dev

Приложение должно быть доступно по адресу http://localhost:5173/.

Использование редактора пазлов

Нет прямой интеграции между React/Vue и редактором пазлов/ диспетчером приложений. Тем не менее, вы по-прежнему можете использовать пазлы для добавления сценариев поведения в ваши React/Vue-приложения. В этом разделе объясняется, как это сделать и каковы ограничения данного подхода.

Настройка диспетчера приложений

Предположим, у нас есть приложение React или Vue, созданное в соответствии с руководством, описанным в этом справочнике. Для того чтобы "соединить" App Manager и проект React/Vue, нам необходимо скопировать специальное приложение-адаптер adapter из папки "Embeddable" с шаблоном приложения в ваш проект на React/Vue. Кроме того, вам потребуется скопировать рантайм «Вердж3Д» v3d.js в папку adapter.


    cp -rv manager/template/Embeddable/adapter /path/to/my_awesome_app
    cp build/v3d.js /path/to/my_awesome_app/adapter

Теперь вы можете видеть свой проект в диспетчере приложений и использовать редактор пазлов.

Loading Resources in Puzzles

Пазлы replace texture, load scene, load sound, load video, load data, и др. требуют указания УРЛ-адреса с загружаемым ресурсам (текстурам, звукам и т.д.).

При использовании редактора пазла для разработки React/Vue-приложений все пути для данных пазлов рассчитываются относительно корня приложения, который обычно начинается с папки приложения public. Если редактор пазлов используется так как это описано выше, то он имеет доступ только к папке приложения public/v3dApp.

В частности, если нам нужно загрузить звук с помощью пазлов, этот файл, назовём его sound.mp3, должен быть размещён в папке public/v3dApp (или какой-либо его подпапке). После этого он может быть загружен по пути v3dApp/mySound.mp3, который и должен быть указан как УРЛ в пазле load sound: