GDScript: Trait system design

[dalexeev]

• Add a Trait system for GDScript #6416
• Add Trait System to GDScript godot#97657
• GDScript: Add Trait System godot#107227

Here you can discuss various aspects of the trait system. Please use separate branches for different topics: implements vs uses, traits vs interfaces, etc.

[Meorge]

One thing I've thought a lot about for the trait system is the naming convention for traits. To fit the English-like readability of the rest of GDScript, I propose PascalCase adjectives. For example, a trait that allows a node to be interacted with could be called Interactable, or a trait that runs a method when shot by a bullet could be called Shootable. This makes trait conformance/usage checks read like English:

if some_node is Shootable:
    some_node.on_shot()  # on_shot() is a method on the Shootable trait

I know C# uses the I prefix for interfaces, and we could perhaps similarly use a T prefix for traits:

if some_node is TShootable:
    some_node.on_shot()

This looks a bit weirder to me personally, though, so I think I'd prefer the first option. Of course, if anyone has other ideas, please express those as well!

[SeremTitus]

I prefer the first one (Shootable) and the use of -able suffixes where applicable. I also suggest we consider having different syntax highlighting colors (perhaps different shades of the same color) for built-in types, class types, and trait types.

[Mickeon]

I would heavily recommend no prefixes of that sort. This kind of thing is very much not in the style of GDScript (and is frankly outdated, as modern IDEs and better naming conventions solve any possible ambiguity).

[Shadows-of-Fire]

There should be no type prefixes nor conventional type prefixes. C# uses the I prefix on very old microsoft convention that derives from C++ (where they also used it) due to lack of separation between interfaces and otherwise "normal" classes.

Once you actually have a first party keyword for how these things operate (implements/uses instead of extends) you don't need special naming markers. They're very much a relic of the past.

[hantaogo]

[lostminds]

In the definition row I think both with and is sort of assume they'll be used on a single row with class_name and extends. But just like you can currently write class_name and extends on separate rows (and in either order?) I think this also needs to be considered for the traits definition keyword. And written on a separate row I think something more descriptive could work better. Why not literally use traits to also communicate that this is what we call this sort of thing in GDScript.

For example:

class_name Player extends CharacterBody2D traits Mover, Movable, Damageable

class_name Player 
extends CharacterBody2D 
traits Mover, Movable, Damageable

[Meorge]

I agree, but I feel like the same could also be said for the extends keyword. traits seems to me like it could end up being confusing: trait SomeTrait means that a trait named SomeTrait is being defined, whereas traits SomeTrait would mean that the class is using the trait named SomeTrait...

What about a mix, like has_trait?

class_name Player
extends CharacterBody2D
has_trait Mover, Movable, Damageable

I suppose the plurality doesn't quite line up (and also wouldn't if it was has_traits with a single trait), but it's a bit more explicit about what the keyword does

[lostminds]

Ah, indeed, I didn't consider the possible confusion between trait in the trait definition file and traits for what such traits a class would use, you're right that those are a little too similar. To differentiate them, another option could be to keep traits and instead change trait, for example to trait_name to be consistent with class_name.

So then you'd have something like

trait_name MyTrait

<definition here>

class_name MyClass
extends Node
traits MyTrait, MyOtherTrait

<definition here>

Regarding the plural in traits I still like it as it hints at the key feature that you can have multiple traits, while you can only have one class_name or inherited class in extends.

[DaloLorn]

I liked uses, myself, but for the sake of broadening the list of options...

