Unity Packages / Nebula

Nebula

Add Nebula to your renderer

Select the Universal Renderer Data asset used by your camera. Nebula needs both a renderer feature and an enabled Volume override; this page adds the renderer feature.

Use a Unity 6 URP project with RenderGraph enabled. The package declares Unity 6000.0.5f1 and URP 17.0.4 as its minimum package versions. Built-in, HDRP, 2D Renderer, XR, and overlay cameras are outside this setup. See platform requirements before choosing a build target.

1. Click Add Renderer Feature and choose Volumetric Lighting Renderer Feature.
2. Keep the feature’s checkbox enabled. Expand its row to see the Nebula settings.

Figure 1

The feature assigns its packaged Shader Data automatically and starts at Medium quality. Your scene will receive fog after you create the profile on the next page.

Create the fog profile

1. Add a Volume component to an empty GameObject and name it Global Volume. Set Mode to Global, then click New to create a profile.

Figure 2

2. In the profile, click Add Override, search for Volumetric Lighting, and select the result. The profile now contains Nebula’s fog controls.

Figure 3

A Unity Volume chooses settings for a camera. It does not define a visible fog shape; use a local fog volume when you need a bounded pocket of fog.

Enable fog and check the result

1. In Volumetric Lighting, click ALL to override the displayed settings, then turn on the value checkbox beside Enabled. The left checkbox allows the profile to supply a value; the checkbox in the value column turns Nebula on.
2. Leave Global Fog Density at 2 and Scattering Intensity at 1 for this first check.

Figure 4

Enter Play mode in a lit scene with objects at different distances. Increase Global Fog Density to 6 for the denser result shown below: distant columns fade into fog lit by a warm Directional Light. The light needs no extra Nebula component.

Figure 5

If the image stays clear, check missing fog. For a fuller scene, continue with Nebula Demo.

Open a sample

Open Nebula in Window > Package Manager, then select Samples. Use Import beside the sample you want. Unity shows Update when an older copy is already present, as in this capture.

Figure 6

Open Assets/Samples/Nebula/1.2.0/Nebula Demo/Nebula Demo.unity to start with the four-part demo. Each imported sample includes its own PDF. Importing a sample does not add Nebula to your renderer.

Set the fog’s appearance

Edit the Volume Profile that controls your camera. Enable the left override checkbox beside each setting you change; Volume weight and priority blend these values like other URP overrides.

Figure 7

Global Fog Density: Higher values obscure more of the scene. 0 removes the global medium while local volumes can remain. The default is 2; 1 in this Inspector means 0.01 extinction per world unit in C#.

Scattering Intensity: Brightens light scattered by fog. It does not change how much background light the fog absorbs or how much light the fog emits.

Global Scattering Albedo: Tints the scattered light. Black absorbs without scattering; white scatters all of the extinction coefficient.

Global Emission: Adds HDR light inside the fog. It needs nonzero density, ignores alpha, and does not illuminate nearby geometry. A nonblack value still glows with Scattering Intensity at 0.

Scattering Distribution: 0 scatters evenly. Positive values strengthen light seen toward its source; negative values favor the opposite direction. The range is -0.9 to 0.9, with a default of 0.2.

Keep fog near the ground

Enable Use Global Height Attenuation, choose Bounded, and leave Height Reference at World. Set Fog Minimum Height to 0 and Fog Maximum Height to 8 for a layer that fades out eight world units above the origin.

Figure 8

Density is full below the minimum and reaches zero at the maximum. A larger Height Attenuation Factor thins the transition sooner.

The Depth controls are camera-relative: Start Distance leaves a clear foreground, Near Fade Distance softens its start (0 disables the fade), and Maximum Distance ends the represented fog interval. Keep the maximum beyond the start.

Use a gradual height falloff

For a layer without a hard upper edge, enable Use Global Height Attenuation and choose Height Profile > Exponential. With Height Reference > World, set Fog Base Height to 0 and Attenuation Distance to 5.

Figure 9

Fog keeps full density at and below the base. At 5 world units above it, about 37% remains; at 10 units, about 14% remains. A larger attenuation distance makes the vertical falloff gentler. The minimum distance is 0.01.

This profile shapes the global fog. Each local volume can use its own height and noise settings.

Supply terrain heights

Add one Fog Terrain Height Field component to an empty GameObject. Use one enabled provider across your loaded scenes, and keep the selected Unity Terrain tiles axis-aligned with unit scale.

1. Expand Terrains, set its size, and assign every tile that should supply ground height.
2. Choose Resolution. The sample uses Resolution 512; the component default is Resolution 1024.

Figure 10

The Inspector reports the covered area, texture dimensions, estimated memory, and world units per texel. Larger resolutions follow small terrain features more closely and use more memory. The longest axis uses 256, 512, 1024, or 2048 samples; the other axis follows the coverage aspect ratio.

Height and hole edits on selected tiles request a rebuild automatically. Click Refresh Height Field after a change that did not notify Unity’s Terrain callbacks. Mesh ground and baked height-field assets are not inputs to this component.

Make fog follow the terrain

After supplying terrain heights, enable Use Global Height Attenuation on the fog profile. Select Exponential and Height Reference > Terrain. The example keeps full density up to Fog Base Height 2.5 above the ground, then fades with Attenuation Distance 6.

Figure 11

Outside Terrain > Suppress Fog clears this contribution outside assigned tiles and over holes. Use World Height evaluates the same profile against world height there.

A valid active terrain field removes all fog below the ground, including local fog that has no height attenuation. Above ground, global and local profiles still shape their own contributions.

Place a local fog volume

Create an empty GameObject and add Volumetric Fog. You can also use GameObject > Effects > Nebula - Local Fog Volume; that command starts with a box scaled to 10 on each axis.

Set the Transform to place, rotate, and size the fog, then choose Shape. A Box fills its transformed unit cube; an Ellipsoid fits inside the same bounds.

Figure 12

Set Fog Density above 0 and use Boundary Fade to soften the edge. In the illustrated ellipsoid, scale (8, 4, 8) gives an eight-unit width and a four-unit height.

Local fog needs the enabled Volume override even when global density is zero. The renderer’s Enable Local Fog Volumes switch must also be on; see rendered content.

Blend fog and clear a space

Use Additive to build a denser patch on top of the global fog. Use Replacing to blend the accumulated fog toward this volume’s medium; a Replacing volume with Fog Density 0 can clear a room or corridor.

Figure 13

Blend Priority: Lower values are evaluated first. Give overlapping volumes different priorities when their order matters. Higher-priority volumes can change the result left by earlier volumes.

Boundary Fade: Softens the transition at the shape boundary. In Replacing mode, the edge gradually returns to the surrounding fog instead of abruptly cutting it away.

Radial Fade Start: Sets where fading from the center begins. 1 disables this extra fade. Use a lower value for a softer center-to-edge distribution.

Color tints scattered light. Emission adds density-dependent glow; black emission in a full-strength Replacing volume clears underlying glow. Excluded temporarily removes this volume’s contribution without removing the component.

Animate and shape a local patch

On Volumetric Fog, enable Height Attenuation for a vertical profile, or Noise Attenuation for moving density variation. These settings affect this volume.

Figure 14

Height Profile uses the bounded or exponential behavior described earlier. Height Reference uses world height or the shared terrain field, even when the volume is rotated.

Noise Frequency: Larger values create smaller features. Noise Wind Direction (1, 0, 0) moves along world X; Noise Wind Strength 0 freezes movement. Direction magnitude also scales the speed.

Enable Override Anisotropy to give this patch its own Scattering Distribution. Otherwise it inherits the global value. Local height and noise also require their renderer switches.

Animate the global fog

In the Volume Profile, enable Use Global Noise Attenuation. Noise reduces the global medium in a moving pattern; it does not replace the independent settings on local volumes.

Figure 15

Noise Frequency: Higher values make finer variation. The global control has a minimum of 1; the local-volume control accepts smaller positive values for broader features.

Noise Wind Direction: A world-space vector. (1, 0, 0) moves along X. Its length is preserved, so doubling the vector length doubles movement speed.

Noise Wind Speed: Multiplies that direction in world units per second. 0 holds the pattern in place. Keep the toggle off when you want uniform global fog and do not need procedural noise evaluation.

Control a light’s fog contribution

Directional, Point, and Spot lights contribute automatically when visible to the camera. Add Volumetric Realtime Light to a Light only when you need the controls below.

Figure 16

Excluded: Keeps this light on opaque geometry while removing its contribution to Nebula.

Volumetric Scattering Intensity: Scales only this light’s fog contribution. 1 preserves it; 0 removes it. It does not change the Unity Light intensity used on surfaces.

Temporal Responsiveness: Values toward 1 favor current lighting over history around this light. Use it for a moving spotlight or flashing light that leaves trails. More immediate response gives up some temporal smoothing.

Nebula uses URP realtime shadows and supported cookies. The light’s layer must be visible to the camera, and their culling masks must overlap. Non-main lights and cookies also depend on the renderer content switches. Area lights do not contribute.

Separate lit and shadowed fog

In the Volume Profile, use Density In Light and Density In Shadow to change thickness according to light visibility. Both default to 1. Try 1 and 0.2 respectively for clearer shadows. Enable both checkboxes beside Additional Light Density to include point and spot lights; otherwise, only the main light selects the density.

Figure 17

0 removes density in that region; values above 1 thicken it. These multipliers affect global and local extinction, scattering, and emission together. They do not classify regions by light brightness.

For an authored palette, set Lit Fog Color and Shadowed Fog Color, then raise Artistic Color Influence. 0 keeps incident lighting; 1 replaces all incident fog lighting, including additional-light contributions and directional phase lighting, with the selected HDR color. Albedo and density still shape the result. Emission is unchanged by these color controls.

Additional Light Density: Off by default. Includes point, spot, and additional directional lights. Ranges, spot cones, shadows, and cookies determine coverage independently of brightness. Overlaps use the strongest coverage; outside all lights, Density In Shadow applies.

It reuses fog-lighting samples but adds shadow and cookie sampling for temporal density validation when the two multipliers differ. Both at 1 preserve density without that extra sampling. Additional lights must also be enabled in the Nebula Renderer Feature.

With this mode off, density controls still need a participating main light. The artistic color controls always use only the main light; an absent, excluded, or camera-filtered main light leaves those colors inactive.

Open the Lit and Shadow Density or Lit and Shadow Colors sample for editable comparisons. Soft shadows, shadow-distance fading, and cookie coverage make gradual transitions.

Fog transparent materials

Nebula composites the opaque scene and sky before transparencies. A stock URP transparent shader does not sample fog at its own surface depth.

1. On the material, choose Shader > Nebula > Transparent Lit Fog.
2. Set Blending Mode to Alpha, Premultiply, or Additive, then set the Base Map color and its alpha. This shader is always transparent.

Figure 18

Keep Enable Transparent Fog on in the renderer feature. It publishes the fog data these shaders sample.

Figure 19

Use Nebula/Transparent Unlit Fog for a simple straight-alpha unlit material. Multiply blending and general refraction need separate integration. The supplied Lit shader has no motion-vector passes. Without published Nebula data, Lit returns to its URP lighting and fog path; the Unlit helper leaves its input color unchanged.

Integrate a custom transparent shader

The supplied Nebula Transparent Fog subgraph accepts final scene-linear RGB from a transparent Unlit Shader Graph or another graph that already computes its final color. A standard Lit graph computes lighting after its Base Color input, so use Transparent Lit Fog for that case.

The subgraph lives at Runtime/Shaders/Transparent/Nebula Transparent Fog.shadersubgraph inside the Nebula package. Its inputs are straight RGB and Alpha. Its outputs are Straight Alpha RGB, Premultiplied RGB, Additive RGB, and Alpha. The RGB output must match the graph’s blend mode, and Alpha passes through to the fragment Alpha block.

For handwritten shaders, include Runtime/Shaders/Transparent/Nebula_TransparentFog.hlsl from the package. Sample at the fragment’s normalized screen UV and positive eye-space depth with Nebula_TrySampleTransparentFog. It returns a Boolean and a NebulaTransparentFogSample containing inscattering and transmittance.

Use the helper that matches your framebuffer blend:

• Nebula_ApplyTransparentFogStraightAlpha(rgb, fog) returns incoming fog light plus transmitted straight RGB.
• Nebula_ApplyTransparentFogPremultiplied(premultipliedRgb, alpha, fog) weights incoming fog light by alpha, then adds transmitted premultiplied RGB.
• Nebula_ApplyTransparentFogAdditive(rgb, fog) attenuates only the additive contribution; it does not add fog light again.

Do not apply Nebula twice to the same final color. Transparent fog beyond the represented interval uses the accumulated fog at the maximum distance. These helpers do not add refraction or solve transparency sorting.

Choose a quality level

On the renderer feature, select Quality Preset to set all four quality groups together. Start with Medium, then measure a Player build on your target hardware and output resolution. Changing an individual group produces Custom unless the groups match a preset.

Figure 20

Froxel Resolution controls the camera-aligned 3D fog cells. The tiers use: Very Low 16 px / 32 slices; Low 12 / 64; Medium 8 / 64; High 8 / 96; Very High 6 / 96. Smaller pixel sizes and more depth slices increase GPU work and 3D texture memory.

Froxel Sampling increases samples within each cell. Close/near/middle/far counts are 1/1/1/1, 1/1/1/1, 2/1/1/1, 2/2/1/1, and 4/2/1/1 from Very Low to Very High.

Temporal Sampling uses a 1024-frame jitter sequence in every tier. History-miss/non-temporal samples are 1/1, 1/1, 4/1, 4/2, and 4/4 respectively.

Cluster Granularity trades CPU construction and buffer size for fewer light/fog tests per cell. Tile pixels/depth slices are 64/8, 48/12, 32/16, 24/24, and 16/32. Finer clusters are not automatically faster.

Choose what the renderer evaluates

The renderer feature is shared by every camera using that renderer. Its Rendered Content switches gate whole categories of work; they do not change values stored in Volume Profiles or local components.

Figure 21

Enable Transparent Fog: Publishes integrated fog for compatible transparent shaders.

Enable Additional Lights: Evaluates supported non-main lights. The main light remains available when this is off.

Enable Light Cookies: Samples cookie textures where URP provides them.

Enable Local Fog Volumes: Collects and renders Volumetric Fog components.

Enable Local Fog Height Attenuation and Enable Local Fog Noise: Allow the corresponding per-volume settings. Turning them off removes those calculations; it does not disable global height or global noise.

Disable a category only if its visible contribution is unnecessary. Preset changes preserve these switches and the depth, lighting, and temporal behavior settings.

Balance stability and response

The lower renderer settings control depth sampling and how much previous frames influence fog. Keep Debug Visualization at None when judging the final image.

Figure 22

Logarithmic Depth Scale: Nebula places more depth slices near the camera. Increase this value to concentrate them further; the default is 32. Existing Quadratic configurations now use logarithmic distribution and may look different.

Enable Conservative Depth constrains fog near opaque surfaces to reduce foreground bleeding. Surface Depth Bias leaves a world-space gap before those surfaces; too much can make fog visibly detach.

Enable Temporal Reprojection smooths fog using history. Scattering History Weight and Extinction History Weight default to 0.9; higher values stabilize more strongly but respond more slowly. Lighting and motion rejection reduce history when the corresponding comparisons disagree.

Inverse-Square Light Distance Bias Scale filters very bright point/spot light contributions near their origin. Larger values spread that near-source filtering over a larger froxel-relative distance. For one moving light, try Temporal Responsiveness before changing every camera’s history weights.

Inspect a rendering problem

Open Window > Analysis > Rendering Debugger, then select Nebula. For a healthy-frame readout, enable Capture Successful Frames under Controls and let the camera render. Failures, skips, and corrected settings are retained automatically.

Figure 23

Choose Camera Snapshot Slot and check the camera and renderer-feature IDs under Frame when several cameras are rendering. Active should be true for a recorded effect; Skip Reason, Error, and Degradations explain skipped work or fallback behavior.

Freeze Snapshot holds the displayed values while rendering continues. Reset Temporal History resets the selected camera. Turn off successful-frame capture when you no longer need retained healthy snapshots. These diagnostics are for the Editor and builds with development diagnostics, rather than a release-player status API.

Resolve missing or unexpected fog

No fog in the Game view

Start with the renderer feature, then the Volume override. The camera must use that renderer and a Volume layer mask that includes the active Volume. Check that its blended Enabled value is on. An unused profile cannot enable fog. The Rendering Debugger distinguishes a disabled Volume, unsupported camera, invalid resources, and missing capabilities.

Scene view and Game view disagree

The Scene view also requires its Effects and Fog controls to be enabled, with Shaded or Shaded Wireframe drawing. Its lighting preview must reflect the scene lights for a useful comparison. Game cameras use their own renderer and Volume stack; overlay cameras and XR are skipped.

A local patch or light disappears

Check the local component or light component for Excluded, disabled objects, and camera-layer filtering. Zero additive density contributes nothing; zero-density Replacing fog can intentionally clear an area. Height attenuation, noise, and terrain fitting can also reduce a valid volume to zero at the point you are viewing.

A transparent object stays clear

Its material needs a Nebula-aware shader, and the active renderer must publish transparent fog. Increasing global density cannot make an unrelated transparent shader sample Nebula.

Moving lights leave trails

Use the light’s Temporal Responsiveness or the renderer’s history controls. For an abrupt camera or fog cut, use ResetTemporalHistory. Higher response can reveal more sampling variation.

Terrain-relative fog is missing

Check the provider’s Inspector error and assigned tiles. Only one provider may be active. Tiles need TerrainData, finite dimensions, unit scale, and no rotation. Suppress Fog intentionally clears uncovered positions and holes. See terrain setup.

When reporting a problem, include Nebula/Unity/URP versions, graphics API and device, a small reproducing scene, the affected camera, and the Nebula Frame error or skip reason. Include the relevant profile and renderer settings.

Change fog during play

Use the Zal.Nebula namespace and reference the Zal.Nebula.Runtime assembly from your assembly definition. Volume access also uses UnityEngine.Rendering.

Inside an existing runtime method with a Volume volume reference, this enables fog and sets the equivalent of Inspector density 2:

using UnityEngine.Rendering;
using Zal.Nebula;

// volume is the Unity Volume that owns the active fog profile.
if (volume.profile.TryGet<VolumetricLightingVolumeComponent>(out var fog))
{
    fog.Enabled.Override(true);
    fog.GlobalExtinction.Override(0.02f);
    fog.Intensity.Override(1f);
}

The profile must already contain the Nebula override. volume.profile gives that Volume an instantiated profile; editing sharedProfile changes the shared asset instead. Retain the instance for your intended lifetime and destroy a runtime-created profile when its owner no longer needs it. These runtime changes do not save an authored profile asset.

Override(value) also sets the parameter’s override state. Assigning only .value does not enable an unchecked override. Global extinction and VolumetricFog.Density are in inverse world units, so multiply Inspector density by 0.01 before assigning either API value.

For a camera teleport, abrupt profile switch, or color cut, reset history before the next render:

// camera is the affected UnityEngine.Camera.
VolumetricLightingRendererFeature.ResetTemporalHistory(camera);

Each camera owns its history. Smooth Volume transitions can keep temporal reconstruction; an explicit reset discards the old view’s accumulated fog on the next render.

Use the runtime controls

The following members are public in Zal.Nebula. Keep references to the actual component or renderer feature you intend to change.

Renderer quality

// feature is a VolumetricLightingRendererFeature reference.
feature.ApplyPreset(NebulaQualityPreset.Low);
NebulaQualityPreset selected = feature.QualityPreset;

