flutter3d_particles library
Particles for flutter3d: a pooled simulation, and one draw call.
An extension rather than part of the engine. Nothing in flutter3d names a
particle now — the last thread was two shader handles Renderer.create
required and no code read, so an application that draws no particles could
not start a renderer.
No Flutter. The two contributors draw through flutter3d_core's
PassContributor, not through a widget, so the whole package runs under
dart test — and flutter3d_model_core's BakeParticleSystemJobRequest
bakes a system into a cache on the Dart VM through it, the same way it
bakes a rigid body through flutter3d_physics.
The shaders stay in flutter3d_shaders. That package is already the
shared GLSL every backend compiles from — Impeller into a bundle, WebGL by
translation, and the CPU backend as Dart transcriptions — so particle.vert
living there while the simulation lives here is the arrangement that package
exists for, not a layering violation. Moving them is a five-package change
with no user-visible benefit and belongs to whenever a second extension
wants a shader of its own.
What is here
ParticleSystem is one pool for the whole application, not one per effect: a system per effect is a draw call per effect, and on this engine a pipeline change is the most expensive state change there is. Emission, ageing and ParticleAffectors advance every particle in it.
ParticleGlow and LightEmitter are the part worth having. A fire is its particles, so the light it casts is measured from them rather than produced by a second wobble running alongside — two generators of one quantity disagree eventually, and the disagreement looks like a flame burning brightly while the light it casts has gone out.
Classes
- BoxEmitter
- Anywhere inside a box. Rain over an area, dust in a shaft of light, embers rising off the whole width of a fire rather than out of one point.
- ConeEmitter
- A cone around a direction. Muzzle flashes, sparks off a wall, blood.
- CurveKey
- One point on a ParticleCurve.
- DriftEmitter
- Straight up, slowly. Smoke and dust.
- EffectBlend
- How an effect's particles combine with what is behind them. A class of constants, for EffectDrawing's reason.
- EffectDescription
- One effect of a document: the particle effect it builds, and how it is drawn and started.
- EffectDocument
-
A
.f3dfxdocument: the effects it describes. - EffectDrawing
- How an effect's particles are drawn.
- EffectRender
-
What a document says about drawing an effect:
ParticleContributor's andMeshParticleContributor's arguments, as data. - EffectSpawn
- How a trigger emits. A class of constants, for EffectDrawing's reason.
- EffectTrigger
- An effect going off when an event is published on the bus.
- EffectVocabulary
- The words a document may use beyond this package's own: emitter shapes, affector types and eases a game or a plugin defines.
- Emission
- A standing emission: what, where, how fast, and for how long.
- Flipbook
- A grid of frames, played across a particle's life.
- FlipbookCell
- One cell of the sheet, in texture space.
- GradientKey
- One point on a ParticleGradient.
- KeyEase
- How a value travels from one key to the next.
- LightEmitter
- Something whose particles are a light source.
- MeshParticleContributor
- Particle
- One particle, reused for the life of the system.
- ParticleAffector
- One thing that happens to a particle while it is alive.
- ParticleBirth
- What ParticleEmitter.emit is handed: the particle to place, and the burst it is born in.
- ParticleColorGradient
- Drives a particle's colour from a gradient.
- ParticleColorOverLife
- Moves the colour from one to another across the particle's life.
- ParticleContributor
- ParticleCurve
- A scalar over a particle's life.
- ParticleDrag
- Bleeds off speed, so a burst slows into a drift instead of flying away.
- ParticleEffect
- A recipe for a burst: what is emitted, and what happens to it.
- ParticleEffects
- The effects an engine has read from documents, the pools they emit into, and the bus subscriptions that start them.
- ParticleEmitter
- Decides where a particle starts and which way it is going.
- ParticleFade
- Fades a particle out towards the end of its life.
- ParticleGlow
- What a source's particles add up to: how much light they are, and where.
- ParticleGradient
- A colour over a particle's life.
- ParticleGravity
- Pulls particles down. Sparks and debris; not smoke.
- ParticlePlaneCollision
- Stops particles at a level floor, and throws them back up off it.
- ParticleRandom
- A reusable, re-seedable generator.
- ParticleSalt
- Which stream a draw comes from.
- ParticleSizeCurve
- Drives a particle's size from a curve, as a multiple of its birth size.
- ParticleSizeOverLife
- Scales a particle across its life.
- ParticleSpin
- Turns a billboard over its life.
- ParticleStep
- What ParticleAffector.apply is handed: one particle and the step it is advanced by.
- ParticleSystem
- Every particle in the world, and the one buffer they are drawn from.
- ParticleTurbulence
- Swirls particles through a standing flow field, so a column of smoke curls instead of rising in a straight line.
- ParticleWind
- Pushes everything one way, for a draught or the wake of an explosion.
- Range
- A range a value is drawn from when a particle is born.
- Shown
- One burst, where it happens, and which way it goes.
- SixWayLayout
- Where each of the eight six-way quantities is in a set of source images.
- SixWayMaterial
- A six-way sheet on the device, and what it emits and receives from every side.
- SixWaySheet
- A baked sheet: columns by rows cells of cell pixels, RGBA8.
- SphereEmitter
- Outwards in every direction. Explosions, and anything that bursts.
Constants
- effectDocumentExtension → const String
- The extension an effect document is saved under.
- effectsSection → const DataSection
-
A data plugin's
effects: particle effects as.f3dfxdocuments, installed into the engine's ParticleEffects.
Functions
-
bakeSixWay(
{required SixWayField density, SixWayField? emission, int frames = 16, int columns = 4, int cell = 64, double extinction = 6.0}) → SixWaySheet -
Bakes
framesframes ofdensityinto a sheet, cells in reading order. -
easeShape(
double t, KeyEase ease) → double -
Applies
easeto a fraction already normalised into[0, 1]. -
importSixWay(
{required List< Uint8List> images, required int width, required int height, int columns = 1, int rows = 1, SixWayLayout layout = SixWayLayout.positiveNegative, bool flipCells = true}) → ({Uint8List negative, Uint8List positive}) -
Repacks RGBA8
imagesofwidthbyheight, laid out bylayout, into the engine's positive and negative textures. -
smokePuff(
{int seed = 1}) → SixWayField - A puff of smoke that billows out and thins over its life — the engine's own, so a six-way particle has something to show with no asset at all.
Typedefs
-
EffectAffectorReader
= ParticleAffector Function(Map<
String, Object?> json) - Reads an affector of a type this package does not have, from its JSON.
-
EffectEmitterReader
= ParticleEmitter Function(Map<
String, Object?> json) - Reads an emitter of a shape this package does not have, from its JSON.
- EffectPlace = ({Vector3 at, Vector3? direction})
- Where an effect goes off, and which way it leans.
- EffectPlacer = EffectPlace? Function(BusEvent event)
-
Places
eventfor an effect it triggers, or returns null to leave it toPlacedEventand the trigger. - SixWayChannel = ({int channel, int image})
-
One channel of one source image:
imagecounts from nought,channelis r, g, b, a as nought to three. - SixWayField = double Function(double x, double y, double z, double t)
-
Density at a point of the cube from −1 to 1 on every axis, at
tthrough the animation from nought to one. Nought is empty; one is as thick as the bake's extinction.
Exceptions / Errors
- EffectFormatException
- An effect document that cannot be read, with the sentence that says why and where.