Log inGet started
World

First-person survival horror game called…

Branchmain
Branchesmain
Commit31ce1f0625

README.md

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.

  • 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; setStyleParams turns 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

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.

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

stylewhat it looks likeblenddefault area (w × h × d m)follows camera by default
firefliesyellow-green lights rising from the grass, wandering slowly, blinking on and off; glowing (bloom at night)glow30 × 4 × 30no
cherryPetalspale pink notched sakura petals tumbling and fluttering down, translucent against the sunlit30 × 12 × 30yes
autumnLeavesred, orange, gold and brown leaves with midrib and stem, swinging downlit30 × 14 × 30yes
dustMotestiny specks hanging almost still, bright where light shafts pass, invisible in shadowlit glow16 × 6 × 16no
pollensoft yellow and cream fluff floating and rising lazilylit24 × 6 × 24yes
embersorange sparks rising from the ground, flickering, burning out as they climbglow10 × 6 × 10no
snowsoft round white flakes falling slowly, swaying and turninglit30 × 14 × 30yes
mistWispsbig soft torn fog puffs drifting low over ground and waterlit40 × 3 × 40no
waterSprayfine droplets thrown up at a waterfall's foot, rainbow where the sun is behind youlit8 × 5 × 8no
ashragged grey flakes falling and turning, a few smouldering orangelit30 × 12 × 30yes
glowSporesbioluminescent teal and green motes floating and pulsing softlyglow24 × 5 × 24no
drizzlethin fast streaks of light rain leaning with the windlit30 × 14 × 30yes
sparkleslittle twinkling four-pointed stars drifting up, gold and blueglow10 × 4 × 10no
lanternSparkswarm golden sparks and glints drifting up lazily from a lantern, brazier or campfire, slower and softer than embers, twinkling out as they climbglow6 × 5 × 6no

Fields of the Drift component

Every style takes every field. All fields are synced.

fielddefaultwhat it does
style"fireflies"one of the styles above
width, height, depth0size of the area box in metres; 0 uses the style's default. The entity stands at the middle of the box's floor
density1share of the particles shown, 0..1; a change fades over fadeSeconds
fadeSeconds2how long a density change, a cross-fade or the start fade-in takes
windDirection-1degrees the wind blows toward (0 = +X, 90 = +Z); -1 uses the style's
windStrength-1wind 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
tintAmount0.7how 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)
sizeScale1particle size multiplier
brightness1glow 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
seed1which field of particles; the same seed gives every player the same particles
playingtrueoff 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.

stylehighmediumlow
fireflies480260130
cherryPetals900450220
autumnLeaves35018090
dustMotes1200600250
pollen700350160
embers25014070
snow1500750350
mistWisps704024
waterSpray1200600260
ash800400180
glowSpores400220110
drizzle1800900400
sparkles1509050
lanternSparks1408040

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's fadeTo, 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 part parts/field (birth through the box on sim.particles, a pull toward the style's fall or rise speed) and draws with shaders/driftCard (shape, facing, lighting, glow, blink, flicker, rainbow, wind, sway, wrap-around, density). Play an entry yourself with asset.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) and guides/example-a-night-garden-with-fireflies-falling-petals-and-lantern-sparks.guide (a step-by-step example level with a short fly-through film).

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 lanternSparks style; followClock and brightness; 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.y about 82 and area.y about 5, not a box centred in the ground.
  • What's new in 1.0.5: the field part and the driftCard shader 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.
  • A field's first play builds its GPU graph, and on a slow machine that takes many seconds (about a minute on a heavily loaded laptop GPU). For a moment that must show at once, such as fireflies under the moon at a fixed point in a film, start the field early at density = 0 and fade it up when it is needed: local f = Drift.start("fireflies", { ..., density = 0 }), then later f:fadeTo(1, 3).
  • 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 airDrift entries directly, pass every input as a number (areaX, centerY, windZ, tintR, ...): a play keeps only number inputs.
  • The effects preview stage (effects.capture on the effect alone) does not show these fields; check them placed in a scene in play.