npm package: @ngx-3d/effects
Description: Particle effects library for @ngx-3d/viewport
Latest version: 0.1.34

# @ngx-3d/effects

Particle effects library for [@ngx-3d/viewport](../core). Add stunning visual effects to your 3D objects with a simple declarative API.

## Features

- 🎨 **Declarative API** - Add effects through simple Angular components
- 🎯 **Smart Positioning** - Automatic anchor points with custom position support
- 🎭 **Layer Control** - Render effects in front, behind, or merged with objects
- 🔥 **Rich Presets** - Pre-configured effects ready to use (fire, smoke, water, etc.)
- ⚡ **Performance** - Optimized particle systems with pooling and batching
- 📐 **Camera-Aware** - Works with both orthographic and perspective cameras
- 🎛️ **Highly Customizable** - Fine-tune every aspect of your effects

## Installation

```bash
npm install @ngx-3d/effects
```

## Quick Start

```typescript
import { N3DEffect } from '@ngx-3d/effects';

@Component({
  standalone: true,
  imports: [N3DEffect],
  // ...
})
```

```html
<n3d-element id="rocket" modelPath="assets/rocket.glb">
  <n3d-effect 
    type="fire"
    anchor="bottom"
    [density]="200"
    [active]="true"
  />
</n3d-element>
```

## Available Effects

- `fire` - Animated fire with glow
- `smoke` - Soft rising smoke
- `water` - Fountain with physics
- `sparks` - Electric sparks
- `fireflies` - Glowing particles
- More coming soon!

## API

### Inputs

| Input | Type | Default | Description |
|-------|------|---------|-------------|
| `type` | `EffectType` | **required** | Effect preset type |
| `anchor` | `AnchorPosition` | `'center'` | Predefined anchor position |
| `customAnchor` | `{x,y,z}` | - | Custom 3D position (overrides anchor) |
| `renderLayer` | `RenderLayer` | `'merged'` | Render ordering: front, behind, or merged |
| `active` | `boolean` | `true` | Enable/disable effect |
| `density` | `number` | `100` | Number of particles |
| `spread` | `number` | `5` | Spatial distribution |
| `velocity` | `number` | `3` | Movement speed |
| `colors` | `string[]` | - | Custom color palette |
| `particleSize` | `{min,max}` | - | Particle size range |
| `lifetime` | `{min,max}` | - | Particle lifetime (seconds) |
| `opacity` | `number` | `1.0` | Overall opacity |
| `gravity` | `number` | `0` | Gravity force |
| `blendMode` | `BlendMode` | `'additive'` | Blending mode |
| `behavior` | `BehaviorType` | `'fountain'` | Movement behavior |

### Outputs

| Output | Type | Description |
|--------|------|-------------|
| `effectReady` | `{effectId: string}` | Emitted when effect is initialized |
| `particleSpawned` | `{particleIndex: number}` | Emitted when particles spawn |

## Examples

### Campfire

```html
<n3d-element id="campfire" modelPath="assets/logs.glb">
  <n3d-effect 
    type="fire"
    anchor="center"
    [density]="250"
    [spread]="4"
  />
  <n3d-effect 
    type="smoke"
    anchor="top"
    [density]="150"
    renderLayer="behind"
  />
</n3d-element>
```

### Custom Effect

```html
<n3d-effect 
  type="fire"
  [customAnchor]="{x: 0, y: 5, z: 0}"
  [colors]="['#00ff00', '#00aa00']"
  [particleSize]="{min: 10, max: 30}"
  [lifetime]="{min: 0.5, max: 1.5}"
  behavior="swarm"
/>
```

## License

MIT © elkestudio

## Links

- [Design Document](../../../PARTICLE_EFFECTS_DESIGN.md)
- [Core Library](../core)