DIVE is a spatial framework made by and optimized for Shopware. It can be used directly integrated in a Shopware frontend such as Storefront or in any other frontend you want to use it in, it is not tied to Shopware.
DIVE supplies your frontend application with all needed tooling to set up a basic 3D application with event-based controls called "Actions". For further information, see Getting started.
The @shopware-ag/dive package can be installed via
npm install @shopware-ag/dive
or
yarn add @shopware-ag/diveIf you are using devenv, you have to make sure that you are in the correct shell while linking. nix (what devenv is
based on) uses it's own instances of npm so we need to make sure that the npm link get's executed within the correct devenv environment a.k.a nix/store.
To make sure you are using the correct instance of npm you have to browse to your devenv project:
cd path/to/your/devenv.nixIf you use direnv you should be launched into the correct shell automatically.
If you don't use direnv you can start the correct shell manually by running
devenv shellWithin the devenv shell you have to browse to your DIVE folder
cd path/to/@shopware-ag/diveYou don't have to do anything special if you don't use devenv.
If you want to link DIVE package locally after checking out, you can to that in the package's project folder:
cd path/to/@shopware-ag/dive
npm linkAfter registering the package in npm, you can use the sym-link in your project:
cd path/to/your/package.json
npm link @shopware-ag/diveAfter successfully linking DIVE into your project you will find the according sym-link in your node_modules.
Don't forget to include DIVE in your webpack.config.js:
const path = require('path');
module.exports = () => {
return {
// Other configurations...
resolve: {
extensions: [
'.ts',
'.cjs',
'.js',
],
alias: {
three: path.resolve(__dirname, 'path/to/node_modules/three'),
'@shopware-ag/dive': path.resolve(
__dirname,
'path/to/node_modules/@shopware-ag/dive',
),
},
},
module: {
rules: [
// Other rules...
{
test: /\.(js|ts)$/,
loader: 'swc-loader',
include: [
path.resolve(__dirname, 'path/to/node_modules/three'),
path.resolve(
__dirname,
'path/to/node_modules/@shopware-ag/dive',
),
],
options: {
jsc: {
parser: {
syntax: 'typescript',
},
target: 'es2022',
},
},
},
// Other rules...
],
},
};
};QuickView is used to quickly display your assets with as few lines of code as
possible. Simply call the static QuickView() method, with your data URI as a
parameter, to create an instance of DIVE with your asset to use in further code.
import { DIVE } from '@shopware-ag/dive';
const dive = DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
const myCanvasWrapper = document.createElement('div');
myCanvasWrapper.appendChild(dive.Canvas);import { DIVE } from '@shopware-ag/dive';
try {
const dive = DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
const myCanvasWrapper = document.createElement('div');
myCanvasWrapper.appendChild(dive.Canvas);
} catch (error) {
console.error('Failed to load asset:', error);
}import { DIVE } from '@shopware-ag/dive'; // <-- import DIVEimport { DIVE } from '@shopware-ag/dive';
const dive = new DIVE(); // <-- instantiate DIVEDIVE supplies your application with a HTMLCanvasElement that it uses as a render target. After instantiating, you can use the supplied canvas within your frontend code to attach it to your DOM.
const dive = new DIVE();
const myCanvasWrapper = document.createElement('div'); // <-- create wrapper element
myCanvasWrapper.appendChild(dive.Canvas); // <-- reference DIVE canvasTo interact with your newly created DIVE instance you have to perform actions via DIVECommunication. For further information, see Actions.
const dive = new DIVE();
const myCanvasWrapper = document.createElement('div');
myCanvasWrapper.appendChild(dive.Canvas);
const com = dive.Communication; // <-- reference DIVECommunication
com.PerformAction('SET_CAMERA_TRANSFORM', {
// <-- perform action on DIVECommunication
position: { x: 0, y: 2, z: 2 },
target: { x: 0, y: 0.5, z: 0 },
});Actions symbolize the communication between frontend and 3D space. All actions can be performed anywhere, no matter if you are in frontend or 3D.
In addition to the impact that specific actions have, every action can be subscribed to.
const myCanvasWrapper = document.createElement('div');
const dive = new DIVE();
myCanvasWrapper.appendChild(dive.Canvas);
const com = dive.Communication;
com.Subscribe('SET_CAMERA_TRANSFORM', () => {
// <-- add subscription
// do something
});
com.PerformAction('SET_CAMERA_TRANSFORM', {
position: { x: 0, y: 2, z: 2 },
target: { x: 0, y: 0.5, z: 0 },
});Subscribing to an action returns a unsubscribe()-callback that should be
executed when not needed anymore.
const myCanvasWrapper = document.createElement('div');
const dive = new DIVE();
myCanvasWrapper.appendChild(dive.Canvas);
const com = dive.Communication;
const unsubscribe = com.Subscribe('SET_CAMERA_TRANSFORM', () => {
// <-- save unsubscribe callback
// do something
});
com.PerformAction('SET_CAMERA_TRANSFORM', {
position: { x: 0, y: 2, z: 2 },
target: { x: 0, y: 0.5, z: 0 },
});
unsubscribe(); // <-- execute unsubscribe callback when doneIn the following you find a list of all available actions to perform on
DIVECommunication class via
com.PerformAction().
| Actions | Description |
|---|---|
| ADD_OBJECT | Adds an object to the scene. |
| COMPUTE_ENCOMPASSING_VIEW | Calculates the camera position and target to view the whole scene. (experimental) |
| DELETE_OBJECT | Deletes an object from the scene. |
| DESELECT_OBJECT | Deselects an existing object. |
| DROP_IT | Places an object on top of an underlying object or the floor. |
| EXPORT_SCENE | Exports the current scene to a blob and returns the URL. |
| GENERATE_MEDIA | Generates a screenshot, stores it in a Blob and writes the URL into the payload. |
| GET_ALL_OBJECTS | Retrieves all objects in the scene. |
| GET_ALL_SCENE_DATA | Retrieves all current scene data. |
| GET_CAMERA_TRANSFORM | Returns the current camera position and target. |
| GET_OBJECTS | Returns a list of objects of given IDs. |
| LAUNCH_AR | Launches AR mode in native capabilities. (iOS: AR Quick Look, Android: Google Scene Viewer) |
| MODEL_LOADED | Is triggered when a model is loaded. |
| MOVE_CAMERA | Moves the camera to a new position and target. |
| PLACE_ON_FLOOR | Places an object on the floor. |
| RESET_CAMERA | Reset the camera to its initial position and rotation. |
| SELECT_OBJECT | Selects an existing object. |
| SET_BACKGROUND | Set the background color of the scene. |
| SET_CAMERA_LAYER | Sets the camera layer to a certain layer. |
| SET_CAMERA_TRANSFORM | Sets the camera position and target. |
| SET_GIZMO_MODE | Sets the gizmo's mode. |
| SET_GIZMO_VISIBILITY | Sets the gizmo's visibility. |
| SET_PARENT | Attach an object to another object. |
| UPDATE_OBJECT | Updates an existing object. |
| UPDATE_SCENE | Updates global scene data. |
| USE_TOOL | Activates a specific tool from the toolbox. |
| ZOOM_CAMERA | Zooms the camera in or out by a certain amount. |
All relevant files are covered by Jest tests. If you find any file that has not been covered yet, feel free to add unit tests accordingly.
If there are any modules that have to be mocked (like three) you can create a given file in the __mocks__ folder in project root. Jest manages to mock modules with a given file with the modules name as a file name (for example three.ts). Every export will be part of the modules mock. You don't need to mock the module in your test anymore, you only extend the module mock.
If you have any other things from a module to import, you can simply create a folder structure and place the mock file at the end of your structure. To understand better please take a look at the __mocks__ folder for yourself.
DIVE uses Prettier as a preconfigured formatter.