3d-cube-loader

A self-contained, customizable 3D rotating cube/dice loader built with Three.js. It features smooth rounded corners, dynamic speed adjustment on the X and Y axes, and on-the-fly texture updates.

By default, any cube face without an image URL renders in a sleek, matte black finish.

Features

• 📦 Zero-Configuration Setup: three is automatically installed as a dependency—no project config updates needed!
• 🔄 Dynamic Controls: Adjust rotation speed on both axes post-initialization.
• 🖼️ Live Swapping: Dynamically update or add image textures to specific cube faces.
• 🎨 Sleek Aesthetics: Rounded corners out-of-the-box via RoundedBoxGeometry.

Installation

Install the package via npm:

npm install 3d-cube-loader

Quick Start (Vanilla JavaScript)

Ensure you have a container element in your HTML:

<div id="loader-container"></div>

Import and initialize the loader in your JavaScript module:

import { RotatingDice } from "3d-cube-loader";

const container = document.getElementById("loader-container");

// Array of up to 6 image URLs corresponding to the cube faces:
// [right(+x), left(-x), top(+y), bottom(-y), front(+z), back(-z)]
const faceImages = [
  "https://example.com",
  "https://example.com",
  null, // Leave entries empty or null to keep them matte black
  null,
  "https://example.com",
  "https://example.com"
];

// Initialize the loader
const loader = RotatingDice(container, faceImages, {
  size: 400,       // Canvas dimensions (width and height in pixels)
  speedX: 0.02,    // Initial rotation speed around the X-axis
  speedY: 0.05,    // Initial rotation speed around the Y-axis
  cornerRadius: 0.1 // Roundness of the cube edges (0 for sharp edges)
});

Usage in React / TypeScript

For frameworks like React (Vite, Next.js, etc.), use this fully responsive, reactive wrapper component. It dynamically updates speed and textures on-the-fly without flickering or recreating the canvas.

Create a component named CubeLoader.tsx:

import { useEffect, useRef } from 'react';
import { RotatingDice } from '3d-cube-loader';

interface CubeLoaderProps {
  size?: number;
  speedX?: number;
  speedY?: number;
  cornerRadius?: number;
  faceImages?: (string | null)[];
}

export default function CubeLoader({
  size = 120,
  speedX = 0.01,
  speedY = 0.02,
  cornerRadius = 0.15,
  faceImages = [],
}: CubeLoaderProps) {
  const containerRef = useRef<HTMLDivElement>(null);
  const instanceRef = useRef<ReturnType<typeof RotatingDice> | null>(null);

  // Core scene initialization
  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const instance = RotatingDice(container, faceImages, { 
      size, 
      speedX, 
      speedY, 
      cornerRadius 
    });
    
    instanceRef.current = instance;

    return () => {
      if (instanceRef.current) {
        instanceRef.current.destroy();
        instanceRef.current = null;
      }
      container.innerHTML = '';
    };
  }, [size, cornerRadius]);

  // Push dynamic speed updates on-the-fly
  useEffect(() => {
    if (instanceRef.current) instanceRef.current.setSpeedX(speedX);
  }, [speedX]);

  useEffect(() => {
    if (instanceRef.current) instanceRef.current.setSpeedY(speedY);
  }, [speedY]);

  // Push live texture changes
  useEffect(() => {
    if (instanceRef.current && faceImages.length > 0) {
      faceImages.forEach((url, index) => {
        if (url) instanceRef.current?.updateFaceTexture(index, url);
      });
    }
  }, [faceImages]);

  return (
    <div 
      ref={containerRef} 
      style={{ 
        width: size, 
        height: size, 
        display: 'flex', 
        alignItems: 'center', 
        justifyContent: 'center' 
      }} 
    />
  );
}

API Reference (Vanilla JS)

The RotatingDice function returns a controller object containing the following methods:

setSpeedX(value)

Updates the rotation speed around the X-axis instantly.

• value (Number): The new rotation delta per frame.

setSpeedY(value)

Updates the rotation speed around the Y-axis instantly.

• value (Number): The new rotation delta per frame.

updateFaceTexture(index, url)

Changes or adds an image texture to a specific face dynamically.

• index (Number): The index of the face (0 to 5).
  • 0: Right (+X) | 1: Left (-X) | 2: Top (+Y) | 3: Bottom (-Y) | 4: Front (+Z) | 5: Back (-Z)
• url (String): The URL of the new image.

destroy()

Cleans up the animation loop, disposes of WebGL geometries/materials, and removes the canvas to prevent memory leaks.

Author

Jaswant Soni - Portfolio | GitHub

License

ISC