feat(ui): add RenderOrder property for UI component stacking

[laske185]

PR Details

Add RenderOrder property to UIComponent to control draw order of overlapping UI components. Lower values are rendered first (behind), higher values render on top. Default is 0, preserving existing behavior.

Related Issue

None.

Types of changes

• Docs change / refactoring / dependency upgrade
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My change requires a change to the documentation. PR: feat: add render order property to "Add a UI to a scene" documentation stride-docs#490
• I have added tests to cover my changes.
• All new and existing tests passed.
• I have built and run the editor to try this change out.

[Ethereal77]

I have not tested your changes yet, but on Discord I was talking about this recently. While you are at this, can you check what effect it has in ordering the UIElement.DrawLayerNumber? I thought it was for this very purpose, but it didn't work. I also tried setting a low depth and positioning the UIElement towards the front, but it is weird and not very intuitive.

Btw, in UIElement the term depth refers to the size in the depth dimension (same as Width and Height), but that name is a bit confusing, it may seem to refer to the depth "position", which is defined in the local matrix.

[laske185]

I also played with the parameters inside the UIPage, like depth, draw layer number, and alignment of the container components. Additionally, I tested the position and the z-coordinate of resolution and size. But all did not work.

In my scenario, I have a split-screen setup with its own UIComponent for the render-to-texture images and a UI for the HUD. It is not deterministic whether the hub is before or behind the split-screen UI. I started to combine the complete UI into one UIPage to be able to set the depth, but now I have a huge UI monolith.

With the solution from this PR, the render pipeline is manipulated to order the UI pages. This explains to me why all parameters did not have any effect on the draw order, because the pipeline renders component for component and overwrites the previous paint.

[laske185]

I have not tested your changes yet, but on Discord I was talking about this recently. While you are at this, can you check what effect it has in ordering the UIElement.DrawLayerNumber? I thought it was for this very purpose, but it didn't work. I also tried setting a low depth and positioning the UIElement towards the front, but it is weird and not very intuitive.

Btw, in UIElement the term depth refers to the size in the depth dimension (same as Width and Height), but that name is a bit confusing, it may seem to refer to the depth "position", which is defined in the local matrix.

To get a quick answer, I asked Claude, and it confirmed what I had observed:

DrawLayerNumber (UIElement) — Controls the depth bias within a single UI tree. Determines how many depth layers an element needs for its own visual parts (background, border, content). For example, Button adds +1 for its design image. Accumulated in UpdateElementState so child elements don't z-fight.

RenderOrder (UIComponent) — Controls draw order between separate UIComponents in the scene, i.e. between entirely different UI hierarchies.

In short: DrawLayerNumber = z-sorting within a UI tree, RenderOrder = sorting between UI trees.

[Eideren]

This is not a trivial call to preform on every render, I assume by default elements are drawn in from first to last child depth first ? Is there a reason why you can't re-order the elements themselves ? You mentioned

In my scenario, I have a split-screen setup with its own UIComponent for the render-to-texture images and a UI for the HUD. It is not deterministic whether the hub is before or behind the split-screen UI. I started to combine the complete UI into one UIPage to be able to set the depth, but now I have a huge UI monolith.

Order of drawing between UI pages looks like a queue, the last one added to the scene is drawn above everything. Then it's split in render groups afair. If you want to draw a page above others, you can remove it from the scene and add it back in. Or mess with its render group I think.

[laske185]

I invested days some time ago, and the order of the entities doesn't change anything. Maybe it was already fixed, or the behavior has changed.

In any case, I can adjust the layering of the UI pages by changing the order of the entities and fix my bug.

Thanks for your feedback, @Eideren! I close the PR.