Add Trait System to GDScript

[SeremTitus]

---

GDScript Trait System

Based on the discussion opened in:

• Add a Trait system for GDScript godot-proposals#6416

The GDScript trait system allows traits to be declared in separate .gdt files or within a trait SomeTrait block.

Traits facilitate efficient code reuse by enabling classes to share and implement common behaviors, reducing duplication and promoting maintainable design.

Syntax Breakdown

Declaring Traits

• Traits can be defined globally or within classes.

• In a .gdt file, declare a global trait using trait_name GlobalTrait at the top. trait used for inner traits.

• Traits can contain all class members: enums, signals, variables, constants, functions and inner classes.

  Example:

  # SomeTrait.gdt
  trait_name SomeTrait
  
  # Trait types used for typing containers.
  var player: TraitPlayable
  var scene_props: Array[TraitMoveable]
  var collected: Dictionary[String, TraitCollectable]
  
  func _ready():
      pass  # Method with implementation, but can be overridden.
  
  # Method to be implemented by the class using the trait.
  # The return type must be `void`.
  func foo() -> void # Bodyless need to be implemented in class using trait.
  
  # The return type can be overridden, but it's not required to specify one.
  func some_method() # Bodyless need to be implemented in class using trait.
  
  # The return type can be overridden but must be a class that inherits from `Node`.
  func some_other_method() -> Node  # Bodyless need to be implemented in class using trait.
  

Using Traits in Classes

• Use the uses keyword after the extends block, followed by the path or global name of the trait.

• Traits can include other traits but do not need to implement their unimplemented functions. The implementation burden falls on the class using the trait.

  Example:

  # SomeClass.gd
  extends Node
  
  uses Shapes, Topology  # Global traits
  uses "res://someOtherTrait.gdt"  # File-based trait
  
  func _ready():
      var my_animals : Array = []
      my_animals.append(FluffyCow.new())
      my_animals.append(FluffyBull.new())
      my_animals.append(Bird.new())
      var count = 1
      for animal in my_animals:
          print("Animal ", count)
          if animal is Shearable:
              animal.shear()
          if animal is Milkable:
              animal.milk()
          count += 1
  
  trait Shearable:
      func shear() -> void:
          print("Shearable ok")
  
  trait Milkable:
      func milk() -> void:
          print("Milkable ok")
  
  class FluffyCow:
      uses Shearable, Milkable
  
  class FluffyBull:
      uses Shearable
  
  class Bird:
      pass

Creating Trait files.

• In Editor go to FileSystem, left click and select "New Script ...". In the pop up select GDTrait as the preferred Language.
• Alternatively in script creation pop up instead of selecting GDTrait from 'Language' dropdown menu change 'path' extention to '.gdt' and language will automatic change to GDTrait
  

How Traits Are Handled

Cases

When a class uses a trait, its handled as follows:

1. Trait and Class Inheritance Compatibility:

The trait's inheritance must be a parent of the class's inheritance (compatible), but not the other way around, else an error occurs. Also note traits are pass down by inheritance, If a class is for instance "SomeTrait" also it here classes will be so.

Example:

    # TraitA.gdt
    trait_name TraitA extends Node

    # ClassA.gd
    extends Control
    uses TraitA  # Allowed since Control inherits from Node

2. Used Traits Cohesion:

When a class uses various traits, some traits' members might shadow other traits members ,hence, an error should occur when on the trait relative on the order it is declared.

3. Enums, Constants, Variables, Signals, Functions and Inner Classes:

These are copied over, or an error occurs if they are shadowed.

4. Extending Named Enums:

Named enums can be redeclared in class and have new enum values.
Note that unnamed enum are just copied over if not shadowing.

5. Overriding Variables:

This is allowed if the type is compatible and the value is changed.
Or only the type further specified. Export, Onready, Static state of trait variables are maintained. Setter and getter is maintained else overridden (setters parameters same and the ).

6. Overriding Signal:

This is allowed if parameter count are maintained and the parameter types is compatible by further specified from parent class type.

