@shopware-ag/dive

About

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.

Installation

npm:

npm install @shopware-ag/dive

yarn:

yarn add @shopware-ag/dive

Setup in Shopware

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...
            ],
        },
    };
};

Usage

Quick View

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);

Example with Error Handling:

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);
}

Getting started

Import:

import { DIVE } from '@shopware-ag/dive'; // <-- import DIVE

Instantiate:

import { DIVE } from '@shopware-ag/dive';

const dive = new DIVE(); // <-- instantiate DIVE

DIVE 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 canvas

To 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

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 done

Actions List

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

Unit Tests

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.

Formatting

DIVE uses Prettier as a preconfigured formatter.