The Missing Principle: When should a feature be implemented as a Node?

[Nodragem]

Introduction

There seems to be a consensus that Nodes are at the core of Godot's philosophy. However, there is no clear rules or principle that let the community of developers decide easily when a feature should be implemented as a Node. This can sometimes create tension, hot debates and frustration.

I am opening this discussion so that the community of gamedev, engine dev and maintainer can reflect together on why do we have Nodes, what is their role, and so when should a feature be a Node?

First, let's state the problem, a lot of features can be implemented either:

• as a set of functions (library?) only available from scripts (code) or,
• as a node available from the editor.

For instance, the Tween feature is currently at the center of a hot debate, because it was implemeted as a Node in Godot 3, and then reimplemeted as a set of functions in Godot 4, and the Node was removed. Some argued that there is no need to have both, but in fact there are many features that are implemeted both as a set of functions and as a Node (e.g. Raycasts, Timers).

Furthermore, new comers can be confused as to why we can do Raycast as a node, or as a function call in script. I believe this confusion can be resolved by understanding, as a community, why/when we should use Nodes, and writte that principle in the documentation.

Nodes vs Function calls, my personal take

I personally believe that Raycast and Tween should both be implemented as a Node and as a set of functions. Nodes are about exposing functions/features in the Editor. While set of functions are about letting the programmers do they own stuffs, and not expose everything in the editor.

Here is my take on when to use a Node rather than a function call:

• visual documentation in the editor: using Nodes, I make my object structure visible in the editor, which is documentation. I click on an ennemy node, and I see there is an AttackTimer, a AttackTween, a StateMachine, etc. The Raycast node will show me where are the rays in the editor.
• visual building/scripting/workflow: as a gamedev, using Nodes I can build Raycast and Physics Joints, place them, link them without a line of code. As a engine developper, using Node, I can expose a whole visual workflow in the editor (e.g. TileMap Editor, AnimationTree), which saves lines of codes to the gamedevs.
• exposing parameters to non-programmers: using a Tween node, I expose its functionality to the UX/UI designer in the editor. I don't want him to go play with my code, neither do they. By using a Node, the UX designer can tweak the animation in editor, and play safely with it.
• discoverability in Add Node menu: all users know about the Add Node button. New users easily discover useful features from there, and go further with scripting later on (e.g. Timer).

So in short, Nodes are about exposing a feature in the editor.

Reciprocally, here is my take on when using a set of functions (i.e. script only):

• as a gamedev you don't want to expose the object's functionality (e.g. Tween) in the editor
• as a engine developper you don't want the feature to be tweakable in editor.
• as a engine developper, it would take too long to make the feature tweakable in editor and no real benefit. For instance, the RenderingPipeline could be a node, but it would be a lot of work to make it fun to use in the editor (?)
• as a gamedev, you think it would optimise performance, or decrease manual work not to use the Node. For instance, you want to create 100 raycasts from arbitrary locations.
• as a gamedev you think that there is no reason to attach the functionality to an object in the editor

Is it really more work to implemented both the Node and the Set of Functions?

@Calinou recently raised the point that they needed to chose between a Tween Node or a Tween set of functions, cause it is too much work to maintain both. But let's say we implement a Tween Node, won't we be writting a Tween set of functions to support that Node anyway? Maybe we could write Nodes so that they are based on the same set of functions we want to expose to the programmers in the API?

Suggested Principle:

Let's see where this discussion goes!

Thank you reading, please let me know what you think below!

[theraot]

Looking at the existing Nodes these are the resons I can see to implement something as a Node:

• If it needs to have a position, it must be a Node.
• If it Contains Nodes, it must be a Node.
• If it is an easy to use version of a low level API, it should be Node. A versatile low level API and an easy to use solution covering the common use cases is part of Godot's best practices (※).
• If it References Nodes, it is beneficial for it to be a Node.
• If the implementation is easier by taking advantage Godot calling Node virtual methods, it is beneficial for it to be a Node.

