Proposal for renaming nodes for Godot 4.0

[reduz]

Breaking compatibility

I know I promised to break as minimum as possible to compatibility for Godot 4.0, but I' ve been thinking this over for a while and based on feedback, and I think it's worth it. It should not break compatibility with existing scenes (we can add internal renames), but it will with code...

So maybe what we could do is a tool in Godot 4.0 that basically converts a script from 3.0 to 4.0 doing symbol renaming or just re-tokening.. this way no manual work has to be done by the user (so no huge amounts of pain like when we moved from 2.0 to 3.0).

For reusing existing tutorials (that I think won't really be affeced much anyway), we can put up an doc article showing what was renamed.

What I would change

Despite that many say that Godot was originally a 2D engine, that is false. Originally, it was a 3D engine and the only things supported as 2d where the canvas (UI) nodes. The 2D nodes came later.

So, this makes it quite confusing that for 3D nodes, the "Spatial" term is used and for 2D nodes, there is "Node2D".

For users starting to use Godot (and even for advanced users), this is pretty confusing in general (only aided by the node colors, but if you make a mistake in code, it can be confusing to realize you are using the right version 3D instead of 2D)).

My proposal is to simply make explicit, in case nodes exist both as 2D and 3D form, that they should be named the same, but add a 3D or 2D at the end (save for some exceptions).

So, typical renames would be:

• Spatial -> Node3D
• Area -> Area3D
• Camera -> Camera3D
• Navigation -> Nagivagion3D
• RemoteTransform -> RemoteTransform3D
• KinematicBody -> KinematicBody3D

and so on.

For some, I think we could keep the current way, because the use case is mainly for 2D or 3D, and the opposite version, such as:

• Sprite and Sprite3D make sense as is, since Sprite is mainly a 2D node
• MeshInstance / MeshInstance2D makes sense, because meshes are mainly used for 3D

But then again, feel free to suggest if you would prefer something more explicit and make everything 2D/3D always.

Namespaces

I'm not that too keen on namespaces within Godot for a few reasons

• Godot is an application, not a library
• Everything has a a clear role when you look at inheritance.
• Debug symbols increase considerably with namespaces, and our debug builds will be much larger

But nothing should avoid us from defining them using the ClassDB API, so languages that are heavily namespace based, and where users are very used to it (like C#) can make use of them.

As an example:

Below a GDCLASS("Node2D") definition, an optional
GDNAMESPACE("Nodes2D")

It will also make browsing help and documentation probably easier too.

Other things I would like to change

SpatialMaterial is confusing as hell to new users (and existing too). I think we should rename to StandardMaterial3D. I would probably also want to make two different versions, one similar to the existing one, and another that instead uses ORM style textures (setting them up in Godot right now is a huge hassle using Spatial Material and assigning channels manually). This way we could have something like:

+ Material3D
- + StandardMaterial3D
- + ORMMaterial3D

or similar..

The 3D scene import process is still quite a hassle because you can't set options to individual meshes and materials while importing them, so I want to add an option in the import dock to have import windows with settings for some types of resources (in this case for imported scenes).

The 3D scene import would show you a tree with all the data and then you can choose a lot of nice stuff in there for every node/material such as:

• Keep material built-in
• Replace this material by this file
• Edit/Create Mesh LODs for proper level of detail
• Edit mesh lightmapping options, including lightmap scale so you can have different scales in the lightmap for different objects, etc
• Many other options.

Feedback welcome!

[jahd2602]

I use Godot professionally for more than a year.

I agree with everything you said, except for:

For some, I think we should keep the current way

If we have this golden opportunity, let's just rename everything. That includes Sprite2D and MeshInstance3D.

It's always better a full painful refactor, that many partial painful refactors.

[Zylann]

Speaking of renaming: #16863

[reduz]

@jahd2602 I don't mind either way personally, we can poll that in the worst case.

I definitely can see people bothered with that simply for the fact that it's an inconsistency, but we can at least see if they are majority or minority.

[reduz]

@Zylann I know, if we decide something here, we'll move this over there.

[AlexDarigan]

I think the stance against namespaces is short-sighted. It makes sense from perspective of the engine workflow in general but it ignores the perspective from toolmakers. Godot Unit Testing (GUT) by bitwes for example broke due to a naming conflict in one of its updates. There is a likelihood this could have been avoided with a dedicated GUT namespace.

I would also like namespaces for Waiting And Testing (WAT) so I can I can use class names like Test (accessed via WAT.Test) while not running over other frameworks (like GUT if it were to use GUT.Test) or just the user's script. I've tried a number of times using a WAT class that contained all of the scripts used as subclasses but that's just a cyclic reference hell.

If we are to be encouraged to build tools from within the engine, then we need the tools to make those tools in the Engine even if they aren't absolutely necessary for the engine workflow itself.

In summary, a dedicated namespace system which can be both accessed as well as defined from the engine (or at the very least the plugin script) so tool makers don't end up walking over each other or their uses would be a godsend.

[reduz]

@CodeDarigan I understand it has benefits and I'm not denying them, but I sincerely believe that the costs outweighs them.

Add to this that pretty much we had no significant complains from GDScript users, who prefer the current approach, so it would force them to an unwanted worfklow and type more code in a language that is intended to just write quick and dirty stuff fast. (C# users seems to do want them, though).

This is why I mean that they can exist as metadata for script language bindings, and we could even add them for GDNative C++. Just not add them for core C++ engine.

[nitodico]

Navigation -> Nagivagion3D
Is this a typo?

[reduz]

@nitodico indeed

[Duroxxigar]

@reduz I agree with @jahd2602. Even if some things may be obvious, for consistency sake, we should postfix with either 2D or 3D.

[swetland]

I'm still getting started with Godot and the proposed changes sound sensible to me -- using subtly different names for the 2D or 3D variant of a node is something that's caused me a bit of confusion while learning which end is up and moving to Thing2D/Thing3D or Thing/Thing3D feels like a significant improvement to clarity and comprehensibility.

[ripperdave]

Please do it.

[StyrmirNathrakh]

Tbh this change would come anyway, so better to do it now and stick with it. For 3d there are not that many tuts so now the change will do less damage than in one, two years later.

[Janders1800]

Regarding materials it would be nice to have some kind of Legacy Material that only uses minimum resources, like diffuse and specular, this would be useful for 3D mobile games.

[MuffinManKen]

I'm also in favour of renaming things to be explicitly 3D or 2D.

Wouldn't it be possible to have the original names still exist as aliases to the new ones? They would be hidden from the editor so the old names wouldn't be usable (or placed under a "deprecated" heading). That way old code would still work, without changes and without needing additional logic to convert anything.

A warning could be added for code using the deprecated node names and then in 4.1 or 4.2 they could be removed.

[pkowal1982]

If there are two versions of a node I would always append 2D/3D suffix.

[MuffinManKen]

Also, I would be happy if Label -> TextLabel. I go to add a node so I can show some text, so I type text in the search bar and of course only RichTextLabel shows up which reminds me that the standard text node doesn't actually have Text in the name.

[reduz]

@Janders1800 that's how it works now, the less features you use in SpatialMaterial, the smaller the shader it creates.

[nobuyukinyuu]

I'm a 2d person, so for nodes with mainly 2d application, keeping the node names without a suffix if it doesn't already have one seems fine to me. This seems like a more painful refactor for 3D users, but it does make a lot of sense where certain nodes have only a 2d or 3D application for the most part that they retain the shorter name for their intended domain and have a suffix elsewhere. Anything else that can be unified would be nice to see unified, specifically Spatial.

[RandomShaper]

I'm in favor of unconditionally using 2D/3D suffixes, too.

While it's true that for some nodes it seems like a lost opportunity to have more "natural" names, consistency wins.

What I don't quite like is that the StandardMaterial3D is the non-ORM one. My point is that ORM is more strongly backed by a standard (at least RM, which is what you have in glTF).

But I can't yet suggest a better naming.

Maybe this is also an opportunity to do something about 'canvas'. I found that concept a bit confusing at times.

I know it's difficult, because is has no 3D counterpart: 3D scenes live in Spatial nodes, but canvases can contain a mix of Node2Ds and Controls.

However, it would be great if we could define some naming that allowed renaming CanvasItemMaterial to Material2D, while keeping it meaningful for the "pure" 2D and the GUI realms.

[m4nu3lf]

I'm not necessarily against the rename, but the original names make sense to me, maybe because of my background.
The default in physics or engineering is "3D". You don't say a "3D kinematic body", you say a "kinematic body", unless you're working in some other space.
However, I'm sure not everyone has the same background or even agrees on that, as this after all is game engine and doesn't have to strictly follow physics or engineering conventions.

[RKiemGames]

for future compatiblility, in gdscript

a gdscript file...

extends Spatial
class_name Node3D

And so on.

[BeayemX]

Have you thought about renaming translation for spatial nodes to position?

[eon-s]

@BeayemX I think that translation is a common term for 3D space, and position is common for 2D developers 🤔

I do not know if 4.0 will be the best for node name changes, there will be a lot of things to deal with and there were many changes from 2 to 3, it means deprecating books, videos, courses.
Even documentation is not complete, with changes in mid completion, fixes will slow things down a lot...

[neikeq]

I'm in favour of renaming 3D nodes as suggested here. I don't know how much of a problem it will be for tutorial makers though. At the very least, it should be trivial to refactor existing code bases. In C# we could even abuse the ObsoleteAttribute in debug mode to make it easier (not sure if a good idea though):
[Obsolete("Use Node3D", error: true)] class Spatial { /* Nothing here */ }

I hope we add namespaces/categories as discussed in #18711. I want to separate the C# API into namespaces and perhaps assemblies as well to make it possible for users to pick only what they need.
My plan for 4.0 was to hard-code a table of namespaces myself if there was no other choice, but I would prefer if instead I could get this information from ClassDB.

[Zylann]

@eon-s I don't think it is... while translation is technically valid to represent coordinates, Godot is the first engine where I see a different term being used here, otherwise I've always seen position regardless of 2D or 3D. Also to me translation is associated with movement, and conflicts with another term related to language/transformation, which makes it odd. This was mentionned in #16863 too.

[neikeq]

BTW, why are we planning to break as little as possible? I understand why people don't want more compatibility breakages, specially those making tutorials; but if we won't take 4.0 as an opportunity to break compatibility, when are we going to? #16863 is already accumulating a lot of suggestions.

[eon-s]

@neikeq can't wait for 5.0? since no new or big features are planned, otherwise people will stop making things and buying courses for an engine that changes important parts every 1 or 2 years (for video tutorial makers this mean redo all their work) and with a few months of warning time...

[AtomaFajrovulpo]

@xxmatxx I would prefer if the rename happened with a short transistion period to stop dragging the 'what would be' old names along.
Also, I'd ensure to well document the changes and makes sure people who are just getting stuck into Godot know about the changes. An in-editor warning informing you that you are using the deprecated version of the node names will also be useful incase some forget about this.

[Skaruts]

I agree, the longer it takes, the longer it will have a chance to confuse people. Tutorials and docs won't be immediately outdated if, like @AtomaFajrovulpo suggested, for a period of time the editor still allows the deprecated stuff but shoots out a warning. Something along these lines I suppose:

Node type 'Spatial' is deprecated and replaced by 'Node3D'. 

and

Method 'clip_polygon()' is deprecated and replaced by 'clip_polygon_3d()'. 

[BenjaminNavarro]

I found yesterday that constants don't all follow the same case. For instance there is Color.black and Vector3.UP. Shouldn't this be made consistent for 4.0?

[Calinou]

@BenjaminNavarro Changing Color constants to uppercase was also discussed at the bottom of #14704.

Also, method/signal/constant renaming should be discussed in #16863, as this issue is specifically about node names.

[BenjaminNavarro]

@Calinou Thanks, I was pretty sure there was other issues but couldn't find them.

[FrederickDesimpel]

I'd rather have the rename in 4.0 and be over with it then knowing it will come later after the project i'm working on has grown more.

if a major release isn't the time to do it, what is.

SemVer: Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

[FrederickDesimpel]

How far will you go with this?

Will GridMap then become TileMap3D, and Tilemap Tilemap2D for example ?

Also, node2D and node3D seem a bit generic, why not have Spatial2D and Spatial3D then ?

I think a big UX difference too would be to have control, node2D and spatial, whatever they will be named, directly accessible beneath node in the new node dialog, although node2D and control inherit from CanvasItem. You can't add a CanvasItem directly to a tree anyway, so maybe it should not be visible in that dialog.

And as far as methods go, i guess there is no need to add a 2D or 3D postfix on those, since you know what you call them on right ?

[clayjohn]

@qq715152910 Please don't comment on long threads with completely unrelated information. Everyone who has commented on this issue will receive a ping and your comment has nothing to do with the proposal for renaming nodes. As a result, I will be hiding your comment.

[rsousacode]

I'll give our opinion about some renaming that would be usefull for us (We use C# mainly)

The renaming that we strongly suggest:

1. Transform.origin -> transform.origin

(Making the access to a transform property lowercase)

Why?
For example the spatial has the Transform that we can access, but many times we write "this.Transform.origin" for better readibility, if we change "Transform" to "transform", we wouldn't need to use "this" all the time. That's our personal opinion.

2. We also support changing "Label" to something like "TextLabel". Or at least when we search by "text" when adding the new node, "Label" should appear, since it's totally related.

3. The constants for some predifined colors should be access with Color in contrary to Colors.

For the rest of the proposing renaming we look forward to what the community think is better.

[Calinou]

AtlasTexture -> TextureAtlas

It's named AtlasTexture because it follows the usual <Type>Texture convention where <Type> can be Image, Viewport, Stream, …

[rsousacode]

AtlasTexture -> TextureAtlas

It's named AtlasTexture because it follows the usual <Type>Texture convention where <Type> can be Image, Viewport, Stream, …

This what shows up when I type "Atlas".

This is what happens when we type Texture:

Edit: We understand why that convention. In the 2nd screenshot, AtlasTexture is very bellow with other things that follow <Type>Texture convention. Following that, that point was removed from our previous post. For this particular case is still not very autocompletion friendly. But we accept it. .

[aaronfranke]

@bigmonte The Transform struct will might be was renamed to Transform3D in Godot 4.0 as per this issue, so you will no longer need this. to make it clear that it's a property.

EDIT: #38430

The constants for some predifined colors should be access with Color in contrary to Colors.

I'm the one that proposed that in the first place, and I strongly disagree. It's better to keep them separate, since it increases discoverability of Color's static members (currently Color8, ColorN, and FromHsv) when using autocomplete in various IDEs. I'm also considering proposing a rename of Color.red etc -> Colors.RED in GDScript for consistency.

By the way, I think you were looking for #16863.

[ACB-prgm]

"a tool in Godot 4.0 that basically converts a script from 3.0 to 4.0"

Lol, I was just beginning to write a python script that would do this for all .gd files in the project folder from which it was run. How set are you on making this tool a thing IE should I give up on this haha.