Integration with React.js/Vue.js

One of the easiest way of integrating a Verge3D scene into your project is to load it separately through an iframe HTML element. But if you want to use it directly inside your app then there could appear some difficulties along the way. However, there are plenty of possible project configurations with their specific issues and peculiarities. This guide can't comprehend them all and only targets such popular JavaScript frameworks as React.js and Vue.js.

There are simple React and Vue.js demos available in the Verge3D Asset Store: React-V3D-App, Vue-V3D-App. If you want to check out how to create a React/Vue.js + Verge3D app from scratch follow the guide below.

Verge3D provides an example of how to make a simple "Hello, world!" React or Vue project and integrate a standard Verge3D application into it. The example files are located in the manager/templates/Embeddable directory inside the Verge3D distribution.

Verge3D React.js Application Example

Here's a simple instruction on how to create a basic React.js + Verge3D application with the Create React App utility. You can find a copy of this instruction in manager/templates/Embeddable/README.md inside the Verge3D distribution.

1) Create a React.js application via the Create React App utility: npx create-react-app react-app-example

2) Copy the following files from Verge3D distribution into your app:

or use the commands below:

Change V3D_PATH and MY_PATH to where the Verge3D distribution and your React application are located respectively. 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/ cp $V3D_PATH/build/v3d.js $MY_PATH/public/
Change V3D_PATH and MY_PATH to where the Verge3D distribution and your React application are located respectively. $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 Copy-Item "$V3D_PATH\build\v3d.js" -Destination "$MY_PATH\public"

3) Add the following script tag into react-app-example/public/index.html: <script src="%PUBLIC_URL%/v3d.js"></script>

4) Create a file called react-app-example/src/V3DApp.js with the following content: 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'; #logicURL = 'v3dApp/visual_logic.js'; async loadApp() { ({ app: this.#app, PL: this.#PL } = await createApp({ containerId: this.#containerId, fsButtonId: this.#fsButtonId, sceneURL: this.#sceneURL, logicURL: this.#logicURL, })); } 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) Replace the contents of react-app-example/src/index.js with the following code: 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) Run the development server by executing the following command in the react-app-example directory: npm start By default the application now should be available at http://localhost:3000/.

Verge3D Vue.js Application Example

Here's a simple instruction on how to create a basic Vue.js + Verge3D application with the Vue CLI utility. You can find a copy of this instruction in manager/templates/Embeddable/README.md inside the Verge3D distribution.

1) Create a Vue.js application via the Vue CLI utility: npx @vue/cli create vue-app-example

2) Copy the following files from Verge3D distribution into your app:

or use the commands below:

Change V3D_PATH and MY_PATH to where the Verge3D distribution and your Vue application are located respectively. 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/ cp $V3D_PATH/build/v3d.js $MY_PATH/public/
Change V3D_PATH and MY_PATH to where the Verge3D distribution and your Vue application are located respectively. $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 Copy-Item "$V3D_PATH\build\v3d.js" -Destination "$MY_PATH\public"

3) Add the following script tag into vue-app-example/public/index.html: <script src="<%= BASE_URL %>v3d.js"></script>

4) Create a file vue-app-example/src/components/V3DApp.vue containing the following code:

<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.logicURL = 'v3dApp/visual_logic.js'; this.loadApp = async function() { ({ app: this.app, PL: this.PL } = await createApp({ containerId: this.containerId, fsButtonId: this.fsButtonId, sceneURL: this.sceneURL, logicURL: this.logicURL, })); } 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> <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.logicURL = 'v3dApp/visual_logic.js'; this.loadApp = async function() { ({ app: this.app, PL: this.PL } = await createApp({ containerId: this.containerId, fsButtonId: this.fsButtonId, sceneURL: this.sceneURL, logicURL: this.logicURL, })); } 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>

5) Replace the contents of vue-app-example/src/App.vue with the following code: <template> <V3DApp></V3DApp> </template> <script> import V3DApp from './components/V3DApp.vue'; export default { name: 'App', components: { V3DApp, }, } </script>

6) Run the development server by executing the following command in the vue-app-example directory: npm run serve By default the application now should be available at http://localhost:8080/.

Using the Puzzles Editor

There's no direct integration between React/Vue and the Puzzles Editor/Application Manager. Nevertheless, you can still use Puzzles for adding behavior scenarios to your React/Vue applications. This section explains how to do that and what are the limitations of the chosen approach.

