Add `@override`, `@nodepath`, and `@not_null` annotations for early error detection

[ajafov98]

Describe the project you are working on

I'm working on my first serious game project with Godot - a 2D platformer with some basic inventory and quest systems. As the project has grown larger, I've encountered several types of errors that are difficult to trace and debug because they only manifest at runtime under specific conditions.

Describe the problem or limitation you are having in your project

I've encounter three major categories of problems:

1. Silent function override failures: Typos in overridden function names (like _proccess instead of _process) lead to hours of debugging. The function never gets called but the engine doesn't warn about this.

2. Invalid node paths: References to nodes in the scene tree frequently break during refactoring or scene restructuring. These issues only become apparent when that specific feature is used, often leading to crashes in edge cases that are difficult to test systematically.

3. Null reference errors: "Attempt to call function on null instance" is our most common runtime error. These frequently occur because of assumptions about initialization order or node availability that turn out to be incorrect.

All three issues share a common trait: they're discovered very late in the development process, typically during playtesting or after deployment, making them costly to fix.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

I propose adding three targeted annotations to GDScript that would help catch these common errors much earlier in the development process:

1. @override Annotation: Verifies at parse time that a function actually exists in a parent class to override.
2. @nodepath Annotation: Validates at scene load time that a node path exists (and optionally is of a specific type).
3. @not_null Annotation: Enforces that variables are assigned non-null values during initialization.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

1. @override Annotation

The @override annotation would verify at parse time that the function actually exists in a parent class.

extends Node2D

# This would cause a compiler error: "function '_proccess' does not override any function in parent classes"
@override 
func _proccess(delta: float) -> void:  # Typo in '_process'
    position.x += 10 * delta

# This would pass validation
@override
func _process(delta: float) -> void:
    position.x += 10 * delta

2. @nodepath Annotation

The @nodepath annotation would validate at scene load time that the path exists.

# This would validate that this path exists
@nodepath
@export var player_sprite_path: NodePath

# With path directly specified
@nodepath
@export var camera_path := "Camera"

func _ready() -> void:
    var sprite = get_node(player_sprite_path)
    sprite.modulate = Color.RED

As an optional enhancement, @nodepath could also validate that the node is of an expected type:

# This would validate that this path exists AND is a Sprite2D
@nodepath(Sprite2D)
@export var player_sprite_path: NodePath

3. @not_null Annotation

The @not_null annotation would enforce that a variable is assigned a non-null value during initialization.

# Must be initialized in _ready or _init
@not_null var weapon: Weapon

# Must be initialized in constructor call
@not_null var player_name: String

func _init(p_name: String) -> void:
    player_name = p_name  # Required, would error if missing
    
func _ready() -> void:
    weapon = $WeaponSlot.get_child(0)
    # If weapon is still null here, the engine would throw an error

If this enhancement will not be used often, can it be worked around with a few lines of script?

These issues cannot be effectively worked around in script:

1. For @override, I don't think there's any way to check if a function really overrides a function in parent classes. Only a visual tip in the lines which shows it's overriden.

2. For @nodepath, one can add runtime checks, but this is both boilerplate code and still only catches errors during runtime:

func _ready():
    if not has_node(player_sprite_path):
        push_error("Invalid path: " + str(player_sprite_path))

3. For @not_null, one could add assertions, but these still only fire at runtime:

func _ready():
    assert(weapon != null, "Weapon must be initialized!")

The main benefit of these annotations is catching errors earlier in the development process (parse/load time rather than runtime), which no script workaround can provide.

Is there a reason why this should be core and not an add-on in the asset library?

From what I understand so far about Godot, these features need to work with the parser and compiler, which I don't think add-ons can modify because they all require deeper integration with the engine. Generally useful features that would benefit a large percentage of Godot projects by catching common bugs early, making them appropriate for core inclusion.

[Calinou]

• Related to Add GDScript support for defining virtual/prototype/must-override methods in base classes #1631.

