ambientDrift
Put living air in any scene with one component.** Fireflies blinking over a pond at night, cherry blossom petals tumbling past a shrine, autumn leaves swinging down, dust motes glittering in a sunbeam, embers rising off a fire, snow, low mist creeping over the water, fine spray a…
ambientDrift: fireflies, falling petals, snow, embers, lantern sparks and other drifting air particles
Put living air in any scene with one component. Fireflies blinking over a pond at night, cherry
blossom petals tumbling past a shrine, autumn leaves swinging down, dust motes glittering in a
sunbeam, embers rising off a fire, snow, low mist creeping over the water, fine spray at the foot
of a waterfall with a rainbow in it, falling ash, glowing bioluminescent spores, a light drizzle,
magic sparkles, warm sparks rising lazily off lanterns and fires. Fourteen styles, all driven the same
way, and they can follow the time of day of worldClockKit's WorldClock. To use it, install
ambientDrift from ZeroMind (search "ambientDrift fireflies petals", or zero zeromind installAsset a0101ddf-98e9-4367-8489-6169dd045dd1), add a Drift component with style = "fireflies" to an entity in
your scene and press play; change style to any of the fourteen to swap it.
- Real sprites, not squares. Petals are notched sakura petals that tumble in 3D and glow pink when the sun is behind them; leaves have a midrib and stem in red, orange, gold and brown; snow is a soft flake; ash is a ragged grey flake, a few still smouldering. Glowing styles (fireflies, embers, spores, sparkles, lantern sparks) give off HDR light with a hot core and a coloured halo, and never shrink below a couple of pixels, so a firefly 40 m away is still a bright point, by day or by night, and bloom catches them.
- Lit by your scene. Lit styles take the sun and its shadows, the sky's ambient light and every lamp in reach, so petals turn warm next to a stone lantern and dust only shows where light falls.
- Cheap. Particles live on the engine's GPU particle solver (
sim.particles); wind, sway, spin, blinking, wrap-around and lighting run in one shader. No Luau runs per particle: a field costs a handful of input changes when you change something, and nothing at all otherwise. - The same for every player. Every field is seeded; the component's fields are synced.
- Light on phones and tablets.
quality = "auto"picks fewer particles in a browser and on touch devices (tiers below). - Made for films too.
fadeTo(density, seconds)starts the petals or raises the fireflies on a cue;setStyleParamsturns up the wind, changes the mood or tints the field mid-shot.
Install
Install ambientDrift from ZeroMind into your world. It brings no other packages.
Add fireflies in one step
In your scene's build.luau, inside content(), so the field is part of the scene and comes back on
every load (a brand-new world opens on its starter scene, /source/scenes/main.scene):
local e = entity.spawnSynced("Fireflies")
e.transform.position = vector.create(0, 0, 0) -- the middle of the area's floor
e.component.add("Drift", { style = "fireflies" })
Press play. Change style to any style below and the same entity shows that instead. The first
field of a session can take a while to appear on a busy machine (see Known limits); after that a
field shows at once. Lit styles (petals, snow, leaves) are pale and read best against sky, foliage
or a darker ground; on a white floor at noon look up to see them.
From code: start, fade, change, stop
local Drift = require("ambientDrift.api")
local petals = Drift.start("cherryPetals", { position = vector.create(0, 0, 0), density = 0 })
petals:fadeTo(1, 4) -- start the petals over 4 s
petals:setStyleParams({ mood = "windy", windDirection = 90 }, 2)
petals:setStyleParams({ tint = "#ffd0e0", tintAmount = 0.5 })
petals:stop(3) -- fade out over 3 s and end
A field started this way is local to the peer that starts it (call it on every peer, or use the
component for a shared one). Drift.forEntity(e) returns the live field a Drift component is
playing on e, with the same fadeTo, setStyleParams, stop and get.
Styles
| style | what it looks like | blend | default area (w × h × d m) | follows camera by default |
|---|---|---|---|---|
fireflies | yellow-green lights rising from the grass, wandering slowly, blinking on and off; glowing (bloom at night) | glow | 30 × 4 × 30 | no |
cherryPetals | pale pink notched sakura petals tumbling and fluttering down, translucent against the sun | lit | 30 × 12 × 30 | yes |
autumnLeaves | red, orange, gold and brown leaves with midrib and stem, swinging down | lit | 30 × 14 × 30 | yes |
dustMotes | tiny specks hanging almost still, bright where light shafts pass, invisible in shadow | lit glow | 16 × 6 × 16 | no |
pollen | soft yellow and cream fluff floating and rising lazily | lit | 24 × 6 × 24 | yes |
embers | orange sparks rising from the ground, flickering, burning out as they climb | glow | 10 × 6 × 10 | no |
snow | soft round white flakes falling slowly, swaying and turning | lit | 30 × 14 × 30 | yes |
mistWisps | big soft torn fog puffs drifting low over ground and water | lit | 40 × 3 × 40 | no |
waterSpray | fine droplets thrown up at a waterfall's foot, rainbow where the sun is behind you | lit | 8 × 5 × 8 | no |
ash | ragged grey flakes falling and turning, a few smouldering orange | lit | 30 × 12 × 30 | yes |
glowSpores | bioluminescent teal and green motes floating and pulsing softly | glow | 24 × 5 × 24 | no |
drizzle | thin fast streaks of light rain leaning with the wind | lit | 30 × 14 × 30 | yes |
sparkles | little twinkling four-pointed stars drifting up, gold and blue | glow | 10 × 4 × 10 | no |
lanternSparks | warm golden sparks and glints drifting up lazily from a lantern, brazier or campfire, slower and softer than embers, twinkling out as they climb | glow | 6 × 5 × 6 | no |
Fields of the Drift component
Every style takes every field. All fields are synced.
| field | default | what it does |
|---|---|---|
style | "fireflies" | one of the styles above |
width, height, depth | 0 | size of the area box in metres; 0 uses the style's default. The entity stands at the middle of the box's floor |
density | 1 | share of the particles shown, 0..1; a change fades over fadeSeconds |
fadeSeconds | 2 | how long a density change, a cross-fade or the start fade-in takes |
windDirection | -1 | degrees the wind blows toward (0 = +X, 90 = +Z); -1 uses the style's |
windStrength | -1 | wind in m/s before mood; -1 uses the style's |
mood | "normal" | calm (wind ×0.4, sway ×0.6), normal, windy (wind ×2.4, sway ×1.6) |
tint | "" | colour override "#rrggbb"; empty keeps the style's colours |
tintAmount | 0.7 | how much of tint replaces the style's colours, 0..1 |
followCamera | "auto" | on wraps the field around the camera wherever it goes; off keeps it in its area; auto uses the style's default |
quality | "auto" | auto, high, medium, low (counts below) |
sizeScale | 1 | particle size multiplier |
brightness | 1 | glow and light multiplier |
followClock | "off" | auto follows the time of day of worldClockKit's WorldClock when the scene has one (see below); off ignores it |
seed | 1 | which field of particles; the same seed gives every player the same particles |
playing | true | off fades the field out and stops it; on starts it again |
api.start(style, opts) takes the same settings as options: root or position,
area = { x, y, z }, density, windDirection, windStrength, mood, tint ("#rrggbb" or
{ r, g, b } in 0..1), tintAmount, follow (boolean), quality, seed, sizeScale, brightness,
followClock ("off" | "auto"), fadeIn.
Follow the time of day (worldClockKit)
Set followClock = "auto" (or followClock = "auto" in api.start options) and the field follows
the scene's worldClockKit WorldClock:
- Night styles (
fireflies,glowSpores,lanternSparks) fade in at dusk, glow brighter as it gets darker and fade out at dawn. - Day styles (
dustMotes,pollen,cherryPetals) do the opposite: they come out in the morning and fade out as night falls. - Other styles are not changed by the clock. Lit styles always take the scene's light, which the clock drives, so petals and snow dim with the evening by themselves.
worldClockKit is optional: ambientDrift does not depend on it. ambientDrift.clock looks for a
WorldClock component on any scene entity (from a direct install or a copy another kit brought) and
asks that copy's timeofday.darkness(). With no WorldClock in the scene, followClock changes
nothing and every field plays at full.
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 10 }) -- worldClockKit
entity.spawnSynced("Fireflies").component.add("Drift", { style = "fireflies", followClock = "auto" })
entity.spawnSynced("Dust").component.add("Drift", { style = "dustMotes", followClock = "auto" })
Quality tiers and particle counts
auto picks low on Android and in a touch browser (tablets, phones), medium in a desktop
browser, high in the native app (medium if it has a touch screen). Counts are particles alive at
once at full density.
| style | high | medium | low |
|---|---|---|---|
| fireflies | 480 | 260 | 130 |
| cherryPetals | 900 | 450 | 220 |
| autumnLeaves | 350 | 180 | 90 |
| dustMotes | 1200 | 600 | 250 |
| pollen | 700 | 350 | 160 |
| embers | 250 | 140 | 70 |
| snow | 1500 | 750 | 350 |
| mistWisps | 70 | 40 | 24 |
| waterSpray | 1200 | 600 | 260 |
| ash | 800 | 400 | 180 |
| glowSpores | 400 | 220 | 110 |
| drizzle | 1800 | 900 | 400 |
| sparkles | 150 | 90 | 50 |
| lanternSparks | 140 | 80 | 40 |
require("ambientDrift.styles") holds this table (count(style, quality), autoTier()).
What is in the package
Drift(component): the field on an entity, synced for every player.api(module):start,forEntity, and the handle'sfadeTo,setStyleParams,stop,get.styles(module): every style's counts per tier, default area, wind, follow setting and whether it is a night or day style.clock(module):darkness()from the scene's worldClockKit WorldClock, or nil with none.airDrift(effect): one entry per style. Each style graph calls the shared partparts/field(birth through the box onsim.particles, a pull toward the style's fall or rise speed) and draws withshaders/driftCard(shape, facing, lighting, glow, blink, flicker, rainbow, wind, sway, wrap-around, density). Play an entry yourself withasset.resolve("ambientDrift.airDrift", "effect"):play("snow", { root = e, inputs = { ... } }); every input is a number.- Guides:
guides/how-to-add-fireflies-falling-cherry-petals-snow-dust-and-embers.guide(how to use every style and field, swapping the style with one change) andguides/example-a-night-garden-with-fireflies-falling-petals-and-lantern-sparks.guide(a step-by-step example level with a short fly-through film).
Known limits
Three engine problems can catch you out with particle fields. They come from the engine, not from ambientDrift, and each is tracked under the engine issue named below. Last checked with ambientDrift 1.0.11 on 2026-11-16, in the Tsukimichi film.
- When a lot of effects start at once, one can take tens of seconds to appear (engine issue
#26337). What you see: the field is playing and its code reports it as live, but the air is
empty, and the particles pop in tens of seconds later (on a loaded machine, over a minute). It
happens the first time a field plays in a session, when other fields or effects start in the
same moment. Once a field has shown, it shows at once every later time in that session. In
Tsukimichi, five fields start together when the film opens. On a freshly opened world, the
fireflies faded up at 1:24 only showed at about 1:48, after their shot had ended. On the
second showing of the film they rose right on cue.
What to do: start a field well before its moment, hidden, with
local f = Drift.start("fireflies", { ..., density = 0 }), and fade it up withf:fadeTo(1, 3)when it is needed. Start as few fields at the same moment as you can. This shortens the wait but does not remove it, so for a moment that must be right (a film, a reveal), watch it in a freshly opened world, never only after a replay. - Editing an effect while it plays can make it vanish for a while (engine issue #20054).
What you see: you save a change to
airDrift.effect(a style's graph, a part or thedriftCardshader) during play, and every field of that style disappears until it has rebuilt. The gap is usually a few seconds; on a loaded machine (2026-11-16) the fireflies took about a minute and a half to come back. Changing a field from code (fadeTo,setStyleParams, the component's fields) does not do this. What to do: make effect edits in edit mode, or wait the gap out. A field that vanished right after an edit is not broken. - A field that starts during a frame-by-frame recording can be missing from the video
(engine issue #26301). What you see: in a video recorded with
cadence = "frame", a field that is first built, or faded, while the take runs is not there, although it plays fine live. What to do: play the film through once first so every field is built, set each field to the strength it has in the film before the take, and skip the fades while recording. filmRig's makeAFilm workflow (stage 9) walks through it, and a cue module can hold the fields the same way (Tsukimichi'sfilm/cueshasholdForRecording()).
Good to know
- Put the entity anywhere. The area box is centred on the entity wherever it stands (a hillside, a rooftop, a terrace far from the origin); the entity is the middle of the box's floor.
- Far particles stay visible. Every particle keeps a smallest on-screen size of about two pixels (glowing ones a little more), paying for it in opacity, so fields read at 5 to 40 m.
- What's new in 1.0.1 and 1.0.2: fields now stand where their entity is (1.0.0 centred every box on the
world origin, which hid fireflies and embers placed anywhere else); glowing styles are brighter,
more saturated and keep a minimum size; fireflies are lit about half of each blink; the
lanternSparksstyle;followClockandbrightness; 1.0.2 keeps glow colours readable against bright skies. - What's new in 1.0.4: fireflies are larger and glow brighter (they read as clear points of
light around a torii under the moon instead of specks); cherry petals, pollen and dust motes are
a little larger, and dust and pollen catch more light, so they read in a 1080p film frame.
Tip: place a ground-hugging field (fireflies, mist, spores) with its box ON the ground, e.g. a
terrace at y 80 wants
position.yabout 82 andarea.yabout 5, not a box centred in the ground. - What's new in 1.0.5: the field part and the
driftCardshader are back to the 1.0.3 code. 1.0.4 also carried an untested change to how cards are sized for culling; it is taken out again so only proven code ships. The 1.0.4 sizes and glow stay. - What's new in 1.0.6: the two superseded guides (
add-drifting-particles,night-garden-example) are removed; the how-to and the night-garden example guide replace them. Built on the current engine library. - What's new in 1.0.7 and 1.0.8: the README says how to record a film with particle fields frame by frame (build every field first, hold each at its film strength, skip the fades during the take); 1.0.8 adds this changelog line.
- What's new in 1.0.9: built on the current engine library, so a kit that installs ambientDrift (such as lanternStair) and is published from a world on that library uses this release as is, one copy, instead of carrying its own.
- What's new in 1.0.10: the preview images and the field part's compiled graph are the ones the current engine library computes. 1.0.9 shipped them stale, so every world on that library computed its own and its copy no longer matched the release; a kit published from such a world then carried an incomplete copy of ambientDrift (no code), and its particles did not load.
- What's new in 1.0.11: the same content as 1.0.10, released as an ordinary commit of this world. 1.0.10's latest release was the merge of a pull request, and a kit naming ambientDrift as a dependency (lanternStair) placed that release without its code; this release is the one such a kit now takes.
- What's new in 1.0.12: a "Known limits" section on the engine problems a creator can hit with particle fields, and what to do about each. No code changes.
- What's new in 1.0.13: from a newcomer's install in an empty world. The quick start now says
where its lines go (the scene's
build.luau, insidecontent(); a new world's starter scene is/source/scenes/main.scene), that the first field of a session can take a while to appear, and that pale lit styles read best against sky or a darker ground. Built on the current engine library. No other code changes. - What's new in 1.0.14: built on the current engine library (b45137c). No change to the particles. Released so the kits that depend on ambientDrift (lanternStair 1.4.4) pin one clean, newest release, and a world that installs them holds a single ambientDrift copy.
- What's new in 1.0.15: built on the current engine library (c98faf2). No change to the particles. lanternStair 1.4.9 is built on this release, so a world that installs both holds one ambientDrift.
- What's new in 1.0.21: the 1.0.20 near-camera fade now reaches every field. 1.0.20 changed only the card shader, and the fourteen particle graphs (and the field part) kept their recorded pin to the shader as it was, so a fresh install loaded the old shader for them beside the new one: two copies, and no fade near the camera. Every file that names the shader is recorded against the current one again, so one shader is installed and every field (fireflies, petals, leaves, embers, snow and the rest) fades out next to the camera. No other change.
- What's new in 1.0.20: no more one-frame particle blobs next to the camera. A firefly, petal, leaf or ember that drifted right past the lens used to fill the frame for the one frame it crossed the eye, a bright flash or a white streak. Every card now fades out smoothly as it comes within 1.8 m of the camera and is gone by 0.45 m, so particles near the camera move and fade smoothly and never flash. Farther ones are unchanged.
- What's new in 1.0.19: the opening paragraph (what ZeroMind shows on the package's card) says how to install it and add the first field. No change to the particles.
- What's new in 1.0.18: built on the current engine library (ca6727b). No change to the particles. lanternStair 1.6.1 is built on this release, so a world that installs both holds one ambientDrift.
- What's new in 1.0.17: built on the current engine library (2c02fe3). No change to the particles. lanternStair 1.6.0 is built on this release, so a world that installs both holds one ambientDrift.
- What's new in 1.0.16: built on the current engine library (33551d3). No change to the particles. lanternStair 1.4.10 is built on this release, so a world that installs both holds one ambientDrift.
- Following the camera wraps the field in a box around the camera, so snow or petals are everywhere you go without filling the world. Ground-hugging styles (fireflies, mist, spores, embers) keep their floor 1.6 m below the camera when they follow.
- Wind, mood, size and follow changes cross-fade: the field dips out and back in over the fade time, because the drift is computed on the GPU from the clock and cannot be re-aimed in place. Density and tint change in place.
- Night: glowing styles need the scene's bloom to halo; lit styles take whatever light the scene has, so at night petals and snow show where moonlight, sky light or lamps reach them.
- Effect inputs are numbers. When playing
airDriftentries directly, pass every input as a number (areaX,centerY,windZ,tintR, ...): a play keeps only number inputs. - The effects preview stage (
effects.captureon the effect alone) does not show these fields; check them placed in a scene in play.
Scoped to this part · feeds back into the world's score.