What NDVDB is

NDVDB is a VDB importer and player. You author simulations in Houdini, EmberGen, Blender or any OpenVDB-compliant tool, convert the .vdb sequence once in the editor into .ndvdb, NDVDB's own GPU-ready streaming format, and play the result back in Unity as a streamed, real-time lit volume. There is no baking to flipbooks, no mesh proxy, and no cloud step.

Feature map

Requirements

What NDVDB is not

• Not a fluid simulator. It plays back simulations you author in your DCC.
• Not a runtime-authorable field. Volumes are streamed effects. You can move, scale, time-remap and light them, but not edit voxels at runtime.

One-time purchase. Full C# and shader source included. No subscription. Redistributes permissively licensed open-source components (Apache-2.0 / BSD / MIT); full notices are in the package.

Getting Started

From a fresh URP project to a playing volume in five steps. The Setup window does the project plumbing for you.

1. Import the package

   Import NDVDB into a Unity 6000.x project that uses URP. The package contains the runtime, editor tooling, shaders, and this documentation under Assets/NDimensionalGames/VDBImporter.

2. Run NDVDB Setup

   Open Tools ▸ NDVDB ▸ Setup. It checks that URP is active, that every URP renderer has the NDVDB Composite renderer feature, and that the depth texture is enabled. Each item has a one-click fix, or use Fix All Renderers.

3. Convert a VDB sequence

   Open Tools ▸ NDVDB ▸ Converter, point it at your .vdb folder, pick a quality tier and map grid roles. Convert & Import writes an .ndvdb asset and hands you a prefab with an NDVDB Player already configured. See Converting VDBs.

4. Drop the prefab in the scene

   Place it, scale it if needed, and press Play. The first frame streams instantly; the IO thread reads ahead while you watch. In the editor you can scrub without entering Play mode via the player's Preview Controls.

5. Light it

   Your directional light drives self-shadowing and scene shadows. Point and spot lights light the smoke automatically. If the sim has a flame grid, it glows with blackbody colour and can optionally emit lights. See Lighting & Fire.

Recommended scene setup

• One directional light as the main light. Its shadows are read by the march so geometry shadows the smoke and the smoke shadows the scene.
• Depth texture on for the URP asset. Setup enables it. Transparents and water sort against the smoke through it.
• HDR colour so blackbody flame and bright scatter keep their range through tonemapping.
• Keep the camera's near plane sane. Volumes the camera passes through are supported, but very small near planes waste march steps.

Where to go next

Converting VDBs

The Converter turns an OpenVDB sequence into a single .ndvdb asset: sparse bricks, per-brick quantization, temporal deltas and a lossless Zstandard envelope. It runs in the editor on every core, streams the source files once, and writes atomically.

Supported input

