mykethearchangel/three.ez

Simplify three.js development, including events, drag & drop, binding, focus management, smart rendering, tweening and more.

three.ez

three.ez is a TypeScript library designed to streamline and enhance the development of three.js applications.
It provides a comprehensive suite of user-friendly tools and high-performance features.
With three.ez, you'll discover an efficient and robust toolkit for your 3D projects.

This library has only one dependency: three.js r151+.

Key Features

Feature	Description
Automatic Resize Handling	Automatically resizes the Renderer, Camera, and EffectComposer.
	Using the viewportResize event, you can easily set the resolution for custom shaders.
Smart Rendering	Optimize performance by rendering frames only when necessary, reducing computational overhead.
Simplified Multiple Rendering	Effortlessly manage rendering for multiple scenes or viewports within a single canvas.
Object3D Property Binding	Streamline the management of Object3D properties.
Event Programming	Add interactions to Object3D through programmable events, similar to DOM events.
	You can bind events for changes in position, scale, rotation, visibility, and enabled state.
Focus and Blur	Enhance interactivity with focus and blur events.
Drag and Drop	Seamlessly integrate drag-and-drop functionality.
Hitbox Functionality	Leverage hitboxes for customized intersections or simplified calculations.
Raycasting Options	Choose between continuous or mouse movement-based raycasting, optimizing intersection operations.
Tweening	Create smooth animations effortlessly with built-in tweening.
Simplified InstancedMesh	Manage InstancedMesh instances with the ease of working with Object3D, simplifying creation and manipulation.
Asset Management	Efficiently load and manage external assets and resources for your 3D projects.

Installation

You can install three.ez via npm using the following command:

npm install @three.ez/main

Usage

import { Scene, Mesh, BoxGeometry, MeshNormalMaterial } from 'three';
import { Main, PerspectiveCameraAuto } from '@three.ez/main';

const box = new Mesh(new BoxGeometry(0.1, 0.1, 0.1), new MeshNormalMaterial());

box.draggable = true;

box.on('animate', (e) => box.rotateX(e.delta).rotateY(e.delta * 2));

box.on(['pointerover', 'pointerout'], function (e) {
    this.tween('id').to(500, { scale: e.type === 'pointerover' ? 1.5 : 1 }, { easing: 'easeOutElastic' }).start();
});

const scene = new Scene().add(box);

const main = new Main();
main.createView({ scene, camera: new PerspectiveCameraAuto(70).translateZ(1) });

Live Examples

These examples use vite, and some mobile devices may run out of memory. However, there is one example without it.

Examples Collection

• Template — Template Extended — Template No Vite
• Smart Rendering
• Multiple Views — Multiple Views Wireframe — Multiple Views Switch
• Asset Management
• Binding — Binding Collisions
• Events — Click On Scene To Add Box
• Focus — Focus Outline (post-processing)
• Drag & Drop — LOD Draggable — Drag Limits
• Continuous Raycasting
• Hitbox
• Tweening — Tweening Custom Progress
• InstancedMeshEntity — InstancedMeshEntity Performance
• Draggable Box OrbitControls
• Textbox (troika-three-text)
• Bubble Refraction

Documentation

The tutorial is available here (work in progress).
The API documentation is available here.

Contributing

Any help is highly appreciated. If you would like to contribute to this package or report problems, feel free to open a bug or pull request.

Questions?

If you have questions or need assistance, you can create a discussion in the appropriate section.