Skip to main content

Spatial framework within the Shopware universe.

Works with
It is unknown whether this package works with Bun
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
It is unknown whether this package works with Deno
This package works with Browsers
JSR Score
82%
Published
a week ago (1.0.6)

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

DIVE package is hosted on jsr.

npm:

npx jsr add @shopware-ag/dive

yarn:

yarn dlx jsr 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', '.tsx', '.js', '.vue'],
            alias: {
                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/@shopware-ag/dive')
                    ],
                    options: {
                        jsc: {
                            parser: {
                                syntax: 'typescript',
                            },
                            target: 'es2022',
                        },
                    },
                },
                ...
            ],
        }
    };
};

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

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
SET_BACKGROUND Set a background color
UPDATE_SCENE Update scene data
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
SET_CAMERA_LAYER Set camera layer to switch between live view and editor view
SET_CAMERA_TRANSFORM Set camera transformation (w/o animation, used to initially set up camera)
ZOOM_CAMERA Zoom in or out
GENERATE_MEDIA Generate a screenshot with the specified parameters
MODEL_LOADED Is performed when a model file is completely loaded
PLACE_ON_FLOOR Set a model onto to the floor
ADD_OBJECT Add an object to the scene
UPDATE_OBJECT Update an existing object
DELETE_OBJECT Delete an existing object
GET_ALL_OBJECTS Return a map of all objects
GET_OBJECTS Return a map of all objects (with the opportunity to filter for ids)
SELECT_OBJECT Select an existing object in the scene
SET_GIZMO_MODE Set gizmo mode
Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @shopware-ag/dive

Import symbol

import * as mod from "@shopware-ag/dive";

Add Package

npx jsr add @shopware-ag/dive

Import symbol

import * as mod from "@shopware-ag/dive";

Add Package

yarn dlx jsr add @shopware-ag/dive

Import symbol

import * as mod from "@shopware-ag/dive";

Add Package

pnpm dlx jsr add @shopware-ag/dive

Import symbol

import * as mod from "@shopware-ag/dive";

Add Package

bunx jsr add @shopware-ag/dive

Import symbol

import * as mod from "@shopware-ag/dive";