Perhaps includes might work? (I do conditionally prefer trait_name over trait, though, as long as it's meant to be an analogue to the global-scoped class_name and not the class-scoped class.)

[evanvlane]

I would like to have them as separate declarations, as the inline version makes it a bit harder at first glance to tell where the inheritance stops and the traits begin.

[ydeltastar]

I see there are no VM changes in godotengine/godot#107227. Is the goal for it to be a runtime feature, or like Python's typing module, which is hints for editor features but has no runtime impact?

[dalexeev]

Yes, that was the original idea, George even wrote about it somewhere. This feature is mostly resolved at compile time, at runtime it only affects the is operator.

We also have some concerns about typed arrays/dictionaries. But since we don't have a unified type system and first-class types yet, we decided it would be better if this feature was not available for typed arrays/dictionaries than if we touched the core, outside the GDScript module.

[hydescarf]

I was thinking of unifying them all under a single word has, that can be meant for only traits & checking with it, just like is for classes.
Though possible confusions are the has() functions, or to newbies, the equivalent confusion of is with ==.

class_name CustomClass
has CustomTraits1, CustomTraits2

if CustomClass has CustomTraits1: # don't mix `is` with classes?
    pass

Or perhaps, the original uses.

class_name CustomClass
uses CustomTraits1, CustomTraits2

if CustomClass uses CustomTraits1:
    pass

[Mickeon]

has in Godot... often refers to "containing" something, be it a value, property, method, signal, etc. So I would avoid it for that alone.

[shanayyy]

Why not use impl like Rust?😂

class_name Character impl Movable, Damageable

[Meorge]

My recollection is that impl was one of the earliest suggestions, since traits overall are commonly associated with Rust, but people weren't a big fan of how it shortens the word, unlike the other keywords like class_name and extends.

We do have var instead of variable and func instead of function, so there is certainly precedent for keywords being shortened. Alternatively, I feel like implements, while a little long, wouldn't be too egregious since it's just written once at the top of the file:

class_name Character
extends CharacterBody2D
implements Movable, Damageable

[shanayyy]

After seeing so many suggestions below, I think implements is the best -- it accurately conveys the meaning and aligns well with the existing naming conventions.

[UnTabouret]

With the current implementation of traits, is it possible to statically type/type check for traits ?

var foo : Movable

if foo uses Movable:
    foo.move()

Also if yes, would the second example enable autocompletion for Movable properties and methods like the following would ?

if foo is MyClass:
    foo.method_of_myclass() #this will be autocompleted in the editor

[SeremTitus]

type checking is not included in the current iteration. and when added is will be used

[Shadows-of-Fire]

Is it planned to be added in the current PR? That sounds like a must-have feature for merge.

[Gromnax]

Reposting that in the correct thread:

1. apparently traits can't use other traits when stored in separate files and with no class_name defined? This doesn't necessarily might be a bug, just a consequence of how GDScript is scoping things.

There no global traits in this pr. To get to a trait go through global class if it is in another file

2. Mixed "extends" in subtraits

The errors are correct. When a trait extends it can use properties and methods from the class it extends. So if the Trait is used it expects also that class to have the same properties and methods. In your case, Fix by making your class extend Node3D @tehKaiN here is an example:

trait Movable extends Node2D: # this trait can not be used in class that is not a descendant of Node2D
    func move_right():
        position.x += 10 # position is from Node2D

class Player extends Sprite2D: # here extends can also be Node2D. It will work
  uses Movable # usable because Sprite2D is a descendant of Node2D
  func _ready():
      move_right()  # Call method from the trait

Small suggestion, use another keyword instead of extends. Extends might cause confusion implying Movable is a node, which is not the case (unless I understood it wrong)

trait Movable requires Node2D 
trait Movable implies Node2D
trait Movable concerns Node2D

et caetera

[DaloLorn]

It will be a piece of a subclass, which can be combined with other such pieces at the developer's leisure.

I can't really offer a more satisfactory explanation: Barring a complicated class hierarchy, the distinction between "this should be a trait" and "this should be a class" is blurry at best. But at the end of the day, it's up to the developer to make the final decision, so Gromnax and his sample code are the final authority on whether Movable is a trait.

[shanayyy]

I realized that there's a good reason for Moveable to be a trait -- it allows for multiple inheritance. For example, in the case where Player inherits from Sprite2D and also uses Moveable, which wouldn't be possible with plain subclassing.

[DaloLorn]

Yep! That's the main point of traits as proposed, IMO. Even without the ability to offer a default implementation, reconciling incompatible hierarchies to present a unified API to downstream consumers (i.e. my other scripts) is a godsend in itself.

[Gromnax]

I wonder, from a design perspective, instead of having it being part of the inheritance tree to make sure a node has some of the parameters it needs to work, wouldn't it be cleaner to have the parameters in question bundled with the trait?
For a Moveable2D trait, it could have the position.x and position.y parameters. If a node has them, it basically uses these, but if it does not, it comes bundled with it?

I suppose I'm just trying to see that from a Composition over Inheritance POW though, maybe it's not the good mindset to have.

[Zephilinox]

I wonder, from a design perspective, instead of having it being part of the inheritance tree to make sure a node has some of the parameters it needs to work, wouldn't it be cleaner to have the parameters in question bundled with the trait?
For a Moveable2D trait, it could have the position.x and position.y parameters. If a node has them, it basically uses these, but if it does not, it comes bundled with it?

I suppose I'm just trying to see that from a Composition over Inheritance POW though, maybe it's not the good mindset to have.

a bit like Interfaces in Go? where anything that meets the requirements implicitly can be constrained to the interface, so the declaration doesn't need to explicitly opt-in to the interface

it's quite nice and allows user code to be written with support for multiple kinds of things, without having to actually change the source code of them

or for a compile time comparison, concepts in C++ achieve the same thing

traits don't achieve that if I'm understanding it correctly, the class needs to explicitly use a trait for it to get type matched against it. The Go interface is much more similar to gdscripts duck typing style, but with the massive advantage of type safety

but you mentioned if it doesn't have what it needs, it will add it. I'm not familiar with another language that does something like that. it sounds interesting but it creates some confusion from the user side on what something needs vs what something provides

[Shadows-of-Fire]

Was there discussion on using interfaces (which cannot define data ownership, only API surfaces) over traits? I feel like the introduction of multiple inheritance through traits (and the accompanying collision resolution strategies and class data layout questions that come with it) is a large can of worms.

[HolonProduction]

In the end interfaces and traits are just labels that differ in behavior between languages. If you see problems with the current solution, we should talk about the specifics.

Also I think it is important to keep usecases in mind. The intended usecase for traits right now is to have a way to reuse code aside from the inheritance tree. Traits are in their current form no optimal solution for the API surface usecase, since they are incompatible with typed collections.

and the accompanying collision resolution strategies

Why would it be easier to resolve a conflict between two interfaces? Two interfaces with a function of the same name would be incompatible the same way as traits as far as I understand.

class data layout questions that come with it)