• A folder of numbered .vdb files (one per frame) or a single .vdb for a static volume.
• Several sequences in one folder. Files whose names differ only by their frame number form one sequence. When the folder holds more than one (two exports side by side, or an export plus a stray file), a Sequence dropdown appears under the folder on both tabs, with the largest sequence selected; one conversion takes one sequence, and the Asset Name follows the pick. A warning under the dropdown lists missing or repeated frame numbers, so a half-copied folder does not quietly become a stuttering asset.
• Standard OpenVDB float grids, and 16-bit half grids (Houdini's 16-bit float volumes, OpenVDB 13 file format 225), which are promoted to float on load. Double, integer and vector grids other than velocity are not accepted; export as float from your DCC. The converter reads with OpenVDB 13.1, so files from current Blender and Houdini releases open without version warnings.
• Any exporter that writes compliant OpenVDB: Houdini, EmberGen, Blender, Axiom, and others.
• Blender fluid caches. Blender writes its .vdb frames in domain-local space: voxel (0,0,0) is the domain's corner and the file carries no world position, so on its own a cache would pivot at that corner. The converter reads the cache's sibling config folder (config_####.uni, written with every bake) for the domain object's world matrix, the true cell size and, for adaptive domains, each frame's region, then bakes the true placement into the asset: the pivot is the Blender world origin and adaptive frames sit in one fixed lattice. (Adaptive caches need this: Blender stamps each of their frames with a different, wrong voxel size, so without the config folder they cannot be placed at all.) Point the converter at the data folder and keep config beside it when you copy a cache. A rotated domain is reported in the Console; apply that rotation to the GameObject. Blender Cache Origin (Advanced tab) turns this off.
• Up axis. Houdini and Maya are Y-up; Blender, EmberGen exports, 3ds Max and Unreal are Z-up. Source Up Axis (Advanced tab) defaults to Auto, which reads the file's creator tag and logs its choice. A Y-up file converted as Z-up lies on its side; if you already converted one that way, a −90° X rotation on the GameObject is the equivalent fix.
• Units and scale. A file unit is taken as one metre. Source Units (both tabs) rescales at import: Centimetres for Unreal-targeted exports and for EmberGen sims that were built around a centimetre FBX imported at 100%, or a custom factor. EmberGen has no fixed unit and applies an FBX's node scale but not its unit, while Unity's importer converts centimetre files to metres; importing the model into EmberGen at 1% instead of 100% makes new sims metre-true from the start. The choice becomes the header's import scale, so voxel data is untouched and the value stays editable under Import Transform in the asset inspector. Under the folder the converter shows the size sampled frames (the first with data, the middle and the last of the range) would have in the scene, and flags EmberGen exports wider than 200 m.
• Empty frames. EmberGen writes 1 KB placeholder files for frames before the first emission, and whenever nothing is emitting. They are kept as empty frames so timing is preserved and the player draws nothing for them; the scan detects grids from the first frame that holds data and says how many empty frames lead the range, and the Console's metadata-scan line counts them apart from real full opens. A range in which every frame is empty stops with an error instead of producing an asset.

Quality tiers

All tiers store voxels at 8 bits per brick with a per-brick range, which gives roughly 11 to 12 bits of effective precision. The tiers differ in how aggressively frame-to-frame deltas are pruned and whether the container is packed; the exact values are listed under Advanced tab.

Conversion speed

Conversion is a frame pipeline. Every worker thread reads a frame and then encodes whichever frame just became ready, so temporal deltas, quantization, checksums and packing of different frames run on all cores at once while the file is written in order. A 200-frame EmberGen explosion (1.3 GB of .vdb, two grids) converts in about 9 seconds from cache on a 16-thread desktop; the previous serial encoder needed just under three minutes for the same files.

• Header-only scan. The pass that establishes the sequence's domain reads each file's grid metadata (a fraction of a millisecond per file) instead of decompressing it.
• One sequential stream. Source files are streamed once, in order, through the OS cache before they are parsed, so a spinning or USB drive is never seek-thrashed. On such a drive the first read of the sequence sets the floor: about 30 seconds for 1.5 GB at 50 MB/s.
• Only the mapped grids are read. Velocity, shadow and other unmapped grids are skipped without being decompressed.
• Parallel VDB Reads (Advanced tab, auto = 4) caps how many files OpenVDB parses at once. Encoding always uses every core; file parsing stops scaling after a few threads, so this is separate from Parallel Workers. Lower it on a small laptop, raise it on a large workstation with fast storage.
• Memory is about two frames of raw bricks per worker, trimmed to 35% of physical RAM from the heaviest frame the scan saw.
• Every conversion logs one [NDVDB Converter] Profile: line to the Console with the time spent in disk, parsing, deltas, quantization, checksums, packing and writing. Read it before changing any setting.

Grid roles

NDVDB renders three roles. Map each grid in the file to one of them, or leave a grid unmapped to drop it from the output.

Output and import

• Convert & Import writes the .ndvdb file into your project, imports it as an NDVDB Asset, and creates a prefab with an NDVDB Player and a volume material.
• Asset Name and Import Folder (Simple tab). The name follows the source folder's name until you type one (clear it to go back), or the sequence's own name when the folder holds several; exporters that always use the same folder name, such as Blender's data, are the case for it. The folder defaults to Assets/NDimensionalGames/Imports/<Asset Name>; Browse picks any folder inside the project's Assets, Default returns to it. The Advanced tab has a free Output Folder and Filename for writing outside the project.
• Writes are atomic: the file appears only when complete, so a Unity import triggered mid-conversion never sees a partial asset.
• The asset inspector shows frame count, brick statistics, grid roles, and the world-space bounds and voxel size read from the VDB. Its Import Transform (a uniform scale about the simulation origin plus a translation) fixes unit and placement mismatches after import: it is patched into the header, the voxel data is untouched, and every scene player rebuilds its domain live.
• Scale and origin are preserved. Enable Use VDB Origin on the player to place the volume exactly where it sat in the simulation.

Advanced tab

The Simple tab is three presets over the controls below. Switch to Advanced when a sequence needs something the presets do not cover. Every value is baked into the asset at conversion time; nothing here is read at playback.

Source

Codec

Resolution

Output

Performance

NDVDB Player

The component that streams an .ndvdb asset from disk, keeps decoded frames in a RAM-budgeted cache, uploads the current frame into a sparse GPU atlas, and hands the volume to the compositor.

Playback

Scripting: Play(), Pause(), Stop(), TogglePlayPause(), SetFrame(int), SeekToFrame(int), SetTime(float seconds), SetProgress(0..1), PrewarmCache(), plus read-only CurrentFrame, PlaybackProgress, GetDuration(), CachedFrames, and IsComposited (true while the scene compositor drew this volume in the last frame).

Editor preview

The Preview Controls section plays, pauses, loops, frame-steps and scrubs the sequence in the Scene view without entering Play mode. Scrubbing is an undoable operation ("Scrub NDVDB Frame"), so a preview position survives an accidental change.

Streaming and memory

The Frame Cache section shows resident frames, the IO queue depth and the memory in use, so you can size the budget against your target machine.

Placement and scale

Non-uniform domains are supported. A long, thin missile trail keeps its aspect ratio and is sampled sparsely along its length.

Material

Each player renders with a material using the VDB Volume shader. Material Template is the shared source; Instance Material, on by default, gives this player its own in-memory copy of it, so one fireball can run hotter, darker or a different colour without touching the others that share the template. A player added without any material receives the package's default volume material as its template automatically, and the template auto-captures whatever VDB material you drop on the renderer. Tweaks made on the copy last for the session; make lasting looks on the template or a material variant. See Volume Material.

Override Emission Properties exposes Blackbody Tint and Blackbody Intensity on the player, which is handy when several effects share a material but one needs a hotter fireball.

Water compositing

Water Compositing chooses how this effect relates to water in the scene: Depth Sorted (default, sorts by depth like any transparent), Show Above, Show Below, or Surface Split (renders both halves). The Water page covers the modes in detail.

Proxy Mode

Proxy Mode is an editor-only layout aid: Inherit follows the session-wide Layout Mode level, or force Full, Preview, Brick or Bounds Only for this player. It never affects Play mode, recording or builds. See Layout Mode.

Volume Material

The VDB Volume shader holds the look of an effect. The compositor reads these values per volume, so every setting here applies whether the volume is drawn jointly or by the fallback path.

Density

Smoke shading

Ambient

Fire

Self-shadow and additional lights

Shadow casting onto the scene

Volumes cast real-time shadows onto geometry through a proxy ShadowCaster pass. Shadow Alpha Threshold, Shadow Filter Radius, Shadow Cast Steps and Shadow Cast Density Scale shape that projected shadow. The cast is independent of the compositor, so it works with the fallback path too.

Scene Compositor

The NDVDB Composite renderer feature raymarches every visible volume jointly in a single pass, then resolves, upsamples and composites the result with correct depth so transparents and water sort against the smoke.

Why a joint march

Drawing each volume as its own transparent object breaks the moment two effects overlap, because a whole object must be either in front of or behind another. The compositor instead gathers up to eight visible volumes per frame and marches them together, so at every sample along a ray it knows the density of all of them. Overlap, interpenetration and cross-volume shadows fall out naturally. Volumes beyond the eight slots render through the per-volume fallback path, with a one-time warning in the Console.

What happens each frame

1. Gather

   Every enabled player is collected once per frame and shared by every camera (Scene and Game views). The trace, resolve and composite passes are scissored to the screen rect the volumes actually cover, so a small effect on a big screen costs a small effect. Players entirely off screen still occupy a compositor slot and keep streaming; see the Performance Guide.

2. Light cache

   Once per frame, a compute pass evaluates main-light self-shadow, sky occlusion and ground occlusion on each volume's brick lattice. The march then fetches instead of re-marching. See Lighting.

3. Trace

   The joint march, at half resolution by default, writing colour with coverage plus a depth distribution (mean and spread) for the composite.

4. Temporal resolve

   Accumulates with the previous frame's history per camera, rejecting samples that fall outside the current view to avoid smearing.

5. Upsample and composite

   A joint-bilateral upsample to full resolution guided by scene depth, blended over the scene. A depth-occlusion write lets transparents and water that draw later sort against the smoke.

Quality settings

Shadow settings

Sorting with transparents

Performance settings

The Performance Guide explains what each of these costs and which to trade first.

Culling and the slot pool

The compositor has eight slots per frame, and a Surface Split volume takes two. With Frustum Culling on, only volumes whose bounds intersect the camera's view compete for them, so a scene can hold as many placed effects as the shot needs as long as no more than eight slots' worth are in view at once. The test uses a slightly wider frustum than the camera plus Cull Margin, so a volume is composited a step before its edge enters frame and its temporal history is primed.

Reveals never hitch. An off-screen player keeps streaming and keeps its GPU data current; it simply holds no slot and builds no light or emission cache while unseen. When the camera pans onto it, nothing has to be rebuilt. The player inspector shows "off screen" while this is the case.

When more than eight are in view, the player's Composite Priority decides who keeps a slot: higher wins, ties go to volumes already composited, then to the nearer one. The rest render through the per-volume path until the shot clears, and the Console says so once. Give a shot's hero effect a higher priority than its set dressing.

Pinning. A player's Always Composite keeps that volume in the compositor even while it is off screen: it always holds a slot and keeps its caches warm, so a camera moving faster than the reveal margin can never catch it between the per-volume path and the compositor. Pinned volumes win slot contention outright. It costs one slot while unseen, two for Surface Split, so reserve it for the hero effects of fast shots.

Without the feature

If a renderer has no NDVDB Composite feature, each player draws itself through the per-volume path in the VDB Volume shader. You keep lighting, fire and shadow casting, but lose joint overlap, cross-volume shadows and water integration. The Setup window and the player inspector both flag this state.

Lighting & Fire

How the smoke is lit, how it shadows itself and the scene, how the flame grid glows, and how fire can light the world around it.

Main light and self-shadow

The directional main light drives single scattering with a Henyey-Greenstein phase (see Anisotropy). Self-shadowing marches from each sample toward the light through the volume's own density, using Shadow Steps, Shadow Step Size and Shadow Density Scale from the material.

Light cache. With Light Cache enabled on the feature, that shadow march, the ambient sky occlusion and the ground-bounce occlusion are evaluated once per frame per volume on the brick lattice and stored in a small 3D texture. The march then does one fetch per sample. The result is identical; the saving is largest on dense, heavily shadowed smoke.

Scene shadows, both directions

• Into the smoke. Receive Scene Shadows samples the main-light shadow map once per march step, so a building or a wing casts a real shadow through a plume.
• Onto the scene. Each volume renders a proxy ShadowCaster pass so the plume darkens the ground under it. Shape it with the Shadow Cast … material properties.
• Between volumes. Cross Volume Shadows lets one effect darken another along the light direction.

Point and spot lights

URP additional lights (point and spot) light the smoke through the standard light loop, up to Max Additional Lights Per Sample. Each light is occluded by the smoke between it and the sample. That occlusion is the expensive part, and Additional Light Shadow Steps on the material lets you make it cheaper than the main-light march without disabling it.

Flame grid

A flame grid emits blackbody colour scaled by Blackbody Intensity, above Flame Threshold with a Flame Falloff curve. If a temperature grid is mapped and Use Temperature Grid for Colour is on, temperature picks the colour along the ramp (up to Temperature Range Max, by default the grid's recorded maximum) while the flame grid keeps driving intensity. Flame Illum Radius spreads that glow into the surrounding smoke of the same volume, which is how a fireball lights its own soot from inside.

Fire as an area light

With Flame Emission enabled on the feature, the flame grid itself lights the smoke: this volume's own and every neighbour's. Once per frame, for each volume, a small irradiance cache is built by tracing twelve wide cones from every cache node through the brick-mean pyramids of all volumes, accumulating the fire's emitted radiance behind the smoke's own extinction. Exposed flame reaches the volume next door; buried flame is absorbed before it leaves. The march then adds one fetch per sample.

• No hot spots and no lag. There are no point sources. The whole emitting surface contributes, and the cache is rebuilt from the current content frame, so the light moves exactly with the fire, holds when it holds, and dies when it dies.
• Smooth by construction. Emission and occlusion come from trilinear brick-mean pyramids whose footprint widens with distance, and the lattice stores a field that is already band-limited to its own spacing. Fine structure in the image comes from the sharp density at each sample, not from the light.
• The shine survives. Each node also stores the mean incoming direction and a directionality. The march blends its phase function from isotropic to Henyey-Greenstein accordingly, so smoke between you and the fire still glows more than smoke lit from behind you.
• The crisp rim stays. Flame Illum Radius remains the sharp near-field term next to a flame tongue, below the cache's brick scale.
• Colour is the material's. The fire's emission is evaluated per voxel with the material's flame threshold, falloff, flame ramp, blackbody tint and intensity, and temperature-driven colour when the material uses it, then averaged into the pyramid. A purple explosion lights its surroundings purple.
• Creative colour per material. Flame Emission Tint and Flame Emission Gain on the volume material colour and scale the glow this fire casts on smoke without changing how the fire itself renders. A hot white core can cast a deep orange glow.
• Water split volumes count once. A Surface Split player occupies two compositor slots; the emission pass treats them as one volume, so the fire never lights its own smoke twice.

Flame Lights: fire on geometry

Enable Emit Flame Lights on the player to spawn up to Flame Light Count real point lights on the fire. They are how fire reaches scene geometry: decks, walls, characters and water respond with their own albedo, specular and, if you enable it, shadows, which no screen-space trick can give in a forward renderer. Range, intensity, smoothing and flicker are per player. The lights animate in the sequence's own time, so a held frame holds them still, a scrub snaps them, and slow motion slows them.

Placed on visible fire. Each flame brick is weighted by how much of its light escapes the smoke around it, estimated from the density recorded at decode time. A light is earned, tracked and powered by that exposed fire: a blaze buried in its plume attracts no light, a light over fire that gets smothered fades in place, and a light never sits where you cannot see flame. Flame Light Exposure scales the effect; 0 restores raw flame brightness.

One job each. While Flame Emission lights the smoke, the flame lights are skipped inside the march and light geometry only, so fire never lights the smoke twice. Flame Lights Also Light Smoke on the feature restores the old behaviour. The material's Flame Emission Tint colours the lights as it colours the glow on smoke.

How flame lights are occluded. A flame light is shadowed by the smoke between the sample and the light, and by nothing behind it. The receiving volume's own density is marched only up to the light; neighbouring volumes' density is accumulated only along that same segment; the light's emitter core is excluded from both. Flame Light Occlusion Strength on the feature then scales the total (1 = as computed, 0.5 = half the optical depth, 0 = unoccluded).

Occlusion policy. Flame lights are recognised inside the march by position, so the feature's Flame Light Occlusion can treat them differently from scene lights:

Multiple scattering

Clouds

Clouds are almost pure scatterers, so the single biggest lever is the albedo you set through Smoke Absorption against Scatter Coefficient: the explosion default (8 against 4) is soot with an albedo of a third, which no amount of ambient will turn white. The shipped VDB_VolumeURP_Clouds material is a starting point: absorption 0.3, scatter 12, Anisotropy 0.55 for the silver lining, Multiple Scattering 2, ambient 0.35 in a sky blue with Ambient Sky Occlusion 0.5. Tune Density Multiplier to the asset first, then step size, then the rest.

Matching a reference render. Cloud references are lit by a whole sky and a ground, not one colour. Set Ambient Source to Scene Ambient with the reference's HDRI as the skybox: the sky term takes the probe's colour straight up and Ground Bounce (start at 0.5) the colour straight down, both occluded through the cloud, so the shading follows the skybox instead of two hand-picked colours; bring Ambient Intensity up to about 1. Add Powder (0.3 to 0.6) for the darker front-lit crevices of real cumulus. Neither costs a march when the light cache is on.

Multiple Scattering approximates the light that bounces around inside the volume before reaching the camera. It brightens dense regions toward the smoke's albedo without changing their opacity, so you can have bright white steam and pyro next to dark soot using the same density.

Water Integration

Explosions at the waterline are the shots everyone remembers. NDVDB splits the march at the rendered water surface so smoke renders correctly above, below, and through it, from either side of the surface.

Water Compositing modes

Set per effect on the NDVDB Player.

Water detection (no component needed)

With Auto Detect Water on the feature (default), NDVDB finds KWS Water System 2 and Crest Water 4 in the scene through reflection. There is no compile dependency and nothing to add. Detection provides:

• the mean water height and whether the camera is above, below or straddling the surface;
• the water system's own per-pixel surface mask (the KWS2 prepass, the Crest ocean mask), so every pixel knows which side it is on;
• the water system's surface depth, used for the wave-exact split and wave occlusion.

For any other planar water, add an NDVDB Water Surface component at the water height. It supplies the plane; the split then uses a plane test per pixel.

The wave-exact split

With Wave Exact Split (default on, active when a water system mask is available) each ray is clipped where it crosses the rendered water surface rather than a flat plane at the mean height. The above-half stops at the wave; the below-half starts there. Because the surface is read from the water system's own depth prepass, the split follows every wave point for point, and it stays correct when:

• the camera sits exactly on the waterline with the view split across it;
• an effect breaches the surface, in either direction;
• the camera crosses the surface during a shot. Each half keeps its own temporal history, so there is no flash;
• the camera is fully submerged below the troughs, looking up at crests. The post-water composite occludes at the same per-pixel surface crossing the march clipped at, so clip and presentation always agree.

Presentation. The half on the far side of the water from the camera is drawn before the water, into the opaque capture the water refracts. The half on the camera's side is composited after the water. A camera clear of the surface reduces to one side per half; a straddling camera gets both on one screen, decided per pixel by the mask. With any water source the far-side halves are drawn after the skybox, so they keep their soft edges through the surface, and with KWS2 or Crest the underwater half seen from above also carries a fog-matched depth for the surface's own depth fog (Crest's exponential fog, KWS2's absorption law): thin smoke fogs like the water behind it, dense smoke at its own distance, and the effect stays visible through deep water instead of being fogged to the seabed.

Plane mode

Without a water-system mask (generic NDVDB Water Surface) the split is a plane at the mean height. Wave Crest Compensation lowers that plane by roughly your wave amplitude so crests do not cut the above-water smoke. It has no effect in wave-exact mode, where it is unnecessary.

Underwater fog

Match Water Fog (default on) makes underwater smoke fog exactly like everything else in the water. With KWS2 the compositor applies KWS2's absorption law to the smoke. With Crest, whose underwater pass runs after the compositor and fogs each pixel at the depth it finds, the compositor presents the smoke with a fog-matched depth: a per-pixel depth chosen so that Crest's own fog, in Crest's own colour, yields exactly smoke fogged at its distance over water fogged at its own. No fog colour is ported, so edges are continuous whatever the ocean material does, and only Crest's depth fog density is read. Because Crest reads URP's depth texture rather than the live depth buffer, that depth is mirrored into the depth texture as well.

Far Side Distortion Range (default 0) is an advanced lever for the far-side half: beyond this distance the half is presented with depth cleared so the water's distortion covers it. Leave it at 0 unless you see a seam in the water system's own refraction at range.

Diagnostics

Checklist for a waterline shot

1. Player: Surface Split

   Set Water Compositing to Surface Split on the effect that breaches. Effects fully on one side can stay Depth Sorted.

2. Feature: defaults

   Auto Detect Water, Wave Exact Split and Match Water Fog on. No component needed for KWS2 or Crest.

3. Verify routing

   Tick Log Water Routing once and confirm the source and side mode in the Console.

4. Look at the seam

   Put the camera on the waterline. If a half is missing, switch the debug view to Pixel Side and check the classification matches the picture.

Timeline

A native Timeline track binds to an NDVDB Player. Clips start, loop, time-remap and scrub the sequence, in the editor and in Play mode.

Adding a track

1. Add an NDVDB track

   In the Timeline window, Add ▸ NDVDB Timeline Track. Bind it to the NDVDB Player in the scene.

2. Add clips

   Right-click the track and add an NDVDB clip. Move and trim it like any clip; the sequence plays from its first frame at the clip start.

3. Scrub

   Drag the playhead. The player seeks to the matching frame and the Scene view updates without Play mode.

4. Check the timeline's length

   In the Timeline settings keep Duration Mode at Based On Clips, or make sure a Fixed Length timeline's end marker sits past your clips. A fixed length of 0 plays for zero seconds in Play mode even though scrubbing still works.

Clip settings

A new clip snaps to the sequence's exact length: frame count divided by the frame rate in effect. Change the clip's Frame Rate Override and the clip rescales in place, taking the clip's speed multiplier into account, so the timeline always shows the true duration of what will play.

Clips support clip-in, speed multiplier, looping and extrapolation, so the standard Timeline trimming and retiming tools all apply.

Activation and memory

A player with no active clip on its track is idle: it holds its last frame or, with an Activation track controlling the GameObject, is disabled and releases its cache. For long cinematics with many effects, pair NDVDB tracks with Activation tracks so only the effects in the current shot occupy RAM and GPU atlas slots.

Timeline and Layout Mode

When a Timeline is playing, the editor's Layout Mode Auto level drops all proxies and renders at full fidelity. Scrubbing a stopped Timeline keeps the proxies, so blocking a shot stays fast. See Layout Mode.

Layout Mode

Block a VDB-heavy cinematic with cheap proxies, then get full fidelity the moment anything plays. Layout Mode never touches Play mode, recording or builds.

Levels

Where to set it

• Scene view overlay. The NDVDB overlay in the Scene view toolbar switches the session-wide level with one click. The same overlay carries the compositor and player sub-windows described below.
• Menu. Tools ▸ NDVDB ▸ Layout Mode ▸ Off / Preview / Brick / Bounds Only / Auto.
• Per player. Proxy Mode on the NDVDB Player: Inherit the session level, or pin this effect to Full, Preview, Brick or Bounds Only. Pin the hero effect to Full and let the background effects follow the session.

The level is stored in the editor session, not in the scene, so it never ships and never dirties your assets. The player inspector shows the effective level and a warning when a proxy is active.

The NDVDB overlay

One overlay in the Scene view carries everything you need while working: docked in the toolbar it is a compact strip, floated or docked to a side it expands into a dashboard with the same three sections.

• Layout. The level buttons and the Auto toggle.
• Compositor (settings icon). A live status line, "N of 8 slots, M in view, K off screen, tier", plus the feature's day-to-day levers without leaving the Scene view: Frustum Culling and Light Cache; Quality with Half Resolution, Temporal Accumulation, Temporal Feedback and Step Size; Flame Emission with its Strength, Self and Neighbours sliders; Water with Match Water Fog, Wave Exact Split and Wave Crest Compensation; the two debug views and a one-shot water routing log. Every change is undoable, one undo step per drag, and saved on the renderer feature.
• Players (memory icon; the button itself shows slots in use and the off-screen count). A table of every player in the open scenes: state (composited, off screen, per-volume, proxy, disabled), current frame, frame-cache RAM, GPU memory, and a Pin toggle for Always Composite. Click a name to select the player. Totals at the bottom.

The footer opens Setup, the Converter, and this documentation.

Performance Guide

What costs what, which levers lose nothing, and which to trade first when a shot is over budget.

Free wins (on by default)

• Light Cache. Main-light self-shadow, sky and ground occlusion once per frame per volume instead of per sample. Identical image.
• Scissor To Volumes. Every compositor pass is limited to the screen rect the volumes cover. A small effect on a big screen costs a small effect.
• Shared gather. Volume collection and uploads happen once per frame and are shared by the Scene and Game views and any extra cameras.
• Empty space skip and sparse atlas. The march walks occupancy and skips empty bricks; only occupied bricks live in GPU memory.
• Skip Overlay Cameras. Camera stacks composite once.

Flame Emission is opt-in. Its cost is one compute build per frame, about a 32³ lattice times twelve cones times up to ten steps per marched volume, and one texture fetch per sample in the march. On a desktop GPU that is a fraction of a millisecond per volume. It replaces the need for Flame Lights on smoke, so turning those off when it is on usually nets a saving.

What to trade, in order

1. Half Resolution + Temporal Accumulation

   Keep both on. This is the single largest saving and the temporal resolve hides the half-res trace on smoke.

2. Additional Light Shadow Steps

   Set 2 to 4 on the material. Point and spot light occlusion drops from the main-light shadow cost to a fraction, with the same shading.

3. Flame Light Occlusion → Cheap Mean

   The default. Use Skip when the flame lights sit inside the fireball.

4. Step Size

   Raise gradually. The march adapts to occupied length, so a larger baseline mostly affects long rays through thin smoke.

5. Cross Shadow Taps

   Drop from 4 to 2 on scenes where volumes rarely overlap along the light.

6. Max Additional Lights Per Sample

   Lower it when many small lights sit near the smoke.

7. Density Multiplier for thin sims

   A trail that needs Density Multiplier 40 to read is also a trail that terminates rays sooner. Thicker is often cheaper.

Memory

• RAM. Max Cache Ram MB caps decoded frames. The Frame Cache section of the player shows use. Sequences that fit stay resident.
• VRAM. Each enabled player holds an atlas slot sized to its densest frame. Disabled players hold nothing.
• Off-screen players take no compositor slot and build no caches, but keep their frame cache and GPU data current so they can enter frame without a hitch. Use Timeline Activation or disable them to release the memory itself.

A/B toggles

The feature's diagnostics let you measure a suspect cost without editing materials:

If the frame time barely moves with a toggle, that path is not your problem.

Rules of thumb

Builds & Deployment

Sequences deploy themselves. The build processor copies every referenced .ndvdb into StreamingAssets for Windows, Linux and macOS standalone players.

How it works

• Each NDVDB Asset references its .ndvdb file. After the build, the processor copies every sequence referenced by an enabled build scene straight into the finished build's StreamingAssets/NDVDB folder, where the runtime streams from.
• Nothing is staged through Assets/StreamingAssets. That keeps the project from doubling hundreds of megabytes per sequence and keeps the asset database from hashing them during the build.
• Unused sequences are not copied, so they never bloat the build.
• The compositor's compute shaders live in Resources inside the package and are included automatically.

Platform notes

Pre-ship checklist

1. Run NDVDB Setup

   Every renderer used by a shipped camera needs the compositor feature and the depth texture.

2. Set a RAM budget

   The default of 0 is unlimited, which is right for a few sequences. When many large sequences play together, give each player a Max Cache Ram MB that fits the minimum-spec machine.

3. Layout Mode is not a concern

   It is editor-only session state and never ships.

4. Test a build

   Confirm the sequences appear under StreamingAssets and play from a clean install path.

Troubleshooting

Start with Tools ▸ NDVDB ▸ Setup. It catches the three causes of "nothing renders" and fixes them with one click. If a problem survives this page, reach us at ndimensionalgames.com/customer-support with the Console log, your Unity and URP versions, and the exporter the VDB came from.

Settings Reference

Every inspector setting in one place, grouped by component. Defaults in grey.

NDVDB Composite (renderer feature)

NDVDB Player

VDB Volume material

See Volume Material for the grouped tables with ranges and guidance.

Water components

Timeline clip

Menus

The .ndvdb Format

A streaming container designed for GPU upload: sparse bricks, per-brick quantization, temporal deltas, and a lossless Zstandard envelope.

Layout

Bricks

8³ voxels. Only occupied bricks are stored. An indirection table maps volume space to atlas slots on the GPU.

Quantization

8 bits per voxel with a per-brick min/max range. Effective precision is roughly 11 to 12 bits because each brick uses its own range.

Temporal coding

I-frames store all occupied bricks. P-frames store bricks that changed beyond the tier's tolerance. The Cinematic tier keeps the tolerance near lossless and inserts I-frames periodically for fast seeks.

Envelope

Zstandard level 1, lossless: on brick data it lands within a few percent of the slowest levels at several times the speed. Draft skips packing entirely.

Grids

Density, flame and optional temperature, each with its own brick set and role recorded in the header.

Metadata

Voxel size, world bounds and simulation origin from the VDB, frame count and frame rate hint, each grid's maximum value (the temperature ramp's default range), per-brick means used by the light cache and cheap occlusion paths.

Streaming behaviour

• An IO thread reads and decodes Stream Lookahead frames ahead of the playhead into the frame cache.
• The GPU receives only bricks that changed since the previously uploaded frame; the atlas apron (the one-voxel border that keeps trilinear filtering seamless across bricks) is refilled incrementally for touched bricks.
• Seeking to a frame decodes from the nearest previous I-frame, which is why the Cinematic tier's periodic I-frames matter for scrubbing.

Metadata and the asset inspector

Selecting an NDVDB Asset shows the file's metadata: path, frame count and duration, value range, compressed and uncompressed sizes with the compression ratio, average frame size, source VDB and creator. Two things are editable there. Import Transform: a uniform scale about the simulation origin and a translation, applied to the bounds and voxel size when the file is read, so 0.01 turns a centimetre export into metres and an offset re-centres a domain-local cache; rotation belongs on the GameObject. The frame rate: the new value is patched into the .ndvdb header in place, losslessly and instantly, with no re-conversion, and every player and Timeline clip using the asset picks it up.

Compatibility

The container carries a format version in its header, at a fixed offset that has never moved. The reader checks it before reading anything version-dependent, so assets converted with an earlier NDVDB continue to load. Re-convert with the current version when you want the newest encoding.

FAQ & Limits