🎨 My Animation Library

A powerful, feature-rich animation library combining Three.js, GSAP, and advanced mathematical utilities for creating stunning web animations and effects.

✨ Features

• 🚀 High-Performance Animation Engine - Built on GSAP for smooth, optimized animations
• 🎯 Advanced Math Utilities - Comprehensive mathematical functions for natural animations
• 🌊 Rich Effect Library - 20+ pre-built effects and animations
• 📱 Responsive & Touch-Friendly - Works seamlessly across all devices
• 🎨 Three.js Integration - WebGL-powered 3D animations and effects
• 📜 Smart Scroll Triggers - Automatic animation triggering on scroll
• 🧮 Easing Functions - 30+ easing functions for smooth transitions
• 🎭 Particle Systems - Dynamic particle effects and simulations
• 🔄 Spring Physics - Realistic spring-based animations
• 🎪 Morphing & Path Animations - Smooth shape and path interpolations

🚀 Quick Start

Installation

npm install my-animation-lib

CDN Usage

<script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>

Basic Usage

import { AnimationEngine, MathUtils } from 'my-animation-lib';

// Initialize the engine
const engine = new AnimationEngine();

// Create a spring animation
const element = document.getElementById('myElement');
engine.createSpringAnimation(element, {
    targetValue: 100,
    stiffness: 0.1,
    damping: 0.8
});

🎭 Effects Library

🌊 Wave Effects

createAdvancedWaveEffect(element, options)

Creates sophisticated wave animations with customizable parameters.

engine.createAdvancedWaveEffect(element, {
    amplitude: 50,        // Wave height
    frequency: 2,         // Wave frequency
    duration: 3,          // Animation duration
    easing: 'sine',       // Easing function
    direction: 'horizontal' // Wave direction
});

Options:

• amplitude (number): Wave height in pixels
• frequency (number): Number of wave cycles
• duration (number): Animation duration in seconds
• easing (string): Easing function name
• direction (string): 'horizontal' or 'vertical'

🎲 Noise Animations

createNoiseAnimation(element, options)

Generates organic, random movement using Perlin noise.

engine.createNoiseAnimation(element, {
    intensity: 30,        // Movement intensity
    speed: 0.5,          // Animation speed
    duration: 5,          // Total duration
    seed: 12345          // Random seed for consistency
});

Options:

• intensity (number): Maximum movement distance
• speed (number): Animation speed multiplier
• duration (number): Total animation duration
• seed (number): Random seed for reproducible results

🦘 Spring Animations

createSpringAnimation(element, options)

Creates realistic spring physics animations.

engine.createSpringAnimation(element, {
    targetValue: 150,     // Target position
    stiffness: 0.1,       // Spring stiffness (0-1)
    damping: 0.8,         // Damping factor (0-1)
    mass: 1.0,            // Mass of the object
    restThreshold: 0.01   // Rest threshold
});

Options:

• targetValue (number): Target position/value
• stiffness (number): Spring stiffness (0-1)
• damping (number): Damping factor (0-1)
• mass (number): Mass of the animated object
• restThreshold (number): Threshold to stop animation

✨ Particle Systems

createParticleSystem(container, options)

Generates dynamic particle effects with customizable properties.

engine.createParticleSystem(container, {
    particleCount: 100,   // Number of particles
    colors: ['#ff6b6b', '#4ecdc4', '#45b7d1'],
    size: { min: 2, max: 8 },
    speed: 0.5,           // Movement speed
    life: 3000,           // Particle lifetime in ms
    gravity: 0.1,         // Gravity effect
    wind: { x: 0.5, y: 0 }
});

Options:

• particleCount (number): Number of particles to generate
• colors (array): Array of hex colors for particles
• size (object): Min/max particle sizes
• speed (number): Movement speed multiplier
• life (number): Particle lifetime in milliseconds
• gravity (number): Gravity effect strength
• wind (object): Wind effect direction and strength

🎨 Color Transitions

createColorTransition(element, startColor, endColor, options)

Smoothly interpolates between two colors.

engine.createColorTransition(element, '#ff0000', '#00ff00', {
    duration: 2,          // Transition duration
    easing: 'sine',       // Easing function
    loop: true,           // Loop the transition
    yoyo: true            // Reverse direction
});

Options:

• duration (number): Transition duration in seconds
• easing (string): Easing function name
• loop (boolean): Whether to loop the transition
• yoyo (boolean): Whether to reverse direction

🛤️ Path Animations

createMorphingPath(element, pathPoints, options)

Animates elements along smooth Catmull-Rom spline paths.

const pathPoints = [
    { x: 0, y: 0 },
    { x: 100, y: 50 },
    { x: 200, y: 0 },
    { x: 300, y: 100 }
];

engine.createMorphingPath(element, pathPoints, {
    duration: 5,          // Animation duration
    easing: 'sine',       // Easing function
    loop: true,           // Loop the path
    autoRotate: true      // Auto-rotate along path
});

Options:

• duration (number): Animation duration in seconds
• easing (string): Easing function name
• loop (boolean): Whether to loop the path
• autoRotate (boolean): Auto-rotate element along path

🔄 Shape Morphing

createMorphingShape(element, shapes, options)

Smoothly interpolates between different shape definitions.

