Quick Start

1. Create the provider

TypeScript

import StringTune from '@fiddle-digital/string-tune';
import { String3D, ThreeJSProvider } from 'string-tune-3d';
import * as THREE from 'three';

String3D.setProvider(new ThreeJSProvider(THREE));

const stringTune = StringTune.getInstance();

2. Register the module

TypeScript

stringTune.use(String3D);
stringTune.start(60);

3. Add one light and one object

HTML

<div
  string="3d"
  string-3d="directionalLight"
  style="--light-intensity: 1.25; --translate-x: -160; --translate-y: -120; --translate-z: 320"
></div>

<div
  string="3d"
  string-id="quick-start-orb"
  string-3d="sphere"
  style="
    width: 168px;
    height: 168px;
    --material-type: standard;
    --material-color: #d4dde7;
    --material-metalness: 0.18;
    --material-roughness: 0.34;
    --rotate-x: -14;
    --rotate-y: 18;
    --translate-z: 72;
  "
></div>

4. Drive it with CSS

CSS

[string-id='quick-start-orb'] {
  transition:
    --rotate-y 280ms ease,
    --translate-z 280ms ease;
}

[string-id='quick-start-orb']:hover {
  --rotate-y: 40;
  --translate-z: 96;
}

What happens behind the scenes

StringTune discovers the element because string="3d" matches the module htmlKey.
String3DScene creates a sphere object for string-3d="sphere" and a directional light for string-3d="directionalLight".
String3DSynchronizer reads the element box and computed styles.
String3DRenderer renders the scene into the fixed overlay container.

Common mistake

Do not expect the module to work before the provider is set. String3D exits early during initialization when no provider has been registered.