Of course, this is only looking at one side of the argument, we also need to see reasons why not to implement something as a Node.

---

It is OK to have two ways to do something. For example, one high level and one low level. In fact, when there are compeeting ways to do something it makes sense to build them on top of a common foundation (either via a low level API, or via inheritance).

When the ways to do something become a maintenance burden, then it makes sense to remove the less powerful one once we know it could be built on top of the other. But that does not mean the removed implementation was wrong.

---

I want to highligh that sometimes a Resource is another way to implement a feature. For example, instead of a NinePatchRect we could have a NinePatchStyleBox.

Also, sometimes the low level API exists but is not exposed. For example the low level API for playing audio is not exposed. It should be!

[menaechmi]

I am new to the Godot community, so I wanted to provide insight on this topic from that perspective, and I hope it's helpful..

---

I want to start by saying that one of the reasons for this divide might come from the doc "Overview of Godots key concepts"

Every game engine revolves around abstractions you use to build your applications. In Godot, a game is a tree of nodes that you group together into scenes. You can then wire these nodes so they can communicate using signals.

(Emphasis original)

Later on in the introduction's Step by Step""Nodes and Scenes" explicitly states:

Nodes are the fundamental building blocks of your game

(Emphasis original)

So some of the earliest exposure to learning Godot focuses on the importance of Nodes. "Overview of Godot's key concepts" was available for the first time in 3.4, which is the same release where "Scenes and Nodes" became "Nodes and Scenes" and "Nodes are fundamental building blocks for creating a game" became "the fundamental building blocks" (emphasis mine). This also coincides with a large bump in Godot's popularity.

Most of the Manual is also written to accommodate using the editor/Nodes. It's confusing mixed-messaging to read the manual, and then see opposition to things being a Node.

---

The Godot interface feels like it wants there to be a very clear and distinct difference between editing Nodes and editing scripts, and it often feels arbitrary and pointless. Almost like Godot wants Nodes to only represent visual elements - even though this isn't how the engine works.

Quick examples:

• Scenes are saved as text files, but you cannot edit these in the script editor (because they're not scripts).
• Signals can be connected entirely visually, and it will create a line in the script for you, but creating a signal must be done in the script editor only. Even if a signal only needs to be signal name

I think that if this divide was better addressed, we would find it wouldn't matter as much if something was a Node or not.

One way I could see addressing it specific to this discussion would be some way of exposing a general Object in the scene tree. This negates the only argument I've seen presented against classes like Tween being Nodes - that it adds extra work to the Godot Developer making or maintaining the feature, while allowing all of the benefits of having these Objects be nodes.

[theraot]

These are not beginer topics, but I rather point them out than to gatekeep information...

---

For example, if I make a Node completely through the script editor, it will never display in the 2D editor because the code isn't being run and it's not a part of the scene until that happens.

The code will run in the editor if you make it in a @tool script. And the nodes will show up if you set the owner property correctly. See Running code in the editor.

The thing is, if your code runs in the editor, it can do much more than create some nodes. It can crash the editor, and it can modify the editor. Godot happens to be vary maleable for this because - brace yourself - the Godot Editor UI is made with Nodes.

---

Then if an engine developer doesn't want to make Node, they don't have to.

You can create a custom MainLoop class, or you can run an script from command line (see Command line tutorial). In either case you do not need a Node to execute code. Yet, the use cases for these features are not very common.

And you can do a lot without Nodes working with "Servers" directly, see Optimization using Servers. However, it is faster to prototype and iterate using Nodes.

---

Yes, you need code. Godot is not a "No Code" engine. Although it should be possible to build one on top of it.

[menaechmi]

I think I was perhaps a little unclear in my phrasing, especially when I used generalized terms. I'm going to edit my original comment to be clearer with what I mean. Thank you for linking everything you did! The versatility of Godot never ceases to amaze me, even if I will probably never have to use them.