ZSort3D

A modern TypeScript z-plane rendering engine that simulates 3D depth using mathematical transformations and Canvas 2D rendering. Port of the original ActionScript 3.0 ZSort3D engine.

Installation

npm install zsort3d

Features

• 3D Simulation: Mathematical transformations using rotation matrices for realistic 3D space simulation
• Mouse Interaction: Drag-based rotation controls for intuitive navigation
• Efficient Rendering: Canvas 2D rendering with optimized depth sorting
• Interactive Objects: Click detection and event handling for 3D objects
• Configurable Perspective: Adjustable perspective distance for different 3D effects
• Multiple Object Types: Built-in support for balls, containers, and SVG objects
• TypeScript: Full type safety with comprehensive type declarations
• Dual Module Support: Both CommonJS and ESM exports for maximum compatibility

Quick Usage

import { Z3DRenderer, Z3DBall, Z3DContainer, Z3DSVG } from 'zsort3d';

// Create canvas element
const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;

// Create 3D objects
const objects = [
  new Z3DBall(50), // radius 50
  new Z3DContainer(100, 100, '#FF0000'), // 100x100 red container
  new Z3DSVG('<svg>...</svg>', 80, 80, 'My SVG', 'https://example.com')
];

// Initialize renderer
const renderer = new Z3DRenderer(canvas, objects);

// Optional: adjust perspective
renderer.perspectiveDistance = 200;

Architecture

• IZ3DSortable: Interface for 3D renderable objects
• Z3DSortable: Abstract base class implementing core 3D properties
• Z3DRenderer: Main rendering engine with Canvas 2D optimization
• Z3DBall: Sphere implementation with gradient shading
• Z3DContainer: Rectangular container implementation

Rendering Optimizations

• RequestAnimationFrame: Smooth 60fps rendering loop
• Depth Sorting: Efficient back-to-front rendering order
• Canvas Optimization: Minimal clear/redraw operations
• Scale-based Culling: Skip expensive operations for tiny objects

Development

Library Development

# Install dependencies
npm install

# Build library (both CommonJS and ESM)
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

Demo Development

# Start demo server
npm run demo

# Build demo for production
npm run demo:build

Publishing

The library is configured with a prepublishOnly script that automatically builds, type-checks, and lints before publishing:

npm publish

Browser Support

• Modern browsers with Canvas 2D support
• ES2020+ JavaScript engines
• Node.js 16.0.0+

License

MIT