What's the problem here? At the moment GDScript uses the Script system which always uses key based property lookup afaik.

[Shadows-of-Fire]

Why would it be easier to resolve a conflict between two interfaces?

Interfaces only carry methods. Two methods with the same name and signature should be compatible and not cause a conflict. While it is arguable that traits are an extension of interfaces, traits allow you to pin data to things, and data conflicts are not resolvable (so you have the added footgun of making things incompatible by giving them data ownership).

Functions of the same name with a different signature, however, are always going to conflict due to GDS rules. Maybe we can relax that in the future? That would require full static typing, though (I think).

At the moment GDScript uses the Script system which always uses key based property lookup afaik.

Oh, yeah I guess if everything is thrown in a Map<String, Variant> internally then it just works™.

[Aratch]

This may come off as a bit of a rant, but here's my 2.5 cents:

"Pure" interfaces (like in Java) that don't allow the addition of fields except through the explicit interface-level declaration of setters and getters are less flexible than traits (as they are presented here) and would go against the GDScript philosophy, IMHO.

Unlike most major object-oriented languages, GDScript doesn't enforce any visibility/access restrictions (even Python has more of that), and while you can define explicit setter and getter methods for custom behaviour/side-effects, the preferred way of accessing and mutating fields is still through the dot notation. Case in point, in Godot 4, custom setters and getters are called every time regardless of context (IIRC). Why would you want to limit traits to "public" (which, again, isn't a useful concept here) method declarations when, realistically, you should be able to expect a class that exposes/uses a trait/interface to have certain accessible/mutable fields? What is there to gain from forcing people to write

interface Damageable:
	func get_health() -> int
	func set_health(health: int) -> void

instead of

trait Damageable:
	var health: int

