UI sprites/text can still be occluded by 3D in 0.24.3 unless tagged with @ui

[Milky2018]

Summary

In 0.24.3, 2D text/sprite HUD can still be occluded by 3D content unless entities are explicitly tagged with @ui.

This is surprising for ports that use plain @sprite HUD (no @ui component) and appears as "UI fix not working" from app side.

Affected versions

• Milky2018/selene: 0.24.3
• Milky2018/selene_raylib: 0.24.3
• macOS (Apple Silicon)

Reproduction

1. Build an app with 3D scene + 2D HUD text via @sprite.Sprite::from_text(...).
2. Do not attach @ui component to those HUD entities.
3. Render a 3D scene with a camera.
4. Observe HUD text/sprites are drawn under 3D.

Source-level analysis

• sprite.render_sprite_system classifies commands as overlay only when entity has @ui:
  • selene/src/sprite/top.mbt (around is_ui = @ui.uis.get(e) is Some(_))
• raylib backend submits draw order as:
  1. frame2d.world_commands
  2. render_3d_frame(frame3d)
  3. frame2d.overlay_commands
  • selene_raylib/src/platform_render/top.mbt

So non-UI sprites are intentionally drawn before 3D and can be occluded.

Why this still looks like a regression

In real ports, many existing HUD systems are plain sprites/text without @ui component. After moving to 3D, they suddenly get occluded although users expected "UI-over-3D" behavior from release notes.

Request

• Clarify this explicitly in docs/changelog (world vs overlay semantics).
• Consider an easier opt-in overlay path for non-@ui sprites/text (e.g. explicit overlay flag / helper API), so migration from legacy sprite HUD is less error-prone.

[Milky2018]

Closing as resolved. The engine and docs now explicitly describe world-vs-overlay semantics for 2D over 3D composition, and Selene also provides explicit overlay helpers for non-ui HUD migration via set_overlay_space and clear_overlay_space.