Add a RenderLayer system for global render ordering

Open
#3,967 0 comments 0 reactions 1 assignee View on GitHub

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

enhancement

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, custom renderTree) 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from flame-engine/flame

All issues in flame-engine/flame

Similar issues

More Dart issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.