What is the LIGHT built-in variable of the canvas_item shader?

Rpahut

I struggle to make sense of the LIGHT shader variable on my own, or the whole lighting thing to be honest.

From fiddling around, it looks like LIGHT might be a sort of accumulator, where I must calculate and add illumination from a light source as a result of my light() function. But then, LIGHT_COLOR is writeable too, and changing that still affects how the sprite is rendered, as well as changing other LIGHT_ variables does. So the actual lighting calculation still happens under the hood, and the LIGHT is just another input to it - only it is required for some reason, and is poorly documented.

Looking for some insight into how things work inside, and are supposed to be used to create custom lighting.

Rpahut

Seem to have figured it out, at least to the point sufficient for my purposes.
Indeed, the LIGHT variable is the intended output of the light() function, much like the DIFFUSE_LIGHT is for the spatial shader. It's the fraction of light from a source being processed that we wish to let through to the fragment.

The undocumented part, how it is used after the light() function, can be recovered from the builtin shader source.
For one, LIGHT is being multiplied by the LIGHT_COLOR. If the light() function already applied the color in a custom way, LIGHT_COLOR have to be altered:
LIGHT_COLOR = vec4(1.0); // cancel builtin multiplication by the light color

Also, LIGHT is being altered by the normal map. If the light() function already applied the normal map in a custom way, LIGHT_VEC have to be altered:
LIGHT_VEC = -NORMAL.xy * length(LIGHT_VEC); // cancel builtin bump mapping
It should be possible to disable the default bump mapping altogether by taking the normal map from the default texture slot, and instead passing it into the shader directly as a custom texture, but I haven't tried that.

As to whether LIGHT should be added to or assigned to, I have settled for the latter, as my lights in Add mode and appear to be added anyway when applied to the lightmap.