particle_core #

Core engine for particle effects in Flutter. High-performance physics, single GPU draw call rendering, and full customization.

You probably want particle_text or particle_image instead — they provide ready-to-use widgets built on this engine.

What's inside #

• ParticleSystem — physics engine with spring forces, pointer repulsion, and text/image rasterization
• ParticleConfig — full configuration: colors, density, physics, fonts, presets
• ParticlePainter — high-performance renderer using Canvas.drawRawAtlas (single GPU draw call)
• Particle — data model for individual particles

Use this package if #

• You want to build a custom particle widget on top of the engine
• You need direct access to the physics system
• You're creating a new particle effect type beyond text and images

Getting started #

dependencies:
  particle_core: ^0.2.0

ParticleConfig options #

Built-in presets #

How particle count works #

Particle count is determined by particleDensity × content area:

count = contentArea × particleDensity / 100,000

• Content area = text bounding box (width × height) or image drawn area — NOT the full screen
• Larger fontSize → bigger bounding box → more particles automatically
• Multi-line text → taller bounding box → more particles
• sampleGap controls how many target positions are sampled (lower = denser pixel targets)
• fontSize is responsive when null — auto-scales with widget size (32–200 px)

To force an exact count: ParticleConfig(particleCount: 6000)

Max count behavior: When maxParticleCount is left at its default (50,000), the density-based count is allowed to exceed it. The cap only applies when you explicitly set a custom maxParticleCount.

Responsive resize #

Both ParticleText and ParticleImage detect widget size changes (e.g. window resize, orientation change) and automatically re-rasterize content and reposition particles at the new size.

Dark image pixel visibility #

Image particles with very dark/near-black source colors (luminance < 80) have their brightness automatically boosted while preserving hue and saturation. This ensures logos and text within images remain visible as particles regardless of background color.

Performance #

particle_core renders all particles in a single GPU draw call using Canvas.drawRawAtlas. This means 10,000+ particles run smoothly at 60fps — compared to traditional drawCircle -per-particle approaches that start lagging at 1,000.

Other optimizations:

• Pre-allocated Float32List/Int32List buffers — zero GC pressure per frame
• Squared-distance checks — avoids sqrt in physics hot loops
• ChangeNotifier-driven repainting — no setState, no widget tree rebuilds
• RepaintBoundary isolation — only the canvas layer repaints
• Pre-rendered sprite texture — 32×32 soft glow circle created once, reused every frame

License #

MIT License. See LICENSE for details.