{"id":47966530,"url":"https://github.com/web3dev1337/hytopia-model-particles","last_synced_at":"2026-04-04T10:36:03.978Z","repository":{"id":283768628,"uuid":"944781599","full_name":"web3dev1337/hytopia-model-particles","owner":"web3dev1337","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-18T05:41:24.000Z","size":70237,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-18T15:54:41.860Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/web3dev1337.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-08T00:31:10.000Z","updated_at":"2026-01-18T05:40:22.000Z","dependencies_parsed_at":"2025-10-21T06:15:01.408Z","dependency_job_id":"7f41d052-a9ba-41d0-9d9f-7851b95fa435","html_url":"https://github.com/web3dev1337/hytopia-model-particles","commit_stats":null,"previous_names":["web3dev1337/hytopia-model-particles"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/web3dev1337/hytopia-model-particles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-model-particles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-model-particles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-model-particles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-model-particles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/web3dev1337","download_url":"https://codeload.github.com/web3dev1337/hytopia-model-particles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dev1337%2Fhytopia-model-particles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T10:36:03.923Z","updated_at":"2026-04-04T10:36:03.972Z","avatar_url":"https://github.com/web3dev1337.png","language":"TypeScript","readme":"# Hytopia Model Particles v2.3.0\n\nAdvanced particle system plugin for the Hytopia SDK featuring **TRUE entity pooling**, **physics forces**, **spatial optimization**, and **simplified initialization**.\n\n## 🚀 What's New in v2.3.0\n\n- 🎯 **TRUE Entity Pooling** - Entities stay spawned, just move between positions!\n- 🚄 **Zero Spawn/Despawn Overhead** - Particles teleport instead of recreating\n- 🏊 **Gradual Pool Building** - Builds 1000 entities at 10 per tick to avoid FPS drops\n- 🎨 **Parking System** - Inactive particles hide at y=-1000 with physics disabled\n- ⚡ **Fixed Velocity Application** - Particles explode properly when activated from pool\n\n## Previous v2.2.0 Features\n\n- 🏊 **Object Pooling** - Reuse particles for massive performance gains\n- 🌊 **Physics Forces** - Global wind, turbulence, and vortex effects\n- 🎯 **Spatial Optimization** - Update only particles near players\n- ⚡ **TypedArray Buffers** - Efficient particle data storage\n- 🎮 **Simplified API** - Works with minimal code, powerful when needed\n- 🔧 **Backwards Compatible** - ParticleSystemV1 still available\n\n## 📦 Installation\n\n```bash\nnpm install hytopia-model-particles@2.3.0\n```\n\n## 🎯 Quick Start - Simple by Default!\n\n```typescript\nimport { ParticleSystem } from 'hytopia-model-particles';\n\n// Just works with minimal setup!\nconst particles = new ParticleSystem(world);\n\n// Spawn with built-in effects\nparticles.spawn('explosion', position);\nparticles.spawn('smoke', position);\nparticles.spawn('spark', position);\n\n// Or quickly register your own\nparticles.quickEffect('magic', {\n  model: 'default',  // Uses built-in particle model\n  count: 30,\n  pattern: 'spiral'\n});\n\nparticles.spawn('magic', position);\n```\n\n## 🏊 Object Pooling (Major Performance Win!)\n\n```typescript\nconst particles = new ParticleSystem(world, {\n  poolSize: 200,  // Pre-create 200 particles\n  performance: {\n    enablePooling: true  // Default: true\n  }\n});\n\n// Check pool efficiency\nconst stats = particles.getPerformanceReport();\nconsole.log(stats.poolStats);\n// {\n//   available: 150,\n//   active: 50,\n//   totalCreated: 200,\n//   poolEfficiency: 1.0  // 100% reuse!\n// }\n```\n\n## 🌊 Physics Forces\n\n### Global Wind\n```typescript\nconst particles = new ParticleSystem(world, {\n  physics: {\n    globalWind: { x: 5, y: 0, z: 0 },  // Constant wind\n    turbulence: 0.3  // Add randomness\n  }\n});\n\n// Change wind dynamically\nparticles.setGlobalWind({ x: -10, y: 2, z: 0 });\nparticles.setTurbulence(0.5);\n```\n\n### Vortex Effects\n```typescript\n// Add a tornado at position\nparticles.addVortex(\n  { x: 10, y: 0, z: 10 },  // Position\n  20,                      // Strength\n  15                       // Radius\n);\n\n// Particles will spiral around vortex centers!\n```\n\n## 🎯 Spatial Optimization\n\n```typescript\nconst particles = new ParticleSystem(world, {\n  performance: {\n    enableSpatialOptimization: true,\n    updateRadius: 50  // Only update particles within 50 units of players\n  }\n});\n\n// Particles far from all players automatically skip updates\n// Great for large worlds with many effects!\n```\n\n## 💾 Memory Optimization\n\nv2.2 uses TypedArray buffers internally for particle metadata:\n- 75% less memory usage than objects\n- Faster access to particle data\n- Better CPU cache utilization\n\n## 🎨 Complete Examples\n\n### Fire Effect with Wind\n```typescript\nparticles.registerEffect({\n  name: 'fire',\n  config: {\n    modelUri: 'models/fire_particle.fbx',\n    lifetime: 2000,\n    tintColor: {\n      type: 'smooth',\n      keyframes: [\n        { time: 0, color: { r: 255, g: 200, b: 100 } },\n        { time: 0.5, color: { r: 255, g: 150, b: 50 } },\n        { time: 1.0, color: { r: 200, g: 50, b: 20 } }\n      ]\n    },\n    animations: {\n      scaleOverTime: { start: 0.3, end: 0.8 },\n      opacityOverTime: { start: 1, end: 0 }\n    }\n  },\n  count: 40,\n  pattern: 'fountain',\n  velocityMin: { x: -1, y: 3, z: -1 },\n  velocityMax: { x: 1, y: 6, z: 1 }\n});\n\n// Add wind effect\nparticles.setGlobalWind({ x: 3, y: 0, z: 0 });\nparticles.setTurbulence(0.4);\n\n// Spawn fire\nparticles.spawn('fire', campfirePosition);\n```\n\n### Magic Portal with Vortex\n```typescript\nparticles.registerEffect({\n  name: 'portal',\n  config: {\n    modelUri: 'models/magic_particle.fbx',\n    lifetime: 3000,\n    useGravity: false,\n    animations: {\n      colorOverTime: {\n        type: 'smooth',\n        keyframes: [\n          { time: 0, color: { r: 100, g: 50, b: 255 } },\n          { time: 1, color: { r: 255, g: 100, b: 255 } }\n        ]\n      },\n      rotationOverTime: { velocity: 360 }\n    }\n  },\n  count: 50,\n  pattern: 'ring'\n});\n\n// Add vortex at portal center\nparticles.addVortex(portalPosition, 15, 10);\n\n// Spawn portal particles\nparticles.spawn('portal', portalPosition);\n```\n\n### Explosion with Physics\n```typescript\n// Built-in explosion already supports physics!\nparticles.spawn('explosion', position);\n\n// Or customize it\nparticles.spawn('explosion', position, {\n  count: 100,  // More particles\n  velocity: { x: 0, y: 10, z: 0 }  // Upward bias\n});\n```\n\n## 📊 Performance Monitoring\n\n```typescript\nconst report = particles.getPerformanceReport();\nconsole.log(report);\n// {\n//   currentFPS: 59,\n//   particleCount: 245,\n//   poolStats: {\n//     available: 55,\n//     active: 245,\n//     poolEfficiency: 0.95\n//   },\n//   bufferStats: {\n//     capacity: 1000,\n//     used: 245,\n//     utilization: 0.245\n//   }\n// }\n```\n\n## 🔄 Migration from v2.1\n\nv2.2 is fully backwards compatible! Your existing code will work without changes.\n\nTo use new features:\n\n```typescript\n// Old way (still works)\nconst particles = new ParticleSystem(world, {\n  maxParticles: 1000\n});\n\n// New way (with v2.2 features)\nconst particles = new ParticleSystem(world, {\n  maxParticles: 1000,\n  poolSize: 200,  // Enable pooling\n  physics: {       // Enable physics\n    globalWind: { x: 2, y: 0, z: 0 },\n    turbulence: 0.3\n  },\n  performance: {   // Enable optimizations\n    enableSpatialOptimization: true,\n    updateRadius: 60\n  }\n});\n```\n\n## 🛠️ Advanced Configuration\n\n### Full Options\n```typescript\nconst particles = new ParticleSystem(world, {\n  // Limits\n  maxParticles: 2000,\n  \n  // Pooling\n  poolSize: 500,\n  \n  // Physics\n  physics: {\n    globalWind: { x: 0, y: 0, z: 0 },\n    turbulence: 0,\n    enableForces: true\n  },\n  \n  // Performance\n  performance: {\n    enableAdaptiveQuality: true,\n    targetFPS: 60,\n    enablePooling: true,\n    enableSpatialOptimization: true,\n    updateRadius: 50,\n    qualityLevels: {\n      high: { maxParticles: 2000 },\n      medium: { maxParticles: 1000 },\n      low: { maxParticles: 500 }\n    }\n  },\n  \n  // Entity factory (for custom entity creation)\n  entityFactory: (config) =\u003e new Entity(config),\n  \n  // Debug mode\n  debug: true\n});\n```\n\n### Use ParticleSystemV1 (Legacy)\n```typescript\nimport { ParticleSystemV1 } from 'hytopia-model-particles';\n\n// Use old system if needed\nconst particles = new ParticleSystemV1(world, options);\n```\n\n## 🎮 Integration Example\n\n```typescript\n// In your game's weapon system\nclass WeaponEffects {\n  private particles: ParticleSystem;\n  \n  constructor(world: World) {\n    this.particles = new ParticleSystem(world, {\n      poolSize: 300,\n      physics: {\n        globalWind: { x: 2, y: 0, z: 0 },\n        turbulence: 0.2\n      }\n    });\n    \n    // Register weapon effects\n    this.particles.quickEffect('muzzle_flash', {\n      count: 5,\n      lifetime: 200,\n      pattern: 'explosion'\n    });\n    \n    this.particles.quickEffect('bullet_impact', {\n      count: 15,\n      pattern: 'explosion',\n      scale: 0.2\n    });\n  }\n  \n  onWeaponFire(position: Vector3Like) {\n    this.particles.spawn('muzzle_flash', position, {\n      priority: 10  // High priority\n    });\n  }\n  \n  onBulletHit(position: Vector3Like) {\n    this.particles.spawn('bullet_impact', position);\n    this.particles.spawn('smoke', position);\n  }\n}\n```\n\n## 🏆 Performance Tips\n\n1. **Use Object Pooling** - Biggest performance win, enabled by default\n2. **Set Appropriate Pool Size** - Based on your max concurrent particles\n3. **Enable Spatial Optimization** - For large worlds\n4. **Use Priority System** - Important effects spawn first\n5. **Monitor Performance** - Check poolEfficiency and adjust\n\n## 📚 API Reference\n\nSee [API Documentation](./docs/API.md) for complete reference.\n\n## 🔧 Changelog\n\n### v2.2.0\n- Added object pooling system\n- Added physics forces (wind, turbulence, vortex)\n- Added spatial optimization\n- Added TypedArray buffers\n- Simplified initialization API\n- Improved performance monitoring\n\n### v2.1.0\n- Added particle animations\n- Added new patterns\n- Added performance monitoring\n- Added YAML configuration\n\n### v2.0.0\n- Initial release with entity factory pattern\n\n## 📄 License\n\nMIT","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb3dev1337%2Fhytopia-model-particles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweb3dev1337%2Fhytopia-model-particles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb3dev1337%2Fhytopia-model-particles/lists"}