repository·main·Indexed 20 days ago
https://github.com/redsim/vrclightvolumesAn optimized voxel-based lighting solution for VRChat that provides a high-performance alternative to traditional light probes and analytic lighting for avatars, dynamic props, and static objects. It features baked per-pixel voxel lighting, support for regular and point light volumes, and integration with various compatible shaders and Amplify Shader Editor (ASE).
The VRC Light Volumes system uses L1 Spherical Harmonics (SH) to approximate how light affects a point in 3D space. This is a computationally efficient method suitable for real-time rendering.
L1 Spherical Harmonics consist of:
Unlike regular Light Volumes which use voxels, Point Light Volumes compute lighting analytically in real time using mathematical formulas. They use L1 SH and an inverse square attenuation model, which accounts for the physical size of the light source.
The attenuation is calculated as: $$\text{Attenuation} = \frac{1}{\text{LightSize}^2 + \text{DistanceToLight}^2}$$
The final color is determined by: $$\text{FinalColor} = \text{Attenuation} \times \text{Color} \times \text{Intensity} \times \text{LightSize}^2$$
Note that intensity is multiplied by the square of the light's size, causing it to behave like light emitted per unit surface area.
To optimize performance, lights are culled at a distance using a squared distance mask: $$\text{Mask} = \text{Saturate}\left(1 - \frac{\text{DistanceToLight}^2}{\text{CutoffDistance}^2}\right)$$
The Saturate() function clamps the result between 0 and 1, and the final light color is multiplied by this mask.
You can choose between three light shape modes:
Uses inverse-square light attenuation.
Light Source Size: Represents the physical radius of the light-emitting surface (e.g., a bulb). Scaling the GameObject also scales this value.Intensity: Represents light emitted per unit of surface area. Small Light Source Size values require very high Intensity to achieve a visible range.Angle: Cone angle in degrees (can exceed 180° for an inverted cone).Falloff: Adjusts cone edge softness.Used for complex shapes and custom attenuation.
Range configuration.Used for projecting textures or cubemaps.
Custom mode, the Angle property cannot create an inverted cone (unlike Spot Light mode).Light Volumes are 3D textures composed of voxels. Each voxel stores numerical data representing the L1 SH coefficients rather than standard RGBA colors.
Because L1 SH requires 12 channels (L0 + 3 color channels $\times$ 3 vector components) and standard 3D textures only support 4 channels (RGBA), the system splits the data across three separate 3D textures.
VRC Light Volumes is an optimized lighting solution for VRChat (designed for SDK3 and Udon) consisting of two distinct systems:
Regular Light Volumes: A voxel-based solution that replaces Unity's light probes with per-pixel lighting. It functions similarly to Unity 6's Adaptive Probe Volumes (APV) but uses manual, ReflectionProbe-like volume placement. Use this for baked, high-quality environmental lighting.
Point Light Volumes: A parametric lighting system for dynamic lights (Point, Spot, and Area lights). Unlike the regular system, these are not voxel-based and use LUT textures or parametric math. They can support up to 128 active lights per scene and can project light cookies or cubemaps, but they do not support real-time shadows.
The TV Screens Integration package provides a way to achieve real-time global illumination from video players.
Key Characteristics:
Limitations:
Light Volume evaluation is performed entirely within the shader. To use this, a material must include specific shader code that supports Light Volumes.
The shader calculates the world position of a pixel, samples the SH data from the atlas using interpolated voxel values, and computes the final color using the following formula:
FinalColor = L0 + dot(L1, WorldNormal);This formula represents the fastest and simplest method for evaluating SH data.
The VRC Light Volumes system uses two distinct components to manage lighting data:
Light Volume (Editor-only): A helper script used in the Unity Editor to configure settings and manage 3D textures. It is not included in the VRChat upload. Use this to set up your volumes and manage the baking process.
Light Volume Instance (Udon script): The actual runtime component that stores all data required for rendering. This is what is uploaded to VRChat.
Usage Note: Do not modify Light Volume Instance values manually in the editor; always use the Light Volume component instead. However, if you are writing Udon logic to change lighting at runtime (e.g., animating light intensity), you should reference and manipulate the Light Volume Instance component directly.
The Point Light Volumes system uses two distinct components to manage lights:
Point Light Volume (Editor-only): A helper script used to configure light settings in the Unity Editor. It is not included in the VRChat upload. Use this for all manual setup.Point Light Volume Instance (Udon script): The actual runtime component that stores data and renders the light in-game.Usage Rule:
Point Light Volume component.Point Light Volume Instance component, as it is the one that functions in-game.If you choose to implement your own evaluation method instead of using LightVolumeEvaluate(), you must use L1 components.
Warning: Using only the L0 (ambient) term will result in unrealistic shading and can make objects appear translucent. Proper shading requires considering L1 directions, or at minimum, the magnitude and direction of the dominant light.