Confused by CanvasLayer property follow_viewport_enable / follow_viewport_enabled, sounded like follow_camera_enabled but it's the opposite

[hsandt]

I find the CanvasLayer > property Follow Viewport > Enable aka follow_viewport_enable (Godot 3) / follow_viewport_enabled (Godot 4) confusing, both in name and descriptions.

1. Just looking at the name, it sounds like I must enable this property to make a HUD that stays on the same position on screen, but it's the opposite.
2. The tooltip clarifies things a bit: "If enabled, the CanvasLayer will use the viewport's transform, so it will move when camera moves instead of being anchored in a fixed position on the screen." => so I understand that when it's disabled, the elements are fixed on screen, which is true. When enabled though, it will move, but how?

The key is to understand that follow_viewport_enable means it is affected by viewport movement, but moves in the opposite direction of the camera to give the illusion that the elements belong to the level (and when follow_viewport_scale is not 1, with some speed variation for a parallax scrolling effect).

But to me, a "viewport" is a rectangle on screen defined by either pixel or ratio coordinates like (0, 0, 1, 1) for a one-player fullscreen game, so it doesn't change, and there is nothing to follow in it.

follow_camera_enabled (the opposite flag) would be clearer, however it would give the impression that enabling it enables a special behavior, but that's the default, more simple behavior of a CanvasLayer (technically speaking, it's easier to just draw stuff at fixed position on screen), so I understand that you didn't want to make it a "positive" flag.

In this case, follow_scene_enabled could be a name easier to understand for a flag that has the same meaning as follow_viewport_enabled. In fact, it seems that in this context, viewport is used in the meaning of the part of the scene shown rather than a portion of the screen. There may be cases where it doesn't really move with scene nodes, but that sounds true in common cases (if scale is not 1, it won't exactly follow, but then it's the same issue with the name follow_viewport_enabled).

I'm not sure what it looks like in 3D. UI elements cannot just follow the scene perfectly in 3D where various camera motions are possible. Maybe it does some approximation using projections and that's why the name viewport was preferred? I'll try CanvasLayer in 3D scenes later, but if you know what it's doing you can describe it in a comment.

I understand that there is no easy solution that gives a naming that is both technically correct for both 2D and 3D and easy to understand, but I think it's better if we find a name that makes dev find the correct setting to get what they want from the first try.

Or the name could say the same, just the tooltip made even clearer, esp. to describe what happens when the flag follow_viewport_enabled is true, such as "it will move in the opposite direction of the camera motion, as if following scene nodes" (at least for 2D).

Anyway, fortunately it's easy to just try the game with on and off, so it's not that critical once you've done that once.

[Mickeon]

I'm not sure what it looks like in 3D. UI elements cannot just follow the scene perfectly in 3D where various camera motions are possible. Maybe it does some approximation using projections and that's why the name viewport was preferred? I'll try CanvasLayer in 3D scenes later, but if you know what it's doing you can describe it in a comment.

Nothing. 2D and 3D renderers are separate and independent from one another.

The tooltip clarifies things a bit: "If enabled, the CanvasLayer will use the viewport's transform, so it will move when camera moves instead of being anchored in a fixed position on the screen."

Honestly the description is iffy indeed. CanvasLayer is one of the most "basic" nodes out there for beginning users. So first of all, they may not understand what the Viewport's transform is in one sentence. Second, it's just overall misleading.

follow_camera_enabled (the opposite flag) would be clearer

Perhaps? It's not true, though. All the Camera does is manipulate the Viewport's transform by itself.

In this case, follow_scene_enabled could be a name easier to understand

It would be more misleading. "Scene" in Godot often refers to PackedScene file you save on disk, or the whole branch of nodes that comes out of it.

I can understand the confusion, honestly. I personally would expect this property to do the exact opposite of currently.