Как интегрировать приложение Вердж3Д в проект React.js/Vue.js — Софт Эйт Софт

# Интеграция с 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
- Пример приложения «Вердж3Д» на Vue.js
- Использование редактора пазлов

#

## Пример приложения «Вердж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, содержащий следующий код:

Vue 3 `<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>` Vue 2 `<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: