flame-engine / flame-engine/flame

Add a RenderLayer system for global render ordering

Open
#3,967 0 comments 0 reactions 1 assignee Claimed by @spydon View on GitHub
enhancement
Dominant language
Dart
Stars
10.8k
Forks
1k
Avg merge
1d 20h
Merged PRs (30d)
21

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 `PositionComponent`s 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.