Copyright © 2025-2026 Candy ArtsUI Z
The UI_Z command changes the z index of UI elements, media players or any other CanvasItem, to draw them in front of or behind each other, for example to show the dialogue box over a video. Nodes are reordered in the order they are listed, so a node can be placed relative to one moved earlier in the same Line. A node that can't be found or has no z index is reported and skipped.
A z index only orders nodes within the same CanvasLayer: UI_Z can't draw a node in front of a node on a higher layer, such as the VN Scene in front of the dialogue box in Candy_UI.tscn. See Drawing Order, on the UI page.
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Nodes
Description:
The nodes to reorder. Each key identifies a node, and its value is a Dictionary of settings for that node (see below).
Values:
• Media player name: A key of the Engine's media_players_paths, such as Video.
• UI element key: A key of the Engine's ui_elements_paths, such as dialogue_box_path.
• Node path: A path relative to the Engine, or an absolute path such as /root/Game/Screen.
• ¢ expression: Can also return the node itself, such as ¢$UI/Map.
Node Settings
Each node in Nodes accepts the following keys.
Z_Index
Description:
The node's new z index, clamped to Godot's range of -4096 to 4096.
Values:
• Reset (case-insensitive): Restore the node's default_z. Every Candy Dialogue Engine UI element and media player has one; for other nodes, an error is reported.
• Number: Set the z index to exactly that value, such as 150 or 0.
• +N / -N: The z index of the Relative_To node plus or minus N, such as +1.
• Empty: No change.
Relative_To
Description:
The node that +N and -N values are relative to; only needed for them. To shift a node from its current z index, set Relative_To to the node itself.
Values:
• Media player name: A key of the Engine's media_players_paths, such as Video.
• UI element key: A key of the Engine's ui_elements_paths, such as dialogue_box_path.
• Node path: A path relative to the Engine, or an absolute path such as /root/Game/Screen.
• ¢ expression: Can also return the node itself, such as ¢$UI/Map.