Add a RenderLayer system for global render ordering
Maintainers usually reply within 1 day
@spydon is already working on this.
Since Jul 22, 2026.
Assessment
This issue has not been assessed yet.
Description
Motivation
priority only orders siblings, so the draw order of a component is tied to where it sits in the tree. Games regularly need cross-hierarchy ordering (a health bar above all enemies, a projectile under all UI) and the current workaround is restructuring the tree so competitors share a parent.
Proposal
A RenderLayer system, similar in spirit to Godot's CanvasLayer and Unity's sorting layers:
- A
World(per camera pass) owns an ordered set of layers; each layer has a z-index. - Components can declare a target layer; their rendering is routed to that layer instead of their tree position, while updating, lifecycle, and hit-testing stay hierarchical.
- Plain
PositionComponents are replayed onto their layer using their cached absolute transform. Subtrees with hierarchical render state (clips, decorators, snapshots, customrenderTree) stay atomic: they render as a unit at their subtree's layer. - The flattened-traversal infrastructure from #3957 (structure versioning, lazily rebuilt root-owned lists) carries over directly for maintaining per-layer render lists.
This also follows the design note in #3957 about separating render order from update order, and would give y-sort a render-time home (a layer sorted by position.y) with zero structural reordering.
Out of scope
Arbitrary interleaving of components across clip/decorator boundaries; those subtrees remain atomic within a layer.
Related: #3957, and the "Support a global z-index/priority" item in #1938.
- Dominant language
- Dart
- Stars
- 10.8k
- Forks
- 1.1k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 61
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from flame-engine/flame
-
Timer with tickCount stays finished after start() or reset()Possibly taken @matthewalberto claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
flame-engine/flame#4240 · 1 comment ·
Maintainers usually reply within 1 day
-
`CameraComponent.follow` follows the local position of a nested targetPossibly taken @ufrshubham claimed this today. Openbug
flame-engine/flame#4238 · 1 assignee ·
Maintainers usually reply within 1 day
-
`ComponentPool` returns components to the pool while they are still in use, and loses components removed before mountingPossibly taken @ufrshubham claimed this 18 days ago. Openbug
flame-engine/flame#4191 · 1 assignee ·
Maintainers usually reply within 1 day
-
Move the flame_studio debugging features to flame_devtoolsPossibly taken A pull request linked to this issue is open or already merged. Openenhancement
Difficulty 5/5 Over a week Newbie friendliness 35/100
flame-engine/flame#4176 ·
Maintainers usually reply within 1 day
-
discussion enhancement
Difficulty 5/5 Over a week Newbie friendliness 25/100
flame-engine/flame#4175 ·
Maintainers usually reply within 1 day
All issues in flame-engine/flame
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
spotiflacapp/SpotiFLAC-Mobile#935 ·
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
chriskelly/wish-together#193 ·
Maintainers usually reply within 1 day
-
area: player feature request
Difficulty 2/5 1-3 hours Newbie friendliness 65/100