Hytopia Model Particles v2.3.0

Advanced particle system plugin for the Hytopia SDK featuring TRUE entity pooling, physics forces, spatial optimization, and simplified initialization.

🚀 What's New in v2.3.0

• 🎯 TRUE Entity Pooling - Entities stay spawned, just move between positions!
• 🚄 Zero Spawn/Despawn Overhead - Particles teleport instead of recreating
• 🏊 Gradual Pool Building - Builds 1000 entities at 10 per tick to avoid FPS drops
• 🎨 Parking System - Inactive particles hide at y=-1000 with physics disabled
• ⚡ Fixed Velocity Application - Particles explode properly when activated from pool

Previous v2.2.0 Features

• 🏊 Object Pooling - Reuse particles for massive performance gains
• 🌊 Physics Forces - Global wind, turbulence, and vortex effects
• 🎯 Spatial Optimization - Update only particles near players
• ⚡ TypedArray Buffers - Efficient particle data storage
• 🎮 Simplified API - Works with minimal code, powerful when needed
• 🔧 Backwards Compatible - ParticleSystemV1 still available

📦 Installation

npm install [email protected]

🎯 Quick Start - Simple by Default!

import { ParticleSystem } from 'hytopia-model-particles';

// Just works with minimal setup!
const particles = new ParticleSystem(world);

// Spawn with built-in effects
particles.spawn('explosion', position);
particles.spawn('smoke', position);
particles.spawn('spark', position);

// Or quickly register your own
particles.quickEffect('magic', {
  model: 'default',  // Uses built-in particle model
  count: 30,
  pattern: 'spiral'
});

particles.spawn('magic', position);

🏊 Object Pooling (Major Performance Win!)

const particles = new ParticleSystem(world, {
  poolSize: 200,  // Pre-create 200 particles
  performance: {
    enablePooling: true  // Default: true
  }
});

// Check pool efficiency
const stats = particles.getPerformanceReport();
console.log(stats.poolStats);
// {
//   available: 150,
//   active: 50,
//   totalCreated: 200,
//   poolEfficiency: 1.0  // 100% reuse!
// }

🌊 Physics Forces

Global Wind

const particles = new ParticleSystem(world, {
  physics: {
    globalWind: { x: 5, y: 0, z: 0 },  // Constant wind
    turbulence: 0.3  // Add randomness
  }
});

// Change wind dynamically
particles.setGlobalWind({ x: -10, y: 2, z: 0 });
particles.setTurbulence(0.5);

Vortex Effects

// Add a tornado at position
particles.addVortex(
  { x: 10, y: 0, z: 10 },  // Position
  20,                      // Strength
  15                       // Radius
);

// Particles will spiral around vortex centers!

🎯 Spatial Optimization

const particles = new ParticleSystem(world, {
  performance: {
    enableSpatialOptimization: true,
    updateRadius: 50  // Only update particles within 50 units of players
  }
});

// Particles far from all players automatically skip updates
// Great for large worlds with many effects!

💾 Memory Optimization

v2.2 uses TypedArray buffers internally for particle metadata:

• 75% less memory usage than objects
• Faster access to particle data
• Better CPU cache utilization

🎨 Complete Examples

Fire Effect with Wind

particles.registerEffect({
  name: 'fire',
  config: {
    modelUri: 'models/fire_particle.fbx',
    lifetime: 2000,
    tintColor: {
      type: 'smooth',
      keyframes: [
        { time: 0, color: { r: 255, g: 200, b: 100 } },
        { time: 0.5, color: { r: 255, g: 150, b: 50 } },
        { time: 1.0, color: { r: 200, g: 50, b: 20 } }
      ]
    },
    animations: {
      scaleOverTime: { start: 0.3, end: 0.8 },
      opacityOverTime: { start: 1, end: 0 }
    }
  },
  count: 40,
  pattern: 'fountain',
  velocityMin: { x: -1, y: 3, z: -1 },
  velocityMax: { x: 1, y: 6, z: 1 }
});

// Add wind effect
particles.setGlobalWind({ x: 3, y: 0, z: 0 });
particles.setTurbulence(0.4);

// Spawn fire
particles.spawn('fire', campfirePosition);

Magic Portal with Vortex

