LightOccluder2D editor preview is misleading as it darkens the sprite that acts as an occluder

[cashew-olddew]

Tested versions

• Reproductible in: 4.3.stable

System information

Windows 10 - Godot 4.3.stable - Vulkan (Forward+)

Issue description

I was trying to cast a light on a Sprite2D that had a LightOccluder2D attached, without actually occluding the sprite itself. In the documentation it is specified that

LightOccluder2Ds follows the usual 2D drawing order. This is important for 2D lighting, as this is how you control whether the occluder should occlude the sprite itself or not.

This led me to believe that this functionality would work both in the editor and in game.
When trying this out, in editor I got:

While testing the game I got:

I managed to reach a solution by applying a clockwise cull mode, but that rids me of the flexibility that the occluder ordering relative to the sprite would have given me.

I had initially thought that this is a documentation issue, as I specified in the godot-docs repo, but @AThousandShips considered that this is likely an engine issue.

Steps to reproduce

1. Create a Sprite2D.
2. Click on the Sprite2D, create a LightOccluder2D sibling.
3. Create a PointLight2D which can have a texture or a simple radial black and white GradientTexture2D
4. In the scene tree, change the placement of the occluder to be above, below the sprite or a child that either has or doesn't have 'show behind parent' enabled.
5. No matter which combination was selected, the sprite will always be occluded by the occluder.

Minimal reproduction project (MRP)

project.zip

[huwpascoe]

Here's the problem:

godot/scene/2d/light_occluder_2d.cpp

Lines 183 to 201 in ee4acfb

	if (Engine::get_singleton()->is_editor_hint()) {
	if (occluder_polygon.is_valid()) {
	Vector<Vector2> poly = occluder_polygon->get_polygon();
	if (poly.size()) {
	if (occluder_polygon->is_closed()) {
	Vector<Color> color;
	color.push_back(Color(0, 0, 0, 0.6));
	draw_polygon(Variant(poly), color);
	} else {
	int ps = poly.size();
	const Vector2 *r = poly.ptr();
	for (int i = 0; i < ps - 1; i++) {
	draw_line(r[i], r[i + 1], Color(0, 0, 0, 0.6), 3);
	}
	}
	}
	}
	}

In editor mode it draws the occluder with an arbitrary black + 60% alpha. The clockwise cull shows how this editor shape looks as-is.

[cashew-olddew]

I think there might still be some misunderstanding in regards to the issue. The problem was not necessarily that the occluder was darkening the sprite in the editor, but rather that, no matter where it was placed relative to the sprite, it did not do what the documentation says:

LightOccluder2Ds follows the usual 2D drawing order. This is important for 2D lighting, as this is how you control whether the occluder should occlude the sprite itself or not.

Let's look at the "Occluder Above" example:

• The occluder is above the sprite in the scene tree, thus, it should draw behind it
• As per the docs, when I run the game, I expect to see a sprite casting a shadow, with the sprite being fully lit (similarly to how the clockwise occluder example works)
• Instead, the sprite is occluded as well

So, if I place a sprite and an occluder on top of each other, to me, two cases seem plausible:

• the docs are wrong: the sprite will always be occluded, no matter where the occluder is relative to it in the scene
• the docs are right: which means that there's an issue with this feature in the engine

[huwpascoe]

@clayjohn is there a definitive answer? Are occluders supposed to respect z-index?

[clayjohn]

@clayjohn is there a definitive answer? Are occluders supposed to respect z-index?

I don't think they do. CCing @Calinou Who added that section of the docs in godotengine/godot-docs#6424