b3d-ambient

The stuff in the air, or in the water. Bubbles and motes when you're under; rain, snow, dust or drifting seeds when you're not.

Demo — dive under

Fly down into the sea (W/S pitch, R/Q throttle). The fog closes in, the light dims, and the water fills with rising bubbles and drifting motes — and it all fades back out as you break the surface.

import { b3d, b3dAircraft, b3dAmbient, b3dWater, b3dFog, b3dLibrary, b3dLight, b3dSkybox, b3dGround, gameController, inputFocus } from 'tosijs-3d'
import { demoSun } from 'tosijs-3d/demo-utils'

// A submersible scout. TWO things make the dive work, and it needs both:
//   `groundY: -40`   — the floor is the seabed, not the default 0 (which here is
//                      exactly the water surface).
//   `submersible`    — the floor SENSOR ignores the water. Without it the ray
//                      hits the surface mesh and calls it ground, so you stop
//                      dead at the waterline however low the floor is. That is
//                      right for a plane ditching in the sea and wrong here.
const scout = b3dAircraft({
  library: 'vehicles', meshName: 'scout',
  player: true, y: 9, groundY: -40, submersible: true, vtolSpeed: 6, maxSpeed: 30,
})

const scene = b3d(
  { gamepad: true },
  b3dLight({ y: 1, intensity: 0.6 }),
  demoSun(),
  b3dSkybox({ timeOfDay: 11 }),
  b3dFog({ start: 200, end: 1200, color: '#bfd9f2' }),
  b3dGround({ meshName: 'ground_nocast', width: 2000, height: 2000, color: '#4a5f3e', y: -40 }),
  // `waterSize`, NOT width/height: those are not water attributes, and an
  // unknown prop is ignored, so the sea would stay at its 128 default beside a
  // 2000-unit ground. `twoSided` because this demo's whole point is
  // descending THROUGH the surface and looking back up at it.
  b3dWater({ y: 0, waterSize: 2000, twoSided: true, follow: true }),
  b3dLibrary({ url: '/test-3.glb', type: 'vehicles' }),

  // Above the surface: dust motes in the air (visible right away). Below it: bubbles rising +
  // plankton drifting. Both RAMP with depth (the same `band` the fog uses), so diving through the
  // surface is a smooth handoff — the air empties, the sea fills with life. No `count` — it adapts.
  b3dAmbient({ preset: 'motes', where: 'above', radius: 12 }),
  b3dAmbient({ preset: 'bubbles', where: 'underwater', radius: 12 }),
  b3dAmbient({ preset: 'motes', where: 'underwater', radius: 12, color: '#2c4a58' }),

  inputFocus(gameController(), scout),
)
preview.append(scene)

tosi-b3d { width: 100%; height: 100%; }

How it works

One component, several presets, and one trick that makes all of them work:

The emitter box follows the camera. The particles do not.

Particles are spawned in a box around your head and then live in world space — so rain falls past you, motes drift by you, bubbles rise away from you. Emit them in your local frame instead and they travel with you like dandruff on the lens, which is the single most common way ambient particles are got wrong.

The box has a hole in the middle, and it matters: a box centred on the camera will happily give birth to a particle on your face, and a few-centimetre sprite half a metre from the lens is a big soft blob covering a chunk of the screen. That's not a mote, that's a smudge. Nothing spawns inside the preset's near radius (drifting in close later is fine — it's being born there that reads as dirt on the lens). Particles also fade in, not just out: born at full alpha they blink into existence, which reads as sensor noise rather than as dust.

Because the box follows you, an endless snowstorm costs a fixed number of particles no matter how big the world is. Nothing grows, nothing allocates.

It switches off rather than thinning out

An ambient effect is garnish, and garnish plays by one rule:

An effect that can't be itself switches OFF. It does not thin out.

Forty raindrops is not light rain — it's a rendering bug wearing rain's clothes. So you don't set a count; you ask. Each effect asks for the capacity its look needs and declares a minCount below which it would be a lie, and the scene divides one shared pool (sized from the measured device tier) between everyone who wants some. Effects thin together while they can all stay honest; the moment someone would drop under its floor, that one is switched off (lowest priority first) and its budget goes to the survivors. Better honest rain and no motes than two half-truths.

The pool is shared because ambient effects compete — rain, dust and motes can each be individually affordable and still cook the frame together. And if the frame stays over budget anyway, the scene shrinks the pool and effects drop out on their own. That ratchet is one-way: ambient that pops back in the moment the frame recovers, then out again at the next tree, is its own broken promise.

The cost of an effect is modelled, not measured, from what actually drives particle cost: area and blend mode (fillWeight). It cannot be measured per effect. Babylon's particle counter covers the whole scene, so an effect cannot tell its own rain from an explosion's sparks; and that counter is CPU-side while particles are GPU-bound (fill and overdraw). Timing the GPU needs EXT_disjoint_timer_query, which a Quest browser tends not to offer, so a self-measured budget would be least trustworthy on the device that needs it most. The pure allocator is allocateAmbient(requests, pool), with ratchetPool/recoverPool for the one-way shrink.

It arrives with the water, not on top of it

where: 'underwater' doesn't switch on at the surface — its emission ramps with depth using the same band() the fog uses (see b3d-fog). Submerge and the bubbles arrive as the water does. Popping a cloud of bubbles into existence at a plane is the particle version of a fog "thunk".

Presets

Leaves are the one preset that is not a sprite. A billboard always turns its face to you, which is right for something round. A leaf's whole read is that it tumbles: it flashes broadside, thins to an invisible edge, flips, shows its back. So leaves are real two-sided quads with per-particle 3-D rotation (LeafField, a Babylon SolidParticleSystem). The camera-riding box, the budget and the drain are the same as every other preset. Each leaf's sway is a flutter on top of the scene's wind, so leaves stream the same way the clouds and the water do.

Attributes