const shapes = [
    'circle(50% at 50% 50%)',
    'polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)',
    'ellipse(25% 40% at 50% 50%)'
];

engine.createMorphingShape(element, shapes, {
    duration: 3,          // Morphing duration
    easing: 'sine',       // Easing function
    loop: true,           // Loop the morphing
    steps: 10             // Number of interpolation steps
});

Options:

• duration (number): Morphing duration in seconds
• easing (string): Easing function name
• loop (boolean): Whether to loop the morphing
• steps (number): Number of interpolation steps

🧮 MathUtils Functions

Basic Math Functions

import { MathUtils } from 'my-animation-lib';

// Clamp value between min and max
MathUtils.clamp(5, 0, 10);        // Returns 5

// Linear interpolation
MathUtils.lerp(0, 100, 0.5);      // Returns 50

// Map value from one range to another
MathUtils.map(25, 0, 100, 0, 1); // Returns 0.25

// Random number between min and max
MathUtils.random(1, 10);          // Returns random number

// Distance between two points
MathUtils.distance(0, 0, 3, 4);   // Returns 5

Easing Functions

// Bounce effect
MathUtils.bounce(0.5);             // Returns bounce value

// Elastic effect
MathUtils.elastic(0.5);            // Returns elastic value

// Back effect
MathUtils.back(0.5);               // Returns back value

// Smooth step
MathUtils.smoothstep(0.3);         // Returns smoothstep value

Advanced Math Functions

// Fibonacci sequence
MathUtils.fibonacci(10);           // Returns 55

// Factorial
MathUtils.factorial(5);            // Returns 120

// Prime number check
MathUtils.isPrime(17);             // Returns true

// Greatest common divisor
MathUtils.gcd(48, 18);             // Returns 6

// Least common multiple
MathUtils.lcm(12, 18);             // Returns 36

🎯 Easing Functions

Standard Easing

import { Easing } from 'my-animation-lib';

// Linear
Easing.linear(t);

// Quadratic
Easing.easeInQuad(t);
Easing.easeOutQuad(t);
Easing.easeInOutQuad(t);

// Cubic
Easing.easeInCubic(t);
Easing.easeOutCubic(t);
Easing.easeInOutCubic(t);

// Bounce
Easing.easeInBounce(t);
Easing.easeOutBounce(t);
Easing.easeInOutBounce(t);

// Elastic
Easing.easeInElastic(t);
Easing.easeOutElastic(t);
Easing.easeInOutElastic(t);

Custom Easing

// Custom easing function
Easing.custom(t, [0.25, 0.46, 0.45, 0.94]);

// Bezier curve
Easing.bezier(t, 0.25, 0.46, 0.45, 0.94);

🎮 Advanced Usage

Custom Animation Timeline

const engine = new AnimationEngine();
const timeline = engine.createTimeline();

timeline
    .add(engine.createSpringAnimation(element1, { targetValue: 100 }))
    .add(engine.createWaveEffect(element2, { amplitude: 50 }), '-=0.5')
    .add(engine.createParticleSystem(container, { particleCount: 200 }));

timeline.play();

Scroll-Triggered Animations

const engine = new AnimationEngine({ enableScrollTrigger: true });

engine.createScrollAnimation(element, {
    trigger: '.trigger-element',
    start: 'top center',
    end: 'bottom center',
    animation: engine.createSpringAnimation(element, { targetValue: 200 })
});

Three.js Integration

const engine = new AnimationEngine({ enableThreeJS: true });

const scene = engine.threeJSManager.createScene();
const cube = engine.threeJSManager.createCube();

engine.createThreeJSAnimation(cube, {
    rotation: { x: Math.PI * 2, y: Math.PI * 2 },
    duration: 3,
    easing: 'elastic'
});

📱 Components

HiTechScroller

import { HiTechScroller } from 'my-animation-lib';

const scroller = new HiTechScroller({
    container: '.scroll-container',
    speed: 1.5,
    smoothness: 0.1
});

ScrollTrigger

import { ScrollTrigger } from 'my-animation-lib';

const trigger = new ScrollTrigger({
    trigger: '.element',
    start: 'top center',
    end: 'bottom center',
    onEnter: () => console.log('Element entered viewport'),
    onLeave: () => console.log('Element left viewport')
});

🔧 Configuration

AnimationEngine Options

const engine = new AnimationEngine({
    enableThreeJS: true,           // Enable Three.js features
    enableScrollTrigger: true,     // Enable scroll triggers
    defaultDuration: 1,            // Default animation duration
    defaultEasing: 'sine',         // Default easing function
    performanceMode: 'high'        // Performance optimization level
});

Performance Modes

• 'high': Maximum performance, minimal features
• 'balanced': Balanced performance and features (default)
• 'quality': Maximum quality, reduced performance

📦 Build & Development

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview build
npm run preview

Build Outputs

• dist/index.js - CommonJS bundle
• dist/index.esm.js - ES Modules bundle
• dist/index.umd.js - Universal bundle (CDN ready)

🌟 Examples

Check out the comprehensive examples in the examples/ directory:

• test-package.html - Complete package test and demo
• math-utils-integration.html - MathUtils integration examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GSAP - The animation powerhouse
• Three.js - 3D graphics library
• Perlin Noise - Natural randomness algorithm

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation
• 💬 Discord: Join our community

Made with ❤️ by [Your Name]