The Application Manager doesn't know what directory structure of a typical React/Vue project can look like. However, after some tweaking the manager can at least recognize the Puzzles' visual logic scripts. That means you can launch the Puzzles Editor from within the App Manager's web-page.

The drawback here is that working with Puzzles can only be done via a standard Verge3D application created within the App Manager. So, there's no access to React/Vue features, components, logic, etc... and Puzzles can be added only in a separate manner. Still a complete React/Vue application can load, run and communicate with logic scripts created in the Puzzles Editor.

App Manager Setup

Suppose we have a React or a Vue application created according to the guide described in this manual. In order to "connect" the App Manager and the React/Vue project we need to create a dedicated "adapter" application. That's a custom app template, which is not present by default in the App Manager but can be added in the App Manager Settings. Let's do that by following the Creating Templates tutorial but when it comes to naming the new template let's put Embeddable/adapter into the name field. Next, let's hit the Apply Changes button and the template will be successfully added to the App Manager:

Then, we need to create a new application using the newly added template. Let's call it my_awesome_app:

Finally, we need to create symbolic links pointing to resources in the React/Vue project that the App Manager needs to be able to launch the Puzzles Editor. Suppose that the React/Vue project is located at the path MY_PATH and your Verge3D applications folder is located at the path V3D_APPS_PATH.

You can check where Verge3D stores your applications in App Manager Settings -> General -> Applications Folder.

We'll create a symbolic link pointing from V3D_APPS_PATH/my_awesome_app/v3dApp to MY_PATH/public/v3dApp - the latter is the place inside the React/Vue project where verge3d-related scene resources are stored. Also, we need to create a couple more symbolic links for Puzzles' logic JS and XML files. Here's how this can be done:

Change V3D_APPS_PATH and MY_PATH to where the Verge3D applications folder and your React/Vue application are located respectively. Also, replace my_awesome_app with the name you specified when created the app in the App Manager. V3D_APPS_PATH=/path/to/v3d/applications MY_PATH=/path/to/my/app ln -s $MY_PATH/public/v3dApp $V3D_APPS_PATH/my_awesome_app/v3dApp ln -s v3dApp/visual_logic.js $V3D_APPS_PATH/my_awesome_app/visual_logic.js ln -s v3dApp/visual_logic.xml $V3D_APPS_PATH/my_awesome_app/visual_logic.xml

The following commands require PowerShell with administrator privileges.

Change V3D_APPS_PATH and MY_PATH to where the Verge3D applications folder and your React/Vue application are located respectively. Also, change my_awesome_app to the name you specified when creating the app in the App Manager. $V3D_APPS_PATH = "path\to\v3d\applications" $MY_PATH = "path\to\my\app" cmd /c mklink /D $V3D_APPS_PATH\my_awesome_app\v3dApp (Resolve-Path $MY_PATH\public\v3dApp) cmd /c mklink $V3D_APPS_PATH\my_awesome_app\visual_logic.js (Resolve-Path $V3D_APPS_PATH\my_awesome_app\v3dApp\visual_logic.js) cmd /c mklink $V3D_APPS_PATH\my_awesome_app\visual_logic.xml (Resolve-Path $V3D_APPS_PATH\my_awesome_app\v3dApp\visual_logic.xml)

After that, it only remains to open the file MY_PATH/src/v3dApp/app.js, then find the following line:

var LOAD_LOGIC_FILES = false;

and change it as follows to enable loading the Puzzles' logic script:

var LOAD_LOGIC_FILES = true;

Now you can see your project in the Application Manager and you can use the Puzzles Editor.

Loading Resources in Puzzles

Such puzzles as replace texture, load scene, load sound, load video, load data, etc... allow to specify URLs to load textures, media and other kinds of files.

When using the Puzzles Editor with a React/Vue application all file paths specified in such puzzles are calculated relative to the app root path which usually points to the app's public directory. If a React/Vue application was created according to the guide described in this manual then that directory is the one that should contain the v3d.js file and the v3dApp directory. Also, if the Puzzles Editor was integrated with a React/Vue application the way described in this manual then the Editor can only access the app's public/v3dApp directory.

So, if, for example, we want to load a sound file via puzzles, then that file, let's name it sound.mp3, should be placed inside the public/v3dApp directory (or its subdirectories). After that the file can be loaded by using v3dApp/mySound.mp3 inside the URL field in the load sound puzzle: