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

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_v3d_app

2) Delete all files in the react_v3d_app/src directory.

3) Copy the content of the manager/templates/Embeddable/public Verge3D's directory to react_v3d_app/public.

Copy the content of the manager/templates/Embeddable/src Verge3D's directory to react_v3d_app/src.

Copy the engine file build/v3d.js to react_v3d_app/public.

4) Add the following script tag into react_v3d_app/public/index.html: <script src="%PUBLIC_URL%/v3d.js"></script>

5) Create a components directory inside react_v3d_app/src. Then create a file called react_v3d_app/src/components/V3DApp.js with the following content: import React from 'react'; import * as v3dAppAPI from '../v3dApp/app.js'; import '../v3dApp/app.css'; class V3DApp extends React.Component { #app = null; componentDidMount() { v3dAppAPI.createApp().then(app => { this.#app = app; }); } componentWillUnmount() { if (this.#app !== null) { this.#app.dispose(); this.#app = null; } } render() { return <div id={v3dAppAPI.CONTAINER_ID}> <div id="fullscreen_button" className="fullscreen-button fullscreen-open" title="Toggle fullscreen mode"></div> </div>; } } export default V3DApp;

6) Create a file react_v3d_app/src/index.js containing the following code: import React from 'react'; import ReactDOM from 'react-dom'; import V3DApp from './components/V3DApp.js'; ReactDOM.render( <V3DApp/>, document.getElementById('root') );

7) Run the development server by executing the following command in the react_v3d_app 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_v3d_app

2) Copy the content of the manager/templates/Embeddable/public Verge3D's directory to vue_v3d_app/public.

Copy the content of the manager/templates/Embeddable/src Verge3D's directory to vue_v3d_app/src.

Copy the engine file build/v3d.js to vue_v3d_app/public.

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

4) Create a file vue_v3d_app/src/components/V3DApp.vue containing the following code: <template> <div :id="containerId"> <div id="fullscreen_button" class="fullscreen-button fullscreen-open" title="Toggle fullscreen mode"></div> </div> </template> <script> import * as v3dAppAPI from '../v3dApp/app.js'; export default { name: 'V3DApp', data() { return { containerId: v3dAppAPI.CONTAINER_ID, } }, app: null, mounted() { v3dAppAPI.createApp().then(app => { this.$options.app = app; }); }, beforeDestroy() { if (this.$options.app) { this.$options.app.dispose(); this.$options.app = null; } }, } </script> <style> @import '../v3dApp/app.css'; </style>

The beforeDestroy() hook is deprecated in Vue.js 3.0.0+, use beforeUnmount() instead.
See: https://eslint.vuejs.org/rules/no-deprecated-destroyed-lifecycle.html

5) Change vue_v3d_app/src/App.vue so it will look like this: <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_v3d_app 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 project's blend-files, the exported .gltf/.glb/.bin scene files and the Puzzles' visual logic scripts. That means you can view the corresponding scene resources and launch the Puzzles Editor from within the App Manager's web-page.

The drawback here is that viewing the .gltf files and working with Puzzles can be only done via the Verge3D Player, i.e the same way as for all standard Verge3D applications 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 the logic script 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. Let's say that it's located at the path APP_PATH and your Verge3D distribution is located at the path VERGE3D_PATH.

In order to "connect" the App Manager and the React/Vue project we need to create a dedicated directory inside VERGE3D_PATH/applications (the place where all Verge3D applications are usually found). We'll create it as a symbolic link pointing to APP_PATH/public/v3dApp - this is the place inside our React/Vue project where the verge3d-related scene resources and Puzzles' logic files are located. Let's call the new directory my_app. Here's how it can be done:

on Linux ln -sr APP_PATH/public/v3dApp VERGE3D_PATH/applications/my_app on Windows (PowerShell, requires administrator rights) cmd /c mklink /D VERGE3D_PATH\applications\my_app (Resolve-Path APP_PATH\public\v3dApp)

After that, it remains only to open the file APP_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. You can open its .gltf and .blend files and use the Puzzles Editor.