Component · render

PostProcessVolume

A region whose post-processing overrides blend in as the camera approaches and enters it. Volumes apply in ascending priority (ties in entity ID order); each property one overrides moves toward its value by the volume's weight at the camera. Properties no volume overrides keep the engine defaults. Scenes saved with the former PostProcess component load as one global volume that overrides everything.

Fields

shape

VolumeShape

Where the volume applies: everywhere, or inside a box or sphere placed and sized by the entity's transform.

default "global"

One ofglobalboxsphere

blendDistance

f32

Distance outside the box or sphere over which the volume fades out; 0 is a hard edge.

default 0m0 – 1000shown when shape is box or sphere

priority

f32

Order among overlapping volumes: higher priorities apply after, and over, lower ones.

default 0-1000 – 1000

weight

f32

Overall strength of the volume's overrides, from 0 (none) to 1 (full).

default 10 – 1

overrides

list<PostOverride>

The settings this volume changes, one entry per group. Anything not listed comes from lower-priority volumes or the defaults.

default []

Usage

Every edit is an undoable command: from the CLI as below, or the same JSON from an agent over MCP. See component.add and property.set.

Add it

ara do component.add -p entity=name:Crate -p component=PostProcessVolume --why "Add PostProcessVolume"

Set a field

ara do property.set -p entity=name:Crate -p path=PostProcessVolume.shape -p value="global" --why "Tune PostProcessVolume"

In a scene document

{
  "PostProcessVolume": {
    "shape": "global"
  }
}

From C#

/// <summary>Call each fixed tick with a room trigger's occupancy to fade its camera treatment in and out.</summary>
public static void UsePostProcessVolume(Entity entity, bool playerInside, in Tick tick)
{
    ref var volume = ref World.Get<PostProcessVolume>(entity);
    volume.Shape = VolumeShape.Box;
    volume.BlendDistance = 2f;
    volume.Weight = Math.Clamp(volume.Weight + (playerInside ? 2f : -2f) * tick.Dt, 0f, 1f);
    volume.Overrides = [
        new PostOverride {
            Module = PostModule.ColorGrading, WhiteBalance = 4500f, Saturation = 0.8f,
            Lut = "@textures/security_lut.png#as_alarm", LutContribution = 0.6f
        },
        new PostOverride {
            Module = PostModule.DepthOfField, FocusDistance = 8f, Aperture = 2.8f,
            NearBlur = 0.5f, FarBlur = 1f
        },
        new PostOverride { Module = PostModule.MotionBlur, ShutterAngle = 180f }
    ];
}

From C#

Scripts read and write it with Get<PostProcessVolume>(); see the PostProcessVolume struct.