Example:

    # TraitA.gdt
    trait_name TraitA
    signal someSignal(out: Node)

    # ClassA.gd
    uses TraitA
    signal someSignal(out: Node2D) # Overridden signal

7. Overriding Functions:

Allowed if parameter count are maintained, return types and parameter types are compatible, but the function body can be changed. Static and rpc state of trait functions are maintained.

8. Unimplemented (Bodyless) Functions:

The class must provide an implementation. If a bodyless function remains unimplemented, an error occurs. Static and rpc state of trait functions are maintained.

9. Extending Inner Classes:

Inner classes defined in used trait can be redeclared in class and have new members provide not shadow members declared inner class declared in trait. Allow Member overrides for variables, Signals and function while extending Enum and its' Inner Classes.

Example:

    # Shapes.gdt
    trait_name Shapes
    class triangle: # Declared
        var edges:int = 3
        var face:int = 1
        func print_faces():
            print(face)


    # Draw.gd
    uses Shapes
    class triangle: # Redeclared
        var verticies:int = 3 # Add a new member
        var face:int =  2 # Overriding Variable
        func print_faces(): # Overriding Function
            print(face-1)

Special Trait Features

10. Trait can use other Traits:

A trait is allows to use another trait except it does not alter members of the trait it is using by overriding or extending.
However, cyclic use of traits (TraitA uses TraitB and TraitB uses TraitA) is not permitted and will result in error.

11. Tool Trait:

if one trait containing the @tool keyword is used it converts classes (except inner classes) and traits using it into tool scripts.

12. File-Level Documentation:

Member documentation is copied over from trait else overridden.

---

System Implementation Progress

• Implement and verify How Traits Are Handled
• Debugger Integration
• Trait typed Assignable (variable, array, dictionary)
• Trait type as method & signal parameters' type
• Trait type as method return type
• Trait type casting (as)
• Class is Trait type compatibility check (is)
• Make .gdt files unattachable to objects/nodes
• Hot reloadable Classes using traits when trait Changes (for Editor and script documentation)
• Making Traits not directly accessible member/calls/instancing
• Write Tests
• Write Documentation (user manual) docs#10393
• Override editor gutter icons
• "ctrl + click" integration with trait functions

Bugsquad edit:

• Closes Add a Trait system for GDScript godot-proposals#6416

[DaloLorn]

Is there a specific reason you specified a void return type for foo()? Do abstract methods always need a strictly defined return type?

If not, might I recommend a different return type for clarity?

[AdriaandeJongh]

(Edited because I missed a part in the OP description)

Fantastic start on this feature. Thank you!

One comment: please use implements over uses, as per the original proposal.

[DaloLorn]

I'm not sure your reasoning lines up with your conclusion there, but I can't say I have much of a preference, what with it being a strictly cosmetic affair.

[btarg]

This system seems very similar to the abstract keyword, which has already been suggested.. what makes this approach better than abstract classes?
I already use a lot of base classes with empty functions that are then overridden in my game currently. Will this improve the workflow comparatively?

[DaloLorn]

Abstract classes are still beholden to the class hierarchy: No class can inherit from two classes at a time.

There is some value in having both of these, I suppose, but traits are far more powerful.

[dalexeev]

This system seems very similar to the abstract keyword, which has already been suggested.. what makes this approach better than abstract classes?

See:

• Add a keyword for abstract classes in GDScript #67777
• Implement abstract methods in GDScript #82987

Also, as DaloLorn said, these are independent features that can coexist together. Traits offer capabilities that classic inheritance cannot provide.

[rrenna]

This looks great, will traits be able to constrain typed collections (ie. Array[Punchable], Dictionary[String, Kickable]) ?

[Dynamic-Pistol]

Amazing that somebody cared to make this,but since the original proposal is shut down,here is some feedback

1. use impl instead of uses,this makes more sense and also is short too
2. don't have a seperate file extension for traits,have .gd files be able to support different object types
3. no trait_name, name it instead type_name
4. traits should only have functions (abstract and virtual),no other stuff

[radiantgurl]

4. traits should only have functions (abstract and virtual),no other stuff

Considering work has already been made for signals, we should get to keep them too. (unless massive performance issues appear)

[Mickeon]