ApplyPreset(NebulaQualityPreset preset) changes the four quality groups on that feature, shared by its cameras. It preserves behavior settings. Custom changes only the preset label; invalid enum values select Medium. Individual quality groups have no public runtime setters. A preset change does not save the renderer asset to disk.

Per-light response

VolumetricRealtimeLight.Excluded, VolumetricScatteringIntensity, and TemporalResponsiveness mirror the light Inspector. Intensity clamps to nonnegative values; responsiveness clamps to 0-1. Nonfinite assignments reset them to 1 and 0 respectively. GetForLight(Light light) returns the registered component or null if absent.

Local fog

VolumetricFog exposes Color, EmissionColor, Density, Shape, BlendMode, BlendPriority, BoundaryFade, RadialFadeStart, and Excluded. Height and noise properties mirror the local Inspector. OverrideScatteringDistribution enables its local ScatteringDistribution value.

Supply finite, valid values. Local density is nonnegative; albedo RGB stays within 0-1; emission RGB is nonnegative HDR and ignores alpha. An invalid local medium can be rejected instead of rendering. The API density is extinction, not the scaled Inspector number.

Terrain updates

FogTerrainHeightField.SetTerrains(Terrain[] terrains) replaces the source list and requests a rebuild. It retains the supplied array: do not mutate it behind the provider. A null array returns Optional<TerrainHeightFieldError> with a failure; an empty optional means input acceptance, not completion of the GPU rebuild.

RequestRefresh() schedules a rebuild before the next render that consumes the field. Resolution also requests refresh when changed. Error exposes the current optional failure, whose Code identifies the category and Detail explains it. Terrains exposes the selected sources as a read-only list.

Choose a supported target

Nebula 1.2.0 is a RenderGraph renderer feature for the Universal Renderer in URP. Its package metadata declares Unity 6000.0.5f1 and URP 17.0.4. This guide’s Editor captures and play checks use Unity 6000.0.82f1, URP 17.0.4, and Metal. The additional-light density checks use the same Unity and URP versions with Direct3D 11. These checks do not qualify other Editor versions or physical devices.

Pipeline and cameras

URP Compatibility Mode bypasses the required RenderGraph path. Built-in and HDRP are not supported. Base Game cameras and Scene views can render Nebula; overlay, reflection/preview camera types, and XR are skipped. The package’s feature targets the Universal Renderer, not the 2D Renderer.

Graphics capabilities

The shipped shaders compile for d3d11 (Direct3D 11/12), metal, vulkan, and gles3. Compute shaders, sampled 3D textures, and 3D RenderTextures are required. The device must support sampled, linearly filtered, and random-write R16G16B16A16_SFloat volumes, plus rendering and blending in the camera color format.

Conservative depth uses sampled/random-write R32_SFloat; without it, that optional stage is disabled. Temporal auxiliary volumes use sampled/random-write R16_SFloat; without them, Nebula falls back to non-temporal rendering. Terrain fitting separately needs the supported R32 height-field format. The debugger exposes these degradations and failures.

Mobile, Web, PC, and consoles

PC and mobile hardware must pass those capability checks. OpenGL ES needs compute support (ES 3.1 or later), not merely an ES 3.0 context. Profile mobile builds on the physical target at shipping resolution; an Editor result is not a performance guarantee.

WebGL is not supported: it cannot provide the required compute path. The current shader allow-list also omits WebGPU and native console backends, including PlayStation, Switch, and Xbox Series. Those targets need package implementation and validation beyond this version. OpenGL Core is likewise outside the allow-list.

Build-time shader variants

Nebula strips scattering variants based on saved URP configurations. Keep every pipeline capability needed at runtime represented in a saved URP asset; introducing an entirely new capability only after startup can require a stripped variant. AssetBundle builds retain configuration-dependent variants because their destination pipeline can differ.

Each additional rendering camera or visible accumulating Scene view can require its own fog history and GPU memory. Measure the camera arrangement you intend to ship, not only one isolated view.

Sample guides

• Nebula
• Nebula
• Nebula
• Nebula