TSL-Lib

A comprehensive TypeScript library for Three.js Shader Language (TSL) utilities designed for React Three Fiber projects. This library provides a collection of shader functions including easing, noise, mathematical operations, color utilities, and pattern generators.

🚀 Features

• Easing Functions: 30+ easing functions (quad, cubic, sine, expo, elastic, bounce, etc.)
• Noise Functions: Value noise, gradient noise, simplex noise, Voronoi, FBM, turbulence, and cellular noise
• Math Utilities: Remap, smoothstep, rotate2D, SDFs (circle, rectangle, hexagon, star), and more
• Color Functions: RGB/HSV/HSL conversions, hue/saturation/brightness adjustments, blend modes
• Pattern Generators: Grid, checkerboard, stripes, dots, waves, bricks, Voronoi cells, Truchet tiles

📦 Installation

npm install tsl-lib
# or
yarn add tsl-lib
# or
pnpm add tsl-lib

Peer Dependencies:

This library requires three version 0.160.0 or higher (with TSL support).

npm install three@latest

🎯 Usage

Basic Example

import { useRef } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import { float, uniform, vec2, vec4, Fn } from 'three/tsl';
import { MeshBasicNodeMaterial } from 'three/webgpu';
import { easeInOutCubic, valueNoise2D, remap } from 'tsl-lib';

function AnimatedMesh() {
  const materialRef = useRef();
  const time = uniform(0);

  useFrame((state) => {
    time.value = state.clock.elapsedTime;
  });

  // Create a custom shader using TSL
  const material = new MeshBasicNodeMaterial();
  
  material.colorNode = Fn(() => {
    const uv = vec2(/* your uv coordinates */);
    const t = easeInOutCubic(time.value.mod(1.0));
    const noise = valueNoise2D(uv.mul(5.0).add(time.value));
    const color = remap(noise, float(0.0), float(1.0), float(0.2), float(0.8));
    
    return vec4(color, color, color, 1.0);
  })();

  return (
    <mesh>
      <boxGeometry />
      <primitive object={material} attach="material" />
    </mesh>
  );
}

export default function App() {
  return (
    <Canvas>
      <AnimatedMesh />
    </Canvas>
  );
}

Easing Functions Example

import { easeInOutQuad, easeInOutElastic, easeOutBounce } from 'tsl-lib/easing';
import { float } from 'three/tsl';

// In your shader code
const t = float(time).fract(); // 0 to 1
const smoothValue = easeInOutQuad(t);
const elasticValue = easeInOutElastic(t);
const bounceValue = easeOutBounce(t);

Noise Functions Example

import { 
  valueNoise2D, 
  gradientNoise2D, 
  fbm2D, 
  voronoiNoise2D 
} from 'tsl-lib/noise';
import { vec2 } from 'three/tsl';

const uv = vec2(/* coordinates */);

// Simple noise
const noise1 = valueNoise2D(uv.mul(10.0));

// Fractal Brownian Motion
const fbm = fbm2D(uv, 6, 2.0, 0.5); // 6 octaves

// Voronoi
const voronoi = voronoiNoise2D(uv.mul(5.0));

Math Utilities Example

import { remap, rotate2D, circleSDF, smootherstep } from 'tsl-lib/math';
import { vec2, float } from 'three/tsl';

const uv = vec2(/* coordinates */);

// Remap value from one range to another
const remapped = remap(uv.x, float(0.0), float(1.0), float(-1.0), float(1.0));

// Rotate point
const rotated = rotate2D(uv, float(Math.PI / 4));

// Signed distance function for circle
const sdf = circleSDF(uv, vec2(0.5, 0.5), float(0.2));
const circle = smootherstep(float(-0.01), float(0.01), sdf);

Color Functions Example

import { 
  rgbToHsv, 
  hsvToRgb, 
  adjustHue, 
  adjustSaturation,
  overlay 
} from 'tsl-lib/color';
import { vec3 } from 'three/tsl';

const baseColor = vec3(0.8, 0.3, 0.5);

// Convert to HSV and adjust
const hsv = rgbToHsv(baseColor);
const adjustedColor = adjustHue(baseColor, float(0.1));
const saturated = adjustSaturation(baseColor, float(1.5));

// Blend modes
const blendColor = vec3(0.2, 0.6, 0.9);
const result = overlay(baseColor, blendColor);

Pattern Generators Example

import { 
  checkerboard, 
  concentricCircles, 
  voronoiCells,
  truchetTiles 
} from 'tsl-lib/patterns';
import { vec2 } from 'three/tsl';

const uv = vec2(/* coordinates */);

const checker = checkerboard(uv, float(10.0));
const circles = concentricCircles(uv, vec2(0.5, 0.5), float(20.0));
const cells = voronoiCells(uv, float(5.0));
const truchet = truchetTiles(uv, float(8.0));

📚 API Reference

Easing Functions

All easing functions take a single parameter t (0-1) and return an eased value:

• easeLinear, easeInQuad, easeOutQuad, easeInOutQuad
• easeInCubic, easeOutCubic, easeInOutCubic
• easeInQuart, easeOutQuart, easeInOutQuart
• easeInQuint, easeOutQuint, easeInOutQuint
• easeInSine, easeOutSine, easeInOutSine
• easeInExpo, easeOutExpo, easeInOutExpo
• easeInCirc, easeOutCirc, easeInOutCirc
• easeInBack, easeOutBack, easeInOutBack
• easeInElastic, easeOutElastic, easeInOutElastic
• easeInBounce, easeOutBounce, easeInOutBounce

Noise Functions

• random(vec2) - Simple random from 2D coordinates
• valueNoise2D(vec2) - Value noise
• gradientNoise2D(vec2) - Perlin-like gradient noise
• simplexNoise2D(vec2) - Simplex noise
• voronoiNoise2D(vec2) - Voronoi/cellular noise
• fbm2D(vec2, octaves, lacunarity, gain) - Fractal Brownian Motion
• turbulence2D(vec2, octaves) - Turbulence noise
• cellularNoise2D(vec2) - Cellular/Worley noise

Math Utilities

• remap(value, inMin, inMax, outMin, outMax) - Remap value between ranges
• smootherstep(edge0, edge1, x) - Improved smoothstep
• rotate2D(point, angle) - Rotate 2D point
• circleSDF(point, center, radius) - Circle signed distance
• rectangleSDF(point, center, size) - Rectangle signed distance
• hexagonSDF(point, radius) - Hexagon signed distance
• And many more...

Color Functions

• rgbToHsv(rgb), hsvToRgb(hsv) - Color space conversions
• rgbToHsl(rgb), hslToRgb(hsl) - HSL conversions
• adjustHue(rgb, adjustment) - Adjust hue
• adjustSaturation(rgb, adjustment) - Adjust saturation
• adjustBrightness(rgb, adjustment) - Adjust brightness
• Blend modes: overlay, screen, colorDodge, colorBurn, softLight

Pattern Generators

• gridPattern(uv, scale) - Grid lines
• checkerboard(uv, scale) - Checkerboard pattern
• stripes(uv, scale) - Stripe pattern
• concentricCircles(uv, center, scale) - Concentric circles
• dots(uv, scale, radius) - Dot pattern
• voronoiCells(uv, scale) - Voronoi cells
• truchetTiles(uv, scale) - Truchet tile pattern

🛠️ Development

# Install dependencies
npm install

# Build the library
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run type-check

🌟 Use Cases

• Procedural textures and materials
• Animated shader effects
• Particle systems
• Post-processing effects
• Dynamic backgrounds
• Generative art
• Game development
• WebGL/WebGPU visualizations

📖 Examples

Check out the /examples directory (coming soon) for complete working examples with React Three Fiber.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © [Your Name]

🔗 Links

• Three.js Documentation
• React Three Fiber
• Three.js Shading Language (TSL)

💡 Tips

1. Performance: TSL functions are compiled to GLSL/WGSL, so they run on the GPU
2. Type Safety: Full TypeScript support with proper type definitions
3. Tree Shaking: Import only what you need for optimal bundle size
4. Composability: Combine multiple functions to create complex effects

Built with ❤️ for the Three.js and React Three Fiber community