@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 {
        ...
        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: [
                ...
                {
                    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',
                        },
                    },
                },
                ...
            ],
        }
    };
};

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

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 you 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().

Action	Description
GET_ALL_SCENE_DATA	Return all scene data that is currently set
GET_ALL_OBJECTS	Return a map of all objects
GET_OBJECTS	Return an array of all objects with given ids
ADD_OBJECT	Add an object to the scene
UPDATE_OBJECT	Update an existing object
DELETE_OBJECT	Delete an existing object
SELECT_OBJECT	Select an existing object in the scene
DESELECT_OBJECT	Deselect an existing object in the scene
SET_BACKGROUND	Set a background color
DROP_IT	Places the model onto the next underlying object's bounding box
PLACE_ON_FLOOR	Places the model onto the floor (zero plane)
SET_CAMERA_TRANSFORM	Set camera transformation (w/o animation, used to initially set up camera)
GET_CAMERA_TRANSFORM	Return currenty camera transformation
MOVE_CAMERA	Move camera to a specific position or the position of a previously defined POV (with an animation)
RESET_CAMERA	Reset camera to original position after MOVE_CAMERA was performed
COMPUTE_ENCOMPASSING_VIEW,	Calculates the camera position and target to view the whole scene
SET_CAMERA_LAYER	Set camera layer to switch between live view and editor view
ZOOM_CAMERA	Zoom in or out
SET_GIZMO_MODE	Set gizmo mode
SET_GIZMO_VISIBILITY	Set gizmo visibility
USE_TOOL	Use a specific tool
MODEL_LOADED	Is performed when a model file is completely loaded
UPDATE_SCENE	Update scene data
GENERATE_MEDIA	Generate a screenshot with the specified parameters