Regarding @nodepath, I think it would be better to make invalid node paths cause a debugger break so you notice it immediately when running a project (instead of just printing an error that's easily missed). There's a proposal on the subject, but I can't find it right now.

The @not_null annotation would enforce that a variable is assigned a non-null value during initialization.

I think this would be better implemented as #162 having a not-null equivalent.

[dalexeev]

Thanks for the proposal! Please do not combine several unrelated topics into one proposal, create several proposals if necessary. Also, these or similar ideas are already being tracked here:

• Overriding methods
  • Add a const/final qualifier for methods that shouldn't be overridden #1311
  • Add GDScript support for defining virtual/prototype/must-override methods in base classes #1631
  • @override and super #3936
  • Add more control for overriding functions in GDScript #4009
  • Implement mustoverride/abstract class members in GDScript #6973
  • Update private member style in GDScript style guide. #10342 (comment)
  • Add a @final method annotation to GDScript #10500
  • Implement an explicit virtual method mark for GDScript godot#103859
• Scene validation
  • Allow us to strongly type packed scenes #782
  • Add scene binding for optional tight-coupling between Node-extending Scripts and PackedScene resources #1935
  • Add a generic parameter to PackedScene (like Array) to allow for easier type safety #6694
  • Static Scenes #7572
  • Allow preloaded PackedScenes as static type hints #8565
• Null safety
  • Add support for nullable static types in GDScript #162
  • Add union types to Typed GDScript #737
  • Implement tagged union types in core (and eventually GDScript) based on std::variant #8265
  • Make objects non-nullable by default #11054

[ajafov98]

• Related to Add GDScript support for defining virtual/prototype/must-override methods in base classes #1631.

Regarding @nodepath, I think it would be better to make invalid node paths cause a debugger break so you notice it immediately when running a project (instead of just printing an error that's easily missed). There's a proposal on the subject, but I can't find it right now.

The @not_null annotation would enforce that a variable is assigned a non-null value during initialization.

I think this would be better implemented as #162 having a not-null equivalent.

Thanks for the feedback.

Regarding the relation to #1631 (virtual/prototype/must-override methods):
I think my @override annotation would actually complement that proposal nicely. While #1631 focuses on enforcing that child classes implement required methods, @override would help catch typos and errors when developers intend to override existing methods. They solve different but related problems.

Regarding @nodepath and the suggestion about debugger breaks:
I completely agree! A debugger break would be even better than just an error message. The goal is to catch these issues as early as possible in the development process. Whether it's implemented as a debugger break or an error, the key benefit is having immediate feedback when a path is invalid.

Regarding @not_null and the relation to #162 (nullable types):
This is a great point. My proposal and #162 are addressing two sides of the same coin. Nullable types (Vector2?) would make it explicit when a value can be null, while @not_null would make it explicit when a value cannot be null. Both approaches would help make null reference errors less common.

[ajafov98]

@dalexeev

Thank you for the comprehensive list of related proposals!

You're right - I should have separated these ideas. I initially conceived this as a general validation annotation system with these three as examples, which is why I grouped them together. Now I see it was a mistake.

For clarity on @override: My proposal is specifically about validation (validate if it really overrides method from parent class) rather than enforcing overrides like most existing proposals.

Should I close this issue and create three separate proposals instead?

[cruglet]

For clarity on @override: My proposal is specifically about validation (validate if it really overrides a method from the parent class) rather than enforcing overrides like most existing proposals.

I wonder if something like this could be implemented by changing the SyntaxHighlighter to indicate when a method overrides a parent method? I like the idea of having something like @override to visually distinguish overridden methods but having to type @override every time you want to do this feels like it could get tedious. By changing the color the editor automatically tells the user implicitly whether they properly overrode a method or not.

I suppose another visual alternative in order to avoid confusing the annotation with something else could be to add a new comment highlight color, something like:

# OVERRIDE
func my_method() -> void