except that it violates some arcane OOP dogma? GDScript isn't an "enterprise-level" language. Chances are, you're looking at your code, trying to figure out pragmatic solutions to your problems. If you are treating every field as if it were public, then it's your problem. But sometimes, fields need to be public. And the structure of the data of several classes need to be compatible to each other without requiring inheritance or some weird kind of encapsulation.

[SeremTitus]

I have handled collisions all ready in traits, so this may not be a concern

[lord-muad-dib]

hello, is it possible to add/remove traits runtime? aka under a condition or event. thanks

[sockeye-d]

Why? Traits are meant for compile time safety

[lord-muad-dib]

for example, it's useful if you have a base object and you want to dynamically have it react differenctly on different spawn. instead of statically create similar objects with few different traits... or playing with nodes and composition

[Shadows-of-Fire]

Generating classes with additional traits dynamically would require runtime generation of classes. While that may theoretically be possible, it is out of scope here. And honestly, I don't think it would be the solution you want anyway (since dynamically generated classes would still be a static enumeration of the possibilities).

What you want is a container object which may contain a dynamically populated map of sub-elements (which is... really just a string->object dict with a contract).

[lord-muad-dib]

yeah that's what i thought seeing how it's called in the class declaration. it would be nice to have it explored in the future though :) thanks anyways 👍 i guess i'll have to stick to the old ways for now

[evanvlane]

Agreed with @sockeye-d . I'm picturing something like a BoTW-style system where things can be burnable but only if not wet. In that case, though, I think I would declare the class burnable and then implement the state logic in the burnable trait method.

I don't see a lot of cases where I want to dynamically change the signature of the class. You could early-out in the `burnable method, for instance.

if not is_currently_burnable:
    return

[ajreckof]

One thing I would like to adress is the use of unimplemented functions. Since abstract functions are already that and are part of the engine. The only difference between the two is that unimplemented would force abstract class to implement the function while abstract functions wouldn't require that. In most cases I think not forcing the abstract to implement anything is what is expected.

Except if there is a particular reason unimplemented adds a lot of value compared to abstract function I think it shouldn't be added as it will add confusion and will add maintainance cost

[Shadows-of-Fire]

Well, yeah, we could have traits declare explicitly @abstract methods; it just seems unnecessary since the lack of a body implies that it is abstract, and there is no contract that a trait must be fully-formed (i.e. you would not have an @abstract trait. I guess you could? But it seems a bit unusual to me).

[dalexeev]