particles.registerEffect({
  name: 'portal',
  config: {
    modelUri: 'models/magic_particle.fbx',
    lifetime: 3000,
    useGravity: false,
    animations: {
      colorOverTime: {
        type: 'smooth',
        keyframes: [
          { time: 0, color: { r: 100, g: 50, b: 255 } },
          { time: 1, color: { r: 255, g: 100, b: 255 } }
        ]
      },
      rotationOverTime: { velocity: 360 }
    }
  },
  count: 50,
  pattern: 'ring'
});

// Add vortex at portal center
particles.addVortex(portalPosition, 15, 10);

// Spawn portal particles
particles.spawn('portal', portalPosition);

Explosion with Physics

// Built-in explosion already supports physics!
particles.spawn('explosion', position);

// Or customize it
particles.spawn('explosion', position, {
  count: 100,  // More particles
  velocity: { x: 0, y: 10, z: 0 }  // Upward bias
});

📊 Performance Monitoring

const report = particles.getPerformanceReport();
console.log(report);
// {
//   currentFPS: 59,
//   particleCount: 245,
//   poolStats: {
//     available: 55,
//     active: 245,
//     poolEfficiency: 0.95
//   },
//   bufferStats: {
//     capacity: 1000,
//     used: 245,
//     utilization: 0.245
//   }
// }

🔄 Migration from v2.1

v2.2 is fully backwards compatible! Your existing code will work without changes.

To use new features:

// Old way (still works)
const particles = new ParticleSystem(world, {
  maxParticles: 1000
});

// New way (with v2.2 features)
const particles = new ParticleSystem(world, {
  maxParticles: 1000,
  poolSize: 200,  // Enable pooling
  physics: {       // Enable physics
    globalWind: { x: 2, y: 0, z: 0 },
    turbulence: 0.3
  },
  performance: {   // Enable optimizations
    enableSpatialOptimization: true,
    updateRadius: 60
  }
});

🛠️ Advanced Configuration

Full Options

const particles = new ParticleSystem(world, {
  // Limits
  maxParticles: 2000,
  
  // Pooling
  poolSize: 500,
  
  // Physics
  physics: {
    globalWind: { x: 0, y: 0, z: 0 },
    turbulence: 0,
    enableForces: true
  },
  
  // Performance
  performance: {
    enableAdaptiveQuality: true,
    targetFPS: 60,
    enablePooling: true,
    enableSpatialOptimization: true,
    updateRadius: 50,
    qualityLevels: {
      high: { maxParticles: 2000 },
      medium: { maxParticles: 1000 },
      low: { maxParticles: 500 }
    }
  },
  
  // Entity factory (for custom entity creation)
  entityFactory: (config) => new Entity(config),
  
  // Debug mode
  debug: true
});

Use ParticleSystemV1 (Legacy)

import { ParticleSystemV1 } from 'hytopia-model-particles';

// Use old system if needed
const particles = new ParticleSystemV1(world, options);

🎮 Integration Example

// In your game's weapon system
class WeaponEffects {
  private particles: ParticleSystem;
  
  constructor(world: World) {
    this.particles = new ParticleSystem(world, {
      poolSize: 300,
      physics: {
        globalWind: { x: 2, y: 0, z: 0 },
        turbulence: 0.2
      }
    });
    
    // Register weapon effects
    this.particles.quickEffect('muzzle_flash', {
      count: 5,
      lifetime: 200,
      pattern: 'explosion'
    });
    
    this.particles.quickEffect('bullet_impact', {
      count: 15,
      pattern: 'explosion',
      scale: 0.2
    });
  }
  
  onWeaponFire(position: Vector3Like) {
    this.particles.spawn('muzzle_flash', position, {
      priority: 10  // High priority
    });
  }
  
  onBulletHit(position: Vector3Like) {
    this.particles.spawn('bullet_impact', position);
    this.particles.spawn('smoke', position);
  }
}

🏆 Performance Tips

1. Use Object Pooling - Biggest performance win, enabled by default
2. Set Appropriate Pool Size - Based on your max concurrent particles
3. Enable Spatial Optimization - For large worlds
4. Use Priority System - Important effects spawn first
5. Monitor Performance - Check poolEfficiency and adjust

📚 API Reference

See API Documentation for complete reference.

🔧 Changelog

v2.2.0

• Added object pooling system
• Added physics forces (wind, turbulence, vortex)
• Added spatial optimization
• Added TypedArray buffers
• Simplified initialization API
• Improved performance monitoring

v2.1.0

• Added particle animations
• Added new patterns
• Added performance monitoring
• Added YAML configuration

v2.0.0

• Initial release with entity factory pattern

📄 License

MIT