photon-editor

A high-performance, lightweight WebGL / WebXR scene orchestration library built on Three.js. Designed for rapid deployment of interactive 3D avatars and immersive environmental configurations.

Technical Architecture

photon-editor encapsulates the boilerplate of Three.js scene management into a streamlined lifecycle. It provides an optimized rendering pipeline specifically tuned for GLTF/GLB assets.

Key Features

• Optimized Pipeline: Pre-configured WebGLRenderer with sRGBEncoding, PCFSoftShadowMap, and alpha transparency.
• Dynamic Asset Orchestration: Native integration with GLTFLoader for asynchronous asset fetching and AnimationMixer for clip management.
• Procedural Interactivity: Integrated inverse-kinematic style joint tracking for rigged models (specifically targeting Mixamo-standard bone naming conventions).
• Environment Management: Declarative API for scene fog, hemisphere/directional lighting, and canvas background state.

Installation

npm install photon-editor three

Note: three is defined as a peer dependency to prevent version collisions in your bundle.

API Reference

PhotonEditor Class

The primary controller for managing the 3D environment and model lifecycle.

Methods

render()

Initializes the rendering pipeline and begins the internal animation loop.

• Returns: void
• Side Effects: Appends a canvas element to the DOM container with ID world.

perspective(options)

Updates the camera's frustum and projection matrix.

• Parameters:
  • options (Object):
    • field ('fov-input' | 'np-input' | 'fp-input'): The property to update (Field of View, Near Plane, or Far Plane).
    • offset (number): The new value to apply.
• Returns: void

cameraPosition(options)

Adjusts the camera's spatial coordinates in 3D space.

• Parameters:
  • options (Object):
    • field ('camera-x' | 'camera-y' | 'camera-z'): The axis to manipulate.
    • offset (number): The coordinate value.
• Returns: void

toggleInteractivity()

Activates or deactivates the mouse-tracking logic for rigged models.

• Returns: void
• Behavior: When active, binds a mousemove listener to the document to drive bone rotations based on cursor position.

refresh()

Internal teardown and reconstruction of the scene. Useful for hard-resetting state or swapping complex assets.

• Returns: void

Properties (Accessors)

path (Setter)

Updates the source path for the GLB model and triggers an asynchronous reload.

• Type: string
• Expected Values: A valid URL or relative path to a .glb or .gltf file.

Usage Example

import { PhotonEditor } from "photon-editor";

const editor = new PhotonEditor();

// Start the engine
editor.render();

// Reactive update example
const updateFOV = (val) => {
  editor.perspective({ field: "fov-input", offset: val });
};

// Hot-swapping models
editor.path = "./assets/models/character_v2.glb";