Canvas layers

CanvasItem nodes, and nodes inheriting from them, are direct or indirect children of a , and will be displayed through it.

A Viewport has the property Viewport.canvas_transform, which allows applying a custom transform to the CanvasItem hierarchy it contains. Nodes such as Camera2D work by changing that transform.

Effects like scrolling are best achieved by manipulating the canvas transform property. This approach is more efficient than moving the root canvas item (and hence the whole scene).

• Parallax Backgrounds: Backgrounds that move slower than the rest of the stage.
• Transitions: We may want visual effects used for transitions (fades, blends) to remain at a fixed screen location.

How can these problems be solved in a single scene tree?

CanvasLayers

The answer is , which is a node that adds a separate 2D rendering layer for all its children and grand-children. Viewport children will draw by default at layer “0”, while a CanvasLayer will draw at any numeric layer. Layers with a greater number will be drawn above those with a smaller number. CanvasLayers also have their own transform and do not depend on the transform of other layers. This allows the UI to be fixed in screen-space while our view on the game world changes.

An example of this is creating a parallax background. This can be done with a CanvasLayer at layer “-1”. The screen with the points, life counter and pause button can also be created at layer “1”.

CanvasLayers are independent of tree order, and they only depend on their layer number, so they can be instantiated when needed.

Note