Bench3D

A reusable 3D modeling engine extracted from Blockbench. Bench3D provides the core 3D modeling functionality without UI dependencies, making it easy to build custom 3D modeling applications with React, Vue, or any other framework.

Installation

npm install bench-3d three

Note: three is a peer dependency and must be installed separately.

Import Style (Like Three.js and p5.js)

Bench3D uses the same simple import pattern as Three.js and p5.js:

// Namespace import (recommended - like Three.js)
import * as Bench3D from 'bench-3d';

// Use everything through the namespace
const engine = new Bench3D.Bench3D({ canvas: myCanvas });
const project = engine.createProject();
const cube = project.addCube({ size: [16, 16, 16] });
const exporter = new Bench3D.GLTFExporter();

// Named imports (also works)
import { Bench3D, Project, Cube, GLTFExporter } from 'bench-3d';

const engine = new Bench3D({ canvas: myCanvas });
const project = engine.createProject();
const cube = project.addCube({ size: [16, 16, 16] });

The namespace import (import * as Bench3D) is the recommended and primary way to use Bench3D, just like import * as THREE from 'three'.

TypeScript Support

Bench3D is written in TypeScript and provides full type definitions. All exports are fully typed, and you'll get excellent IDE support with autocomplete and type checking.

import * as Bench3D from 'bench-3d';

// Full type safety with namespace import
const engine = new Bench3D.Bench3D({ canvas: myCanvas });
const project: Bench3D.Project = engine.createProject();
const cube: Bench3D.Cube = project.addCube({ size: [16, 16, 16] });
const offset: Bench3D.Vector3 = [10, 0, 0];

Type definitions are automatically included when you install the package. No additional @types package needed!

Framework Integration

Bench3D works with React, Vue, and vanilla JavaScript/TypeScript:

React

npm install bench-3d-react bench-3d three react react-dom

import { Bench3DCanvas, useBench3D, useProject } from 'bench-3d-react';

function MyApp() {
  const { project, isReady } = useBench3D();
  const { addCube } = useProject(project);
  
  useEffect(() => {
    if (isReady && project) {
      addCube({ size: [16, 16, 16] });
    }
  }, [isReady, project, addCube]);
  
  return <Bench3DCanvas width={800} height={600} />;
}

See bench-3d-react for complete React documentation.

Vue

npm install bench-3d-vue bench-3d three vue

<template>
  <Bench3DCanvas :width="800" :height="600" />
</template>

<script setup lang="ts">
import { onMounted } from 'vue';
import { Bench3DCanvas, useBench3D, useProject } from 'bench-3d-vue';

const { project, isReady } = useBench3D();
const { addCube } = useProject(project);

onMounted(() => {
  if (isReady.value && project.value) {
    addCube({ size: [16, 16, 16] });
  }
});
</script>

See bench-3d-vue for complete Vue documentation.

Vanilla JavaScript/TypeScript

See the Framework Integration Guide for detailed integration patterns.

Quick Start

Namespace Import (Recommended)

// Single line import - everything included!
import * as Bench3D from 'bench-3d';

// Create an engine instance
const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;
const engine = new Bench3D.Bench3D({
  canvas: canvas,
  onUpdate: (event) => {
    console.log('Update:', event.type, event.data);
  }
});

// Create a project
const project = engine.createProject({
  name: 'My Model',
  texture_width: 16,
  texture_height: 16
});

// Add geometry
const cube = project.addCube({
  name: 'My Cube',
  size: [16, 16, 16],
  origin: [0, 0, 0]
});

// Transform elements
Bench3D.moveElements([cube], [10, 0, 0] as Bench3D.Vector3);

// Render
engine.render();

Both import styles work! Use whichever you prefer.

Core Features

Geometry Management

• Cubes: Box-based geometry with UV mapping
• Meshes: Custom vertex-based geometry with faces
• Groups: Organize elements hierarchically
• Armatures: Skeletal animation support with bones

Project System

• Manage multiple projects
• Element and group selection
• Texture management
• Animation system

Modeling Operations

• Transform operations (move, rotate, scale)
• Selection management
• Geometry manipulation

Animation System

• Keyframe-based animations
• Timeline markers
• Animator system for bones and elements

Texturing System

• Texture management
• UV mapping
• Layer support

Rendering

• Abstracted renderer interface
• Three.js renderer implementation
• Framework-agnostic design

I/O System

• JSON import/export
• Extensible format system
• Project serialization

Architecture

Bench3D is structured to separate core functionality from UI:

bench3d/
├── core/              # Core modeling engine (no DOM dependencies)
│   ├── geometry/      # Mesh, Cube, geometry operations
│   ├── modeling/     # Transform, editing operations
│   ├── animation/    # Animation system
│   ├── texturing/    # UV mapping, textures
│   ├── rendering/     # Three.js scene management (abstracted)
│   ├── io/           # File format import/export
│   └── project/      # Project management
├── api/              # Public API surface
└── utils/            # Shared utilities

Entry Points

• bench3d - Main entry point with all features
• bench3d/core - Core-only (without rendering)
• bench3d/full - Full features including Three.js renderer

Framework Integration

Bench3D is designed to work with any UI framework. Here's an example with React:

import { Bench3D } from 'bench-3d';
import { useEffect, useRef } from 'react';

function ModelEditor() {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const engineRef = useRef<Bench3D | null>(null);

  useEffect(() => {
    if (canvasRef.current && !engineRef.current) {
      engineRef.current = new Bench3D({
        canvas: canvasRef.current,
      });
      
      const project = engineRef.current.createProject();
      project.addCube({ size: [16, 16, 16] });
      
      const animate = () => {
        engineRef.current?.render();
        requestAnimationFrame(animate);
      };
      animate();
    }
  }, []);

  return <canvas ref={canvasRef} width={800} height={600} />;
}

Building a Full 3D Modeler

Want to build your own 3D modeling application like Blockbench? Bench3D provides all the core functionality you need. See BUILDING_A_MODELER.md for a complete guide on what's included and what you need to build.

TL;DR: Bench3D provides ~80% of what you need (all the core modeling operations). You build the remaining 20% (UI, interaction, tools) using your preferred framework.

License

GPL-3.0-or-later