Rename `@export` annotation to be less confusing

[h0lley]

Describe the project you are working on

Any project that makes use of the @export annotation with the intention to expose a variable to the editor inspector.

Describe the problem or limitation you are having in your project

I think there's a couple of downsides in terms of ambiguity to the export keyword. It has a strong meaning elsewhere in game development and editors in general, such as exporting the project, exporting an asset, etc.

As a consequence, looking up documentation and past help threads can be cumbersome. I've often found myself on the wrong docs page or having to sift through search results. it can also be confusing when asking questions about it. for instance, which kind of export is being referred to occasionally needs to be clarified in Discord help channels.

Some proof of the poor searchability: exported property - doesn't show up at all export - shows up as the 22nd item GDScript export - 22nd item again exporting - 17th item

you pretty much need to remember the exact title of the article - GDScript exports - do find it quickly. although to be fair that is also to some extent and issue of the readthedocs search. Google does a better job.

Furthermore, I think it's not even a particularly good word for describing the feature. Quoting @aaronfranke here:

In terms of English words, exporting something does not necessarily imply storing it, in fact a good/product exported overseas typically means the opposite of storing it, it's shipped away.

Other users have also expressed confusion about it.

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

The first term that shoots to mind as an alternative is @expose. Although it's a minuscule difference, I feel like it describes what users generally expect from this feature - exposing a variable to the inspector - much better. It's also a short and concise keyword similar to export, but without the ambiguity issue.

There has been some critique to that idea brought up by @pycbouh: 1, 2, 3 they explain that @export does more than just exposing to the inspector, such as serialization and storing on disc, but personally I don't see how export does encapsulate that any better than expose. Once again, I think @aaronfranke put it best:

if we can say "exported variables are stored by default", why can't we say "exposed variables are stored by default"?

On the other hand, if the current @export keyword has two distinct use-cases, then perhaps it should be split up into different annotations as mentioned by pycbouh.

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

A simple replacement of @export for @expose, including the variations such as @export_range() becoming @expose_range().

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

n/a

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

n/a

[YuriSizov]

they explain that @export does more than just exposing to the inspector, such as serialization and storing on disc, but personally I don't see how export does encapsulate that any better than expose.

My opinion is not that it encapsulates it significantly better than your proposal per se, just that your proposed term doesn't make it better in principle. IMO, of course. The old keyword still has the benefit of familiarity for many existing Godot users, even if it comes at a price of confusion for newcomers. We do need to improve the docs, though, that is certain.

I'd like this to not become an argument about whether export or expose is better. We should not trivialize the choice here, we can still look for a better term that does actually reflect the functionality of the keyword. Especially since the proposal comes from the place of not realizing that there exists any additional functionality. I think this a great argument in itself to keep looking.

[golddotasksquestions]

While I think what @pycbouh says is very valid, we should always look for the term which explains and infers as much of the functionality of a keyword of property or method or class as possible. However in some cases like this one where there are some lesser known expert uses, it might make sense to choose a term which focuses on the primary wider know use in order to arrive to a solution rather than keeping the old even worse naming.

Which is why I would be in favor of expose over export or serialize, but maybe there are more suggestions?

[Mickeon]

I would outright exclude serialise. It sounds like an annotation that would save the property on disk, but not necessarily expose it in the editor.

[h0lley]

if I try to put myself in the shoes of someone who just booted up Godot for the first time, then I am fairly certain I'd never expect serialize to be the name of the feature that makes properties appear within the inspector, and upon learning about it I would raise at least one brow as far as humanly possible. expose on the other hand seems very intuitive to me; it's exactly what I want to happen, and it's an expressive, concise word on the level of export on top of that. not to mention, I think many users don't even understand serialize as "making an object storable", but associate it purely with the sequential publication of works such as books or magazines...

the line "exposed variables are stored by default" in the opening paragraph of the corresponding documentation article would then take care of pointing out more advanced use-cases.

sure, we shouldn't be prematurely restrictive in the spectrum of choices - someone may have a better idea - but frankly I doubt that there's a single concise word in existence that encompasses all applications of this feature. @edit, @store, @inspect ... it's like either or, never both.

[Mickeon]

Of note that should the renaming go through with @expose, the change would really be minimal for the user writing a script, especially when code autocompletition is taken into account. It would also really allow further describing the concept without getting it mixed up with the other "export" the Engine documentation refers to, which is completely unrelated.

