three.ez Documentation

repository·master·Indexed 18 days ago

A framework built on top of three.js designed to simplify scene management, viewport rendering, and application lifecycle through a centralized 'Main' class. It provides utilities for events, drag & drop, property binding, focus management, smart rendering, and tweening. Key features include automatic resizing cameras (OrthographicCameraAuto and PerspectiveCameraAuto), CSS-like selectors for Object3D elements, and a comprehensive RenderView management system.

Tokens: 45.7K
Snippets: 156
Records: 252
Agent score: 63%

What's inside three.ez

Overview of three.ez features
master
three.ez is a TypeScript library built to enhance three.js development. It provides high-level abstractions for common 3D tasks to reduce boilerplate and improve performance.
Core Capabilities:
- Automatic Resize Handling: Automatically synchronizes the Renderer, Camera, and EffectComposer with the window/container size. Use the viewportResize event to update custom shader resolutions.
- Smart Rendering: Reduces CPU/GPU overhead by rendering frames only when changes occur.
- Simplified Multiple Rendering: Manages multiple scenes or viewports within a single canvas.
- Object3D Property Binding: Streamlines the management of properties on Object3D instances.
- Event Programming: Enables interaction on Object3D using a DOM-like event model. You can bind events for changes in position, scale, rotation, visibility, and enabled state.
- Interactivity Tools: Includes built-in support for Focus/Blur events, Drag and Drop, and Hitbox functionality for customized intersections.
- Raycasting Optimization: Offers choices between continuous raycasting or raycasting triggered only by mouse movement.
- Animation & Instancing: Provides built-in tweening for smooth animations and a simplified interface for InstancedMesh that behaves like standard Object3D instances.
- Asset Management: Tools for loading and managing external resources.
https://github.com/agargaro/three.ez/blob/master/docs/docs/tutorial/index.md
Use the InstancedMesh2 namespace
master
The InstancedMesh2 namespace provides tools for managing large numbers of instances efficiently. It includes the core InstancedMesh2 class for managing the mesh and InstancedEntity for interacting with individual instances. You can also define custom data types for your entities using the Entity<T> type alias.
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/namespaces/InstancedMesh2.md
Understand Update events
master
Update events are triggered whenever a property or state value changes.
Key distinction: Unlike interaction events, update events do not follow a propagation system (they do not bubble up through the scene graph).
https://github.com/agargaro/three.ez/blob/master/docs/docs/tutorial/events/update.md

Understand miscellaneous events in three.ez

master

Miscellaneous events in three.ez cover viewport resizing and animation lifecycle hooks.

Key behaviors:

No Propagation: Unlike interaction events, miscellaneous events do not follow a propagation system.
Visibility Requirement: Animation events (beforeanimate, animate, afteranimate) are exclusively triggered for visible scenes.

Available Events

Event	Description	Parameters
`viewportresize`	Triggered on the first render and whenever an object is rendered with a different viewport size than the previous frame.	`ViewportResizeEvent`
`beforeanimate`	Triggered every frame immediately before the `animate` event. Use this to prepare object animations.	`AnimateEvent`
`animate`	Triggered every frame for animating objects.	`AnimateEvent`
`afteranimate`	Triggered every frame immediately after the `animate` event. Use this for post-animation operations.	`AnimateEvent`

Use custom or predefined easing functions in Tweening
master
The Easing type allows you to specify how a value changes over time during a tween. You can use a predefined easing name from the Easings class or provide a custom EasingFunction.
An EasingFunction is a function that takes a single number (representing progress from 0 to 1) and returns a number (the eased progress).
```
// Using a predefined easing name (from Easings class)
type Easing = keyof Easings | EasingFunction;

// Using a custom EasingFunction
type EasingFunction = (x: number) => number;

const myCustomEasing: EasingFunction = (x) => x * x; // Quadratic ease-in
```
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/namespaces/Tweening.md
Use easing functions for animations with Tweening.Easings
master
The Tweening.Easings class provides a collection of easing functions used to control the rate of change in animations. These functions determine how a value transitions from its start to its end state over time. For a detailed visual guide on what each easing function does, you can refer to easings.net.
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/classes/Tweening.Easings.md
Control binding update frequency with detectChanges and setManualDetectionMode
master
By default, bindings are calculated automatically. You can switch to a manual mode to optimize performance or control exactly when updates occur.
1. Enable Manual Mode: Call setManualDetectionMode() to stop automatic binding calculations.
2. Trigger Updates: Call detectChanges(recursive?) to calculate bindings. If recursive is set to true, it will also calculate bindings for all children of the object.
```
// Switch to manual mode
object.setManualDetectionMode();

// Manually trigger updates for this object and its children
object.detectChanges(true);
```
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/interfaces/Patch.Object3DExtPrototype.md
Understand the InteractionEvents interface
master
The InteractionEvents<T, R, RD> interface represents a collection of interaction events that propagate to parent objects in the scene hierarchy. It is parameterized to provide type safety for the primary target, related targets, and drag-specific targets.
Type Parameters
- T: The primary target type (defaults to Object3D).
- R: The related target type (defaults to Object3D).
- RD: The related target type specifically for drag events. This can be an Object3D or an InstancedMeshEntity.
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/interfaces/Events.InteractionEvents.md
How rendering works in three.ez
master
Rendering in three.ez is managed through a collection of RenderView instances. These instances are internally handled by the Main class.
To interact with the underlying WebGL engine, you can access the WebGLRenderer instance via the renderer property of the Main class.
https://github.com/agargaro/three.ez/blob/master/docs/docs/tutorial/rendering/how-it-works.md
Manage running tweens with TweenManager
master
The TweenManager class provides static methods to globally control all active tweens in the application. You can use it to stop or complete tweens based on their unique ID, a specific tag, or globally across all running tweens.
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/classes/Tweening.TweenManager.md
Use InstancedMesh2 for individual instance management
master
The InstancedMesh2 class extends the standard InstancedMesh to allow for individual management of each instance, treating them similarly to Object3D entities. It maintains an array of InstancedMeshEntity objects, where each element represents a separate instance that can be interacted with and managed independently.
Key features include:
- Individual Access: Access specific instances via the instances array or through state-based accessors like hoveredInstance, clickingInstance, draggingInstance, and focusedInstance.
- Interaction Support: Inherits and extends interaction capabilities such as dragging, clicking, and focusing.
- Event Triggering: Can be configured to trigger 'animate' events for each individual instance.
```
// Example conceptual usage
const mesh2 = new InstancedMesh2(geometry, material, 100, InstancedMeshEntity, true);

// Accessing the currently hovered instance
const hovered = mesh2.hoveredInstance;
if (hovered) {
  // Perform actions on the specific instance
}
```
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/classes/InstancedMesh.InstancedMesh2.md
Control binding updates with setManualDetectionMode() and detectChanges()
master
By default, bindings are calculated automatically. If you want to optimize performance or control exactly when updates occur, you can switch to manual mode.
1. Call setManualDetectionMode() to stop automatic binding calculations.
2. Call detectChanges(recursive?) to manually trigger the calculation of bindings on the object. If recursive is set to true, it will also calculate bindings for all children in the hierarchy.
```
// Switch to manual mode
camera.setManualDetectionMode();

// Later, manually trigger updates for this object and its children
camera.detectChanges(true);
```
https://github.com/agargaro/three.ez/blob/master/docs/docs/api/classes/Cameras.OrthographicCameraAuto.md

three.ez Documentation

What's inside three.ez

Available Events

Type Parameters