I am a bit concerned on the performance of this in general, but that would be something that can be solved over time. I am really, really ecstatic about this.

I agree. There's no reason to exclude signals from traits if the work has been done.

[radiantgurl]

Just some nitpicks, mostly you should rename uses with impl everywhere.

[AdriaandeJongh]

As various others have suggested to use impl instead of implements, I wanted to make a case against impl. Take this example:

class_name SomeClass
extends BaseClass
impl TraitA

• impl is inconsistently abbreviated next to the written-out extends and class_name keywords that will almost always be just above or below it.
• for non-native English speakers, impl is harder to understand at first glance, and un-google-able for translation.
• If contributors want Godot to be beginner friendly, writing out implements is the more friendly option here, because it requires less knowledge of the programming language and associated jargon.
• as rightfully mentioned on mastodon in response to me yapping about engine UX, impl could imply "implies", "impels", "implant", "implode".

The 6 characters impl saves over implements is not worth the confusion and inconsistency. Instead, perhaps you would agree with me that this is much more readable and consistent:

class_name SomeClass
extends BaseClass
implements TraitA

[Dynamic-Pistol]

impl is inconsistently abbreviated next to the written-out extends and class_name keywords that will almost always be just above or below it.

what would you abbreviate extends and class_name to? only answers i can think of is for class_name, which could be changed to use the script name, and extends could just be extend

for non-native English speakers, impl is harder to understand at first glance, and un-google-able for translation.

Pretty sure non-native speakers are able to understand abbreviations, by your logic int and bool should be Integer and Boolean, this doesn't include all the abbreviated types that exist already

If contributors want Godot to be beginner friendly, writing out implements is the more friendly option here, because it requires less knowledge of the programming language and associated jargon.

traits aren't exactly beginner stuff, when someone starts with a language they learn they might learn traits ,but for gamedev you don't learn certain stuff until you get the basics/become a casual programmer , when i was a unity developer, i didn't learn about interfaces (which are extremely similar to traits) until i had advanced enough and realised i need some other solution to inheritance

as rightfully mentioned on mastodon in response to me yapping about engine UX, impl could imply "implies", "impels", "implant", "implode".

this makes no sense? let's take a look at some example code:

class_name Door
extends AnimatableBody3D
impl Interactable

what would "implies" mean in a progammer context?, "impels" isn't even abbreviated correctly, "implant"? seriously?, "implode" would be a function for gameplay

The 6 characters impl saves over implements is not worth the confusion and inconsistency. Instead, perhaps you would agree with me that this is much more readable and consistent

previous points still matter, also rust uses the impl keyword, and i am pretty sure it popularized the concept of traits and yet still 0 complains from it

[OscarCookeAbbott]

Is using a separate file extension necessary? And if not, would it be better to stick to .gd? From a UX perspective it seems a lot simpler and easier not to.

[eon-s]

Is using a separate file extension necessary? And if not, would it be better to stick to .gd? From a UX perspective it seems a lot simpler and easier not to.

Extensions can be useful for quick search, filter, etc., without the need to check the content of the file nor adding extra prefix/suffix to file names (so it's better in UX terms), also can help other tools like the filesystem to implement custom icons.

[DaloLorn]

Put me down as another vote in favor of "implements", for what it's worth. I'm indifferent on "implements" versus "uses", but I'm not nearly so indifferent on "impl" versus "implements": The majority of Adriaan's concerns have not been addressed to my satisfaction.

[JJulioTLG]

As various others have suggested to use impl instead of implements, I wanted to make a case against impl. Take this example:

class_name SomeClass
extends BaseClass
impl TraitA

• impl is inconsistently abbreviated next to the written-out extends and class_name keywords that will almost always be just above or below it.
• for non-native English speakers, impl is harder to understand at first glance, and un-google-able for translation.
• If contributors want Godot to be beginner friendly, writing out implements is the more friendly option here, because it requires less knowledge of the programming language and associated jargon.
• as rightfully mentioned on mastodon in response to me yapping about engine UX, impl could imply "implies", "impels", "implant", "implode".

The 6 characters impl saves over implements is not worth the confusion and inconsistency. Instead, perhaps you would agree with me that this is much more readable and consistent:

class_name SomeClass
extends BaseClass
implements TraitA

I think uses is fine.

[antimundo]

I agree on "impl" been a very confusing keyword.

[radiantgurl]

To resolve the class reference error: Compile godot, then run ./bin/godot<TAB> --doctool, then push the result.

[SeremTitus]

Export type if is Trait must inherit from node.

Initially intended, however I will rework it

[SeremTitus]

In the recent push, exported trait-typed variables now align with the expected export behavior. Additionally, traits extending Nodes and Resources have been removed from various selection and creation windows.

[Dynamic-Pistol]

Made an interaction system with this, very pleased

have other issues tho

Issues

Variables

trait variables override the class variables and the only way to access the shadowed variables is to cast self to the base class and get the property

this also works even if the trait variable's type is different from the class variable

also untested, but i think the overriding variables with the same name and type count as 2 different variables, not sure so check

Functions

trait's functions work very weird with existing methods when the trait extends CollisionObject2D and has some methods of CharacterBody2D and a class extending CharacterBody2D implements that trait

the trait and the class will fight over the function definition and if you somehow settle it, the engine will give you a warning for overriding a class method that the trait demands (in this case the move_and_xxx twins)

Possible solutions

Variables

while the best solution is to simply not have variables in traits, i doubt it will happen so here is another possible solution

if the variable has the same name and type as a class's property, it will refer to that property (basically an alias/ptr if you will)

for the different type, i was going to suggest an alt to super for traits, but not sure how it would scale with multiple traits, a possible solution is to error if a variable with the same name but a different type exists in a class, but this feels wrong

btw did anyone check what happens if traits share a variable names?

Functions

if the function definition matches an existing function in a base class, you won't need to override it, this also solves my case

if a function's name but return_type/parameters don't match, there is a hacky solution i found

func MyTrait.my_class_func(same: Parameter) -> AndReturnType:
    pass

func other():
   #`tbase` stands for trait base
    tbase[MyTrait].my_class_func(blah_blah)

source:

Bad test.zip

[KoBeWi]

Exported Resources and exported Nodes work correctly now.

[WhalesState]

So Redot has already found this bug Redot-Experimental/RedotX@ed49262.

can we track it?

[AThousandShips]

We don't track bugs for un-merged features, but if the author of this wants to check that out for this PR that would make sense

[MarianoGnu]

Functions
if the function definition matches an existing function in a base class, you won't need to override it, this also solves my case

if a function's name but return_type/parameters don't match, there is a hacky solution i found

Traits should not override native class functions, that looks like a bug to me i dont think that is an expected usage of traits.

If the base class is CharacterBody2D it should throw an error as soon as you try to implement
func move_and_collide():

If your trait doesn't inherit from a class, but names a function, in this example, move_and_collide, then it should throw an error when attempting to use it

extends CharacterBody2D
uses MyTrait #This line should error because MyTrait.move_and_collide tries to override native method

[SeremTitus]

Functions

trait's functions work very weird with existing methods when the trait extends CollisionObject2D and has some methods of CharacterBody2D and a class extending CharacterBody2D implements that trait

the trait and the class will fight over the function definition and if you somehow settle it, the engine will give you a warning for overriding a class method that the trait demands (in this case the move_and_xxx twins)

extends CharacterBody2D
uses BadTrait

trait BadTrait:
    extends CollisionObject2D
    func move_and_collide()

Fixed by providing error "move_and_slide" variable from trait "BadTrait" shadows a native method of the using class. if similar error is hit trait should be dropped from uses, it also applies to all trait members vs all native members

---

So Redot has already found this bug Redot-Experimental/RedotX@ed49262.

can we track it?

Done

---

QuickOpenDialog now asks for trait types only when the resource script is changed, making it more optimized from the previous push

[KoBeWi]

You can use find_file() to get both the directory and index.

[KoBeWi]

That's not how cached data is usually handled in EditorFileSystem.

Check how other members of class_info are handled. The information should be stored in the filesystem cache file, so it's not re-initialized in every editor session.