[Zireael07]

Voting for "expose" - the change from export to expose is minimal and also it doesn't run the risk of people confusing exported properties for exporting projects when searching the docs.

[sairam4123]

I'm voting for "expose" too. It would be a little bit difficult to change my muscle memory to type in expose instead of export 😄

[I-Have-No-Idea-What-IAmDoing]

+1 on the expose, it seems to make a lot more sense than export to me though I never had any problem with export

[fire-forge]

When I first started using Godot I remember having trouble finding docs pages relating to export variables, because they were buried in pages about project exporting. I'd support changing export to expose, since it would make searching the docs easier.

[dalexeev]

The word "export" reflects that the values ​​of the variables are taken from the scene/resource file. If we are going to rename this annotation, then I would prefer @store or something similar, but definitely not @expose. I think @expose is no more understandable to beginners than @export, and even more confusing.

The "easier to find online" argument doesn't seem like a compelling reason for this renaming. No one will search for "godot expose variables". Beginners may search for something like "godot how to add variables in editor". From this point of view, @editor is also a good option, although it distorts what is happening.

Please note that the new option must be clearly better than @export, otherwise it is not worth changing to another one that is the same but less familiar.

[Zireael07]

@store has the problem that deserialize has, it sounds like it'll be stored to some file...

[YuriSizov]

@store has the problem that deserialize has, it sounds like it'll be stored to some file...

Which is true?..

[Mickeon]

@store has the problem that deserialize has, it sounds like it'll be stored to some file...

Which is technically what @export also does, as well!

It'd be nice, though, to find a word that fits with every variation of the export annotation:

• @export_range;
• @export_multiline;
• @export_flags...

For this, I would still favour @expose as I personally really find it to be the closest verb describing what the annotation actually does:

@expose_range(10, 50) var jump_height := 0.0
@expose_flags("Fire", "Water", "Earth", "Wind") var elements := 0
@expose(Array, PackedScenes) var stages := [] 
@expose_file var file
@expose_dir var directory

For example, the annotation @store_range or @store_file may sound too misleading to whoever is trying to understand the code. The same goes for @serialize_range.

[Xrayez]

Be aware that all of this is backed up by property usage flags in C++:

There's another value PROPERTY_USAGE_DEFAULT, which combines both, and PROPERTY_USAGE_NOEDITOR, which excludes PROPERTY_USAGE_EDITOR and remains PROPERTY_USAGE_STORAGE.

Due to this, the "storage" and "editor" are treated separately in core, it's possible to expose properties to editor but not to store them, for instance. I've done this myself in the past by overriding _get_property_list().

Because of this, I see that export keyword combines both storage and editor flags. Regardless of whether we end up renaming export to expose, we still have different concepts to distinguish:

• export or expose: expose to the editor, store to scene/resource.
• store: store to scene/resource, do not expose to the editor.
• editor: expose to the editor, do not store in the scene/resource.

So I think that we cannot just rename export to store. I honestly think that store and editor should be introduced as new annotations to GDScript (I don't imply removing export).

[YuriSizov]

I honestly think that store and editor should be introduced as new annotations to GDScript (I don't imply removing export).

While it is one of the suggested changes in OP, this creates a lot of additional complexity to a feature that should be simple to use. For example, if we both keep the unified annotation and add individual annotations for each store and editor, this means that every export hint needs to be defined twice (export/expose + editor), or even thrice (if store also validates it).

This leads me to suggest we split actual "exposure" and "storage" declaration from the hinting. It would be more verbose, but at least we can then keep export/expose and add store, editor without making them individually more complex. This would also be quite similar to our shader language hints:

@export @hint_range(10, 50) var jump_height := 0.0
@expose @hint_flags("Fire", "Water", "Earth", "Wind") var elements := 0
@store @hint(Array, PackedScenes) var stages := [] 
@editor @hint_file var file
@expose @hint_dir var directory

[Mickeon]

That makes me think, couldn't @hint by itself be a good word for the rename? It's short, concise, doesn't step on another concept's toes and matches the shader language to an extent. The Global Constants already refer to them as PROPERTY_HINT_*, and Engine.editor_hint is a fairly useful property when writing code interfacing within the editor itself.

[YuriSizov]

That makes me think, couldn't @hint by itself be a good word for the rename? The Global Constants already refer to them as PROPERTY_HINT_*

Well, yes, the hint part is the same, but hints by themselves don't imply any behavior. Usage does (e.g. STORAGE or EDITOR, or others). So using just hint would conflict with the rest of the system and create wrong assumptions when you start to learn the engine more. If we do this, the reasonable question from the user would be "Why does setting PROPERTY_HINT_* not expose my property, when the annotation of the same name does expose it?"

Since these are not internal systems, hidden from user, but instead just the next level of the same feature, we must ensure logical and syntactic parity.

matches the shader language to an extent

You still need to mark a shader property as a uniform to expose it as a parameter.

[SilencedPerson]

I really do not see point of having the name reflect that it is being stored. It is not the main use case, it's main use it's to expose stuff to the inspector. Anything else is additional functionality and should be easily accessible from the documentation.

1) export is confusing, gets buried under actual exporting stuff in the docs. 2) serialize is pretty hard to write and does not convey that it exposes stuff to the inspector any better than export 3) hint is something i wish would be gone from the shaders too as it makes it feel more like tooltip 4) store is something that makes me think of steam or itch.io than storage but it's still better than every other option so far. 5) expose in my opinion vastly superior to all the the other choices.

I will throw in few other possible words (which i feel are still inferior to expose): 1) reveal 2) disclose 3) exhibit 4) externalize 5) manifest 6) mirror i like this one the least but it is used in web terminology to point to exact copy stored elsewhere

[YuriSizov]

I really do not see point of having the name reflect that it is being stored. It is not the main use case, it's main use it's to expose stuff to the inspector.

That's very subjective and doesn't actually reflect the reality. As we can see from OP, some users don't fully realize what the keyword/annotation does. That is the problem. Finding information in the docs is not really a problem. It's one page and you just look for "godot export hints", if you don't have it bookmarked.

It's confusing to me that a lot of arguments in favor of expose don't look to rectify the bad name that poorly explains the keyword's functionality, but instead want to reinforce a term that hides part of that functionality. You aren't doing yourself, or new users, a favor with this. We should seek to help people understand Godot's systems, not change terms on superficial level just because you happen to not care or not know what the keyword actually does.

Like I've said in my original comment here, the fact that so many of you don't even realize that the keyword does more than exposing the property to the editor, and that it is, for example, an essential tool for creating custom resources (the preferred way in Godot to deal with data), is an amazing example that we need a better convention than what we have. Not just a flavor change, an actual better convention.

If we keep ignoring that users don't fully appreciate the feature that the export/whatever represents, then there is no point renaming it.

[SilencedPerson]

The "easier to find online" argument doesn't seem like a compelling reason for this renaming. No one will search for "godot expose variables". Beginners may search for something like "godot how to add variables in editor".

Not how it works these days. Beginner will watch a tutorial on Youtube where the tutor explains to them that the export keyword exposes the variable to the inspector. Subsequently, the beginner will try it in the game engine. Then sometime later they will go directly to the documentation after being sent there by community many times before after asking in other places like reddit/discord/youtube comments on different issues when they eventually begin to wonder what else they can do with the keyword (what i encountered the most is how to export multiline string) and type in "export" and hit the wall. Only so very few people without prior experience in other engines would ever think about adding variable to inspector, it's not something obvious.

People are focusing on the documentation part because this is how it happens. I have experienced it, I have seen it other people go through and I made other people experience it by sending them to documentation.

If they had easier access to the documentation, they would immediately learn it immediately.

[dalexeev]

Clarification for those who did not know or did not pay attention to this fact: you can create a script that extends Node/Resource, and different instances of your class can have different values of export variables.

You don't just make it possible to edit the value of a variable in the editor for the script as a whole, you make it possible to set different values for different instances of the class. This is an essential detail, which is highly desirable to be reflected in the name. That is why @expose is worse than @export.

[golddotasksquestions]

@dalexeev I'm 100% sure everyone here knows this. It's really hard to miss once you start instancing a scene with export variables.

export still sucks infinitely more because it's other much more prominent meanings in game dev and editors in general and the fact that the name makes it impossible to even find information about this and more behaviour/functionality the keyword has. Which is also why store, serialize are equally really bad choices.

expose or reveal are used nowhere I can think of, and therefore allow all these additional functionality and behaviour you and @pycbouh are talking about to be found much easier.

In fact if you Google search for "Godot expose" you will find how many people already use expose interchangeably for the export keyword.

[aaronfranke]

@dalexeev: No one will search for "godot expose variables".

Yes they would...?

@dalexeev: You don't just make it possible to edit the value of a variable in the editor for the script as a whole, you make it possible to set different values for different instances of the class. This is an essential detail, which is highly desirable to be reflected in the name.

That's... completely expected regardless of the keyword. It's basic object oriented programming that instances of a class can have different values, nobody would expect that the inspector treats these variables as static or anything. If someone does not understand object oriented programming, @export will not help them understand this behavior one bit over @expose.

Again, though, if we can say "exported variables do [thing]", why can't we say "exposed variables do [thing]"?

[dalexeev]

I'm 100% sure everyone here knows this. It's really hard to miss once you start instancing a scene with export variables.

1. I don't think 100% of all users know this. 2. I'm worried that with the renaming we will lose some of this meaning and this problem will become bigger.

That's... completely expected regardless of the keyword. It's basic object oriented programming that instances of a class can have different values, nobody would expect that the inspector treats these variables as static or anything.

Yes, but we are talking about initial values, and they are the same for all instances, it may not be obvious (I know that exported values are applied after _init, but the essence is the same). I remember someone suggested adding the ability to export constants - this also shows that not everyone fully understands how exports work.

I don't think "export" is the ideal name, but I'm still not sure if the suggested alternatives are better enough than the existing name to justify this renaming. This is one of the two main reasons why I am skeptical about this proposal.

I expressed my concerns. The decision must be made by the maintainers. At this point, the discussion has become somewhat tense, so I'd better keep quiet.

[aaronfranke]

The rename itself is not a big obstacle considering that users will already have to rename to change export to @export.

[Xrayez]

I think it's not enough to just rename the annotation, to be honest.

If there's some resistance to renaming, perhaps #2979 could also be incorporated with @expose somehow... A property which is exposed is likely meant to be used outside of the scene/script as well. This is not to say that we should treat private/public access modifiers as something mandatory, but the way I see it, GDScript could potentially warn you about using properties on an instance which does not @expose them (given that the warning system is optional and can be disabled, this is not intrusive at all).

This is just an idea of course, but I think that this kind of feature would certainly make it intuitive and more complete. Of course, that's more work to do, but you'll get a quality product in the long run. The solution could be largely different to match the expectation of what @expose would mean in the new context.

Those who are against the renaming appear to be seasoned users to me. I'm also not sure about this, but that might be only because I got used to status quo. 😛

[YuriSizov]

The rename itself is not a big obstacle considering that users will already have to rename to change export to @export.

Yes, users will have to do changes to their scripts anyway. Then why not rename it proper? Changing a core term comes at a cost of years of accumulated knowledge and help resources. We can pay that price, but wouldn't it be better to make it actually worth it big time? We won't have a chance to do that again until Godot 5.

Seeing that the only vocal opposition so far is me and @dalexeev I think I can say for all of us that we are not against fixing the problem, we just want to fix it all. I really don't understand why there is so much reluctance to investigate other options to help solve a big misconception. No matter how many times it is stressed that serialization and editor exposure are two equal parts of one functionality, some still call the serialization part "additional functionality and behaviour" in this very thread. It's not, it's the core of it. One of two parts. And we need to make sure people stop missing it. So we want a better option. Don't you?

[h0lley]

is an amazing example that we need a better convention than what we have. Not just a flavor change, an actual better convention.

such as? :)

I really don't understand why there is so much reluctance to investigate other options to help solve a big misconception.

I think that's just due to that people can't really get behind something that's not concrete.

I mean there's no comment in here that goes actively against an alternative to a simple renaming, i.e. a new convention, right?

an essential tool for creating custom resources (the preferred way in Godot to deal with data)

I've been using export in conjunction with custom Resource classes extensively throughout my current project. so have I already been using this feature in the way you say is not reflected by "expose"? because exposing the custom resource properties to the inspector (and therefore storing them with the corresponding scene file when changed from the default) is still the main point in my mind.

you make it sound like there is a situation where you want to export your resource and the fact that it then appears in the inspector is just dead weight to your use-case. is that right?

I know there's resources like TileSet which you plug into a TileMap, and that does not have any exported properties of its own - but this is an exception because it got its own editor interface. or there's this awkward resource called ButtonGroup which doesn't hold any data of its own but is used to link buttons that reference it - but that, too, seems like an outlier.

I can't think of a common use-case for exporting a custom resource that doesn't export any properties of its own for editing in the inspector, so I would like to understand.

[YuriSizov]

you make it sound like there is a situation where you want to export your resource and the fact that it then appears in the inspector is just dead weight to your use-case. is that right?

Yes, that is pretty normal for an average project. You would likely have your own data editor/tools for your custom resources (made with an editor plugin, for example), or would use some resources programmatically.

I can't think of a common use-case for exporting a custom resource

This has nothing to do with exporting custom resources. Resources are used without exporting them in scenes all the time. But a custom resource without any exported fields is not going to save anything. People run into this all the time, not realizing they need to mark properties for export for them to save. (Partly because they think it's only for inspector).

such as? :)

I suggested some options, but I don't think that I am solely responsible in finding the answer, am I?

[h0lley]

Yes, that is pretty normal for an average project. You would likely have your own data editor/tools for your custom resources (made with an editor plugin, for example), or would use some resources programmatically.

I feel like adding your own UI to the editor for your custom resources is a rather advanced use-case and users on that level are extremely unlikely to get hung up on basic keywords. but please do not take this as me saying there's no merit in looking for better solutions.

This has nothing to do with exporting custom resources. Resources are used without exporting them in scenes all the time. But a custom resource without any exported fields is not going to save anything. People run into this all the time, not realizing they need to mark properties for export for them to save. (Partly because they think it's only for inspector).

unfortunately I keep struggling here. in what scenario would someone expect or need a not exported property of resource to be serialized & stored? anything that isn't prefixed with export is given a default value and meant for run-time use only. how could someone expect that a variable that isn't overwritten via export to have any other initial value than the one it is declared with in the script?

I suggested some options,

the thing with splitting into separate annotations? yea I recognize that, which is why I also mentioned it in the opening post, but it needs be fleshed out. sorry if I missed anything else.

but I don't think that I am solely responsible in finding the answer, am I?

sorry, I did not mean to imply that at all.

[YuriSizov]

I feel like adding your own UI to the editor for your custom resources is a rather advanced use-case and users on that level are extremely unlikely to get hung up on basic keywords.

Sure, but Godot is not a toy engine either. It tries to be user-friendly, but it doesn't try to be overly simplistic for the sake of it. This is to say that "advanced users will figure it out anyway" is not a good argument in any proposal. I mean sure, I for one don't care that it's called export anymore, just some Godot-specific term, it can mean whatever, I've learnt it, I use it, I don't think about it. But it's better to teach new users proper lingo than to hope that more experienced developers would just roll with it.

We should strive to be correct, regardless of skill level.

unfortunately I keep struggling here. in what scenario would someone expect or need a not exported property of resource to be serialized & stored? anything that isn't prefixed with export is given a default value and meant for run-time use only. how could someone expect that a variable that isn't overwritten via export to have any other initial value than the one it is declared with in the script?

I can't know for sure how people get confused, I just have experience that they do get confused sometimes. They probably expect that it's enough that the member is public for it to be stored with a custom resource. That is a somewhat reasonable guess if you don't know about exporting properties. And it's not like you would look up "godot export" to figure this out. So yeah, it's not the best term, we all agree on that.

This was just a tangential example, however. When I was saying "Resources are used without exporting them in scenes all the time." I meant that a lot of time you create resources not to be edited in the inspector, not to be stored as a part of the scene. And so that fact does become a dead weight. There are other considerations too. For example, you may also want to compute and store some properties, but don't make them easily editable by your artist, for example, so they don't mess it up by accident. Godot has a powerful property system that allows all that, with the export keyword being just the tip of an iceberg, that hides a lot of complexity (and yet, people ask for more anyway, like annotations for grouping, or contextual properties — all possible, just hidden).

I think we can make use of this situation and clarify what you can do with the properties, and possibly make it doable more easily. I would find it very annoying if we go through the trouble of modifying this core syntax for a small superficial change without actually making the feature richer and giving users more control that they often ask for.

the thing with splitting into separate annotations? yea I recognize that, which is why I also mentioned it in the opening post, but it needs be fleshed out. sorry if I missed anything else.

In this particular thread I suggested a slightly different thing compared to the one you used in OP. I proposed we split the hint part and the export/expose part. Then we can indeed use different keywords for storage/editor individually, and keep some keyword for the unified storage + editor usage. Xrayez suggested that part as well, so there is some support to the idea, I think.

I think we should keep close to the terminology of the engine, because it would make learning about the extension of this feature easier. E.g. if you learn about some @storage annotation you would be able to map that knowledge when you start learning about _get_property_list and various amazing things you can do with that, but can't do with annotations (because there you'd use PROPERTY_USAGE_STORAGE instead). So we can easily borrow @storage (since @store is apparently reserved by Steam in collective mind) and @editor from PROPERTY_USAGE_* flags.

One problem is that the unified usage flag is called PROPERTY_USAGE_DEFAULT, and @default is hardly a good term. If we can find a good term here, we can change PROPERTY_USAGE_DEFAULT to use that term as well, allowing, once again, to learn about the advanced usages of the feature easier.

---

Overall, I find that the main conflict here is that the discussion started kind of tunnel-vision-y with people saying how great expose is to reflect what they know about the feature, whereas what I want from this change is that we expand people's knowledge about the feature where it's lacking. Because frankly properties are freaking cool and powerful and worth to learn about.

[Scony]

What about introducing annotation aliases in project settings? OP would then create an alias:

expose=export

And use @export as well as @expose interchangeably.

The @export would remain default and everyone would be happy.

[Zireael07]

everyone would be happy.

Not everyone - the people saying there are more complex things at work worth exposing to users explicitly still wouldn't be happy (unless we could do "export = storage+editor"?)

[aaronfranke]

@Scony Making the GDScript language change depending on project settings is a bad idea.

[TurtleKwitty]

Definitely very much like the idea of actually splitting the annotations so its accessible, but personally don't think we need an annotation for default even if internally it does use default to present the use case of both. @editor just to expose to the editor, and @editor_*() for all the magical madness possible, that way it always refers back to the fact that this annotation is for the editor and only the editor If you want both then put both, it keeps things very simple, no need to add additional hint annotations on top of it all just @storage @editor to indicate that you want this property to interact with both the editor and the storage facilities.

[Mickeon]

I think that for the beginning user it is fairly expected to see a stored property in the Inspector. And, being such a common thing, removing @export outright and splitting the functionalities up would feel redudant.

[pchasco]

The fact that exported variables are shown as "properties" in the editor creates an obvious choice: @property

[h0lley]

wouldn't that imply to new users that only variables exposed to the inspector are referred to as properties?

also I doubt it's much better of a keyword than "export" to search the docs by.

in my mind there's still nothing really competing with @expose.

[pchasco]

wouldn't that imply to new users that only variables exposed to the inspector are referred to as properties?

I don't think so. I would think that the "filter properties" label under the search box would be giving new users that impression.

also I doubt it's much better of a keyword than "export" to search the docs by.

I don't know if the goal of any keyword is to necessarily make it 100% unambiguous to search the docs for. To me, the keyword should clearly communicate its meaning. It should be easy for new users to make the connection that when they see @property before a script variable that it would be visible in the properties window.

In the end, I'm not sure that the disruption to existing GDScript developers would be worth the marginal benefit to changing this keyword.

[Mickeon]

in the editor creates an obvious choice: @property

Let's see then:

@property_range(10, 50) var jump_height := 0.0
@property_flags("Fire", "Water", "Earth", "Wind") var elements := 0
@property(Array, PackedScenes) var stages := [] 
@property_file var file
@property_dir var directory

It doesn't sound too bad, but it's not exactly correct, per se. Any property defined in the script is... a property! Regardless of whether or not it's exposed to the editor.

[TurtleKwitty]

I still quite like the idea of splitting the options. editor would very much simplify making the connection that these are exposed to the editor in clear language for a new user, and storage for the same reasons for being exposed to the storage mechanisms

So, @Mickeon exmaples would become

@editor_range(10, 50) var jump_height := 0.0
@editor_flags("Fire", "Water", "Earth", "Wind") var elements := 0
@editor(Array, PackedScenes) var stages := [] 
@editor_file var file
@editor_dir var directory

with possibilities for exposing things to either without forcing the other

@storage @editor var characterName := "Bob"
@storage @editor_flags("Knight", "Wizard") var characterClass
@storage var exp := 0
@editor_range(1.1, 2.5) expScaling

Showing exp in editor wouldn't be very useful, but neither do you need to save the expScaling factor per character its just a constant of the scene form the editor as examples

[Mickeon]

Problem with that is, when available in the editor, the storing behaviour is to be expected. If anything, not storing in that case may be the exception.

Suppose you're a beginner user that makes use of @editor. The property will display in the editor, so the user will modify the value, save, open the Scene again and discover that nothing has been saved. So they wonder what happened and... Writing @storage for each one of them is a fair nuisance for such a common necessity, and it would, for example, be attached to almost every property of a custom Resource. If only there was a single annotation that avoided repetition, which there is, and it's as of currently @export,

[Mickeon]

I want to try to find a name in the attempt to have a new name be more exhaustive and self-explanatory. It's true, @export doesn't just do one thing. It displays a property in the editor and serialises it. It's very important and fairly powerful.

I looked around, these are closest words I can personally find to define it. @record, or @register, too. According to some dictionaries:

"set down in writing or some other permanent form for later reference." "to keep information for the future, by writing it down or storing it on a computer" "to show a measurement, an amount, etc."

It seems like it is not just about storing, it's also about the need for it to be looked that by an user agent.

Putting it up to the now typical example, and more:

@record_range(10, 50, 0.2) var jump_height := 0.0
@record_flags("Fire", "Water", "Earth", "Wind") var elements := 0
@record(Array, PackedScenes) var stages := [] 
@record_file var file
@record_dir var directory
@record_enum("Rebecca", "Mary", "Leah") var character_name: String
@record_multiline var text
@record_exp_easing var transition_speed
@record_color_no_alpha var col: Color
@record_node_path(Button, TouchScreenButton) var some_button

Despite me personally finding it more accurate, I'm terribly afraid this is not a term most people would be willing to adapt to, unless it got overwhelming support. Its meaning closely intertwines with a theoretical @store, as well.

[Mickeon]

Splitting my line of thought in half, any @record_* variation may come with the same, long aforementioned misleading issue of any variation of @store_* (how is the enum of @record_enum being recorded, too?), which, personally, I believe @export is also guilty of. This is currently mitigated by proper documentation and proficiency for the language, so I'm not confident on how much of an issue this actually is.

[filipworksdev]

I like @export is just export is also used when exporting the project. At first when I started using Godot I thought is something to do with exporting the project.

I actually vote for using @property which is actually what the controls in the Inspector are called in the source code.

If you sit down and think about it what you are actually doing is turning a variable into an Inspector property.

[aaronfranke]

@filipworksdev The problem with @property is that properties are already a well-defined thing in programming languages like GDScript and C#, they just aren't exposed to the inspector by default unless we have this attribute.

Also, this was already proposed: https://github.com/godotengine/godot-proposals/issues/3906#issuecomment-1050981600

[filipworksdev]

@aaronfranke In that case I cast my vote for my second choice @expose which makes it different than export but with a better meaning since export means to transport, spread while expose to reveal or show or make available. Properties are exposed to the inspector rather than exported. Export is more appropriate when saving something to file. Expose when revealing something to the user.

The other choices serialize, store, record, register seems very odd to me.

Searching through this entire thread these are the most common suggestions with just the most common words in the brackets:

@export - 27 (export 124)
@expose - 22 (expose 78)
@store - 11 (store 41)
@property - 10  (property 44)
@record - 15 times but only 2 comments  (record 16)
@register - 2
@serialise - 1 (incorrect form)
@serialize - 1
@edit/editor - 1
@inspect - 1

So expose does seem like the second most supported after export. In fact reading some of the comments they refering to exported property as being exposed to the inspector. Seems like expose comes naturally to refer to properties showing up in the inspector.

[YuriSizov]

@filipworksdev It has been stated already that exposing the property to the inspector is only one of two things it does. The other thing it does is saving the property to a file. So by your own logic we'd be replacing a word that means half of its actual functionality with a word that means the other half. But neither is expressive enough to actually convey the functionality as a whole.

[h0lley]

I don't quite follow how export is more descriptive in the serialization aspect of the feature than expose.

but even if we grant that, expose still does clash less with other things commonly used in game development and therefore makes for better searchability, so in my mind it has at least one up on export.

the counter argument that remains is that export is the established term for existing users, and it may not be worth the trouble of amending the docs plus having people have to get used to typing a different keyword. personally I feel like that's moot though, looking at the amount of breaking changes Godot 4 is already sure to come with.

[YuriSizov]

No, my counter argument was that if we go through this trouble of changing one of the core terms, we must do it for more benefit than just having a maybe slightly better term.