In that case, regular classes could also have implicit abstract methods (if a function has no body, it's abstract). @abstract serves to show the compiler that you explicitly want to create an abstract method, and haven't accidentally forgotten the body. And traits are no different from regular classes here; they can also have both abstract and concrete methods.

Yes, traits are always abstract by definition (cannot be instantiated), unlike classes, which can be both abstract and concrete. So, @abstract trait would be redundant. But this has nothing to do with the abstractness/concreteness of the methods themselves that are contained in the class/trait.

If we decided to add interfaces too, in which all methods are "abstract" (or, you could say, interfaces don't contain method definitions, but only a list of required methods for classes that implement the interface), then I would agree with you, @abstract seems redundant in interfaces. But in the case of traits, I would prefer explicitness, since both types of methods (abstract and concrete) are possible.

[DaloLorn]

Personally, it's a little late for it, but I would have preferred a prefix (e.g. abstract func) over an annotation.

[sockeye-d]

There was a discussion about that decision if you want to read more. I would prefer abstract as well but I think the reasoning is solid and it's probably just out of familiarity that the annotation seems a bit strange.

[Shadows-of-Fire]

If we decided to add interfaces too, in which all methods are "abstract"

I don't even think that becomes a fair definition of interfaces these days. Languages with interfaces (such as Java) typically permit those interfaces to supply method implementations (i.e. default methods).

A trait, then, is simply a superset of what an interface is - an abstract construct which may define both data (definitions) and methods (either declarations or definitions).

So it's really about assumed user intention and what makes more sense as the default state, and if switching between states needs to be explicit or not. Since the trait itself is implicitly @abstract, it isn't crazy to assume that a bodyless function in a trait is also implicitly @abstract, but it is just as reasonable to require that be explicit.

---

Aside, I think the use of an annotation here is incorrect, but that ship sailed before I ever landed here :p

[nkrisc]

What governs if a trait's method will run in the editor? Suppose I have a class:

# A.gd
@tool
class_name A

trait TraitA:
    func foo(): print("foo")

And another:

# B.gd
class_name B
uses A.TraitA

If I call foo() on an instance of class B in the editor, will it print, or will the method not be found? Or is that still simply determined by whether B.gd is a tool script?

My hope is that it would, as it would be nice if traits could run code in the editor without having to make every class that uses it a tool script also, even if they don't need to be otherwise.

If that's not really feasible or possible, then oh well, traits will still be a huge improvement for lots of things.

[SeremTitus]

Currently trait can not be tools but can be used by tool classes, in the Og pr you could add @tool to trait that just forced the implementing class to also use @tool - I had to drop it though -

[nkrisc]

Thanks for clarifying, and thanks for the work you've done. The more I thought about it later after posting the more I realized how convoluted what I was asking could actually become.

[Fatbonks]

is the trait system still going to use is/as to be able to check if a trait exist in a class? or has it been dropped

[tehKaiN]

From my understanding it will come later since the old PR was too big for a review. Last time I read about it, the plan is to merge it in bit by bit.

[CopeFiend]

Regarding the keyword for trait implementation, how about the keyword applies?

class_name Enemy
extends Node2D
applies Damageable, Movable

In general, in fits the GDScript style of using plain English, especially verbs, to convey meaning. It is more precise than terms like has, is, with etc.

Comparing it to other "verb" keywords:

1. uses
uses Implies pre-built functionality. If you "use" something, it means the thing can already run on its own.

# Do I just get these traits for free?
# This reads more like a plugin/module
class_name Enemy
extends Node2D
uses Damageable, Movable

In contrast, applies denotes that declaration must be followed by implementation.

# I have to apply for something, like a contract
# There are rules to follow before things can work
class_name Enemy
extends Node2D
applies Damageable, Moveable

2. implements

Synonym to applies, but with one major difference,

class_name Foo
extends Bar # 7 characters
applies Baz  # also 7 characters

class_name Foo
extends Bar # 7 characters
implements Baz # 10 characters
# You are going to be looking at these a lot

Having a perfectly aligned declaration would look prettier than not having one, especially when you consider how often they would appear.

3. extends

I believe classes and traits are different enough to warrant separate keywords, not to mention situations like

class_name SomeClass
extends TraitA, ClassA, TraitB

That is all.

[FabriceCastel]

The way you parse that makes sense to me. I don't think it's outright unreasonable, but I do think that applies is no more legible to a beginner than uses as far as keywords go, and that for anyone with more experience writing software they're more likely to resonate with uses over applies as it's present in a number of programming languages already whereas I've never seen applies used as a keyword (across the dozen or so languages I've used over the years at least)

So.. all in all, applies offers no benefit to beginners and is less familiar to experienced folks, which makes it seem like a worse option IMO.

[tmilker]

A trait is something that is possessed, i.e. thing has trait X. In the cases of uses and applies, neither one make sense because of the possibility of both abstract and concrete traits. You don't use or apply imaginary things that will be defined in the future in the case of the abstract. You also don't really apply contracts, as previously stated, their terms are fulfilled by the parties to the contract. There's better things implements could be used for in the future like interfaces. has is too general to limit it to just traits and it would be better used like is to determine if something has a trait than (ab)using is to conflate identity with possession. concerns is just a no.

I'd much prefer has_trait/has_traits which both mean the same thing, the plural version just being syntactic sugar when specifying multiple traits at once. It's direct and explicit, there's no vagueness about what's being stated and doesn't collide with future keywords.

fulfills could be a decent alternative if traits are considered a synonym of contracts.

[clarence112]

There's better things implements could be used for in the future like interfaces.

In my opinion, traits and interfaces are functionally identical. They both ultimately achieve the same thing, and as a result, I find myself preferring the "implements" keyword over the other options.

[Meorge]

My understanding is also that traits will be GDScript's version of interfaces; trying to introduce interfaces on their own would introduce too much overlap and be confusing

[tmilker]

If traits are Godot's version of interfaces, I'm cool with that too. 😀