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. 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 relevant files are located inside the Verge3D distribution: for Blender - manager/templates/Embeddable, for Max - manager/templates/Embeddable-Max, for Maya - manager/templates/Embeddable-Maya.

• Verge3D React.js Application Example
• Verge3D Vue.js Application Example
• Using the Puzzles Editor

#

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) Enter the react-app-example directory and install the verge3d npm package: cd react-app-example npm i verge3d

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

• the contents of Verge3D's manager/templates/Embeddable/public directory to react-app-example/public
• the contents of Verge3D's manager/templates/Embeddable/src directory to react-app-example/src

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'; 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) 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 Vite. 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 Vite: npm create vite@latest vue-app-example -- --template vue

2) Enter the vue-app-example directory and install the verge3d npm package: cd vue-app-example npm i verge3d

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

• the contents of Verge3D's manager/templates/Embeddable/public directory to vue-app-example/public
• the contents of Verge3D's manager/templates/Embeddable/src directory to vue-app-example/src

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

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 dev By default the application now should be available at http://localhost:5173/.

#

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:

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 relatively to the app root path which usually points to the app's public directory. 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: