@web-engine-dev/vfx

Visual effects system for trails, lines, decals, and screen effects.

Features

• Trail Rendering: Ribbon/trail effects behind objects
• Line Rendering: Thick lines, bezier curves
• Decals: Projected textures on surfaces
• Screen Effects: Fullscreen post-process effects
• Distortion: Heat shimmer, shockwaves
• Billboards: Camera-facing sprites

Installation

npm install @web-engine-dev/vfx
# or
pnpm add @web-engine-dev/vfx

Quick Start

import { VFXSystem, Trail, Decal, Line } from '@web-engine-dev/vfx';

// Create VFX system
const vfx = new VFXSystem(renderer);

// Create trail
const trail = new Trail({
  width: 0.5,
  length: 2.0,
  color: '#ff6600',
  fadeOut: true,
});

// Update trail position
trail.addPoint(position);

// Render
vfx.update(deltaTime);
vfx.render(camera);

API Overview

Trails

const trail = new Trail({
  width: 0.5, // Trail width
  length: 2.0, // Max length in seconds
  segments: 32, // Segment count
  color: '#ffffff',
  texture: trailTexture,
  fadeOut: true, // Fade at end
  textureMode: 'stretch', // 'stretch', 'tile'
});

// Add points
trail.addPoint(position, time);

// Clear trail
trail.clear();

Lines

// Straight line
const line = new Line({
  points: [start, end],
  width: 2,
  color: '#00ff00',
});

// Bezier curve
const curve = new BezierLine({
  start: p0,
  control1: p1,
  control2: p2,
  end: p3,
  width: 2,
  segments: 32,
});

// Dashed line
const dashed = new Line({
  points: [start, end],
  dashLength: 10,
  gapLength: 5,
});

Decals

const decal = new Decal({
  texture: bulletHoleTexture,
  position: hitPoint,
  normal: hitNormal,
  size: { width: 0.5, height: 0.5 },
  rotation: Math.random() * Math.PI * 2,
  fadeTime: 10.0,
});

vfx.addDecal(decal);

Screen Effects

// Screen shake
vfx.screenShake({
  intensity: 10,
  duration: 0.3,
  frequency: 30,
});

// Screen flash
vfx.screenFlash({
  color: '#ffffff',
  duration: 0.1,
});

// Vignette pulse
vfx.vignettePulse({
  intensity: 0.5,
  duration: 0.5,
});

Distortion

const shockwave = new Shockwave({
  position: explosionPoint,
  radius: 0,
  maxRadius: 10,
  thickness: 1,
  distortion: 0.5,
  duration: 0.5,
});

Peer Dependencies

• @web-engine-dev/math - Vector math