A reusable 3D modeling engine extracted from Blockbench
npm install bench-3dA 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.
``bash`
npm install bench-3d three
Note: three is a peer dependency and must be installed separately.
Bench3D uses the same simple import pattern as Three.js and p5.js:
`typescript
// 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();
`
`typescript
// 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'.
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.
`typescript
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!
Bench3D works with React, Vue, and vanilla JavaScript/TypeScript:
`bash`
npm install bench-3d-react bench-3d three react react-dom
`tsx
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
}
`
See bench-3d-react for complete React documentation.
`bash`
npm install bench-3d-vue bench-3d three vue
`vue
`
See bench-3d-vue for complete Vue documentation.
See the Framework Integration Guide for detailed integration patterns.
`typescript
// 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.
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
- bench3d - Main entry point with all featuresbench3d/core
- - Core-only (without rendering)bench3d/full
- - Full features including Three.js renderer
Bench3D is designed to work with any UI framework. Here's an example with React:
`typescript
import { Bench3D } from 'bench-3d';
import { useEffect, useRef } from 'react';
function ModelEditor() {
const canvasRef = useRef
const engineRef = useRef
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 ;
}
``
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.
GPL-3.0-or-later