Expose _get_argument_options virtual function in GDScript to allow for custom dynamic function argument autocomplete

[pkmollman]

From the GDScript editor, autocomplete provides a list of existing animation names on an AnimationPlayer when calling AnimationPlayer.play, and a list of property names on Nodes when calling Node.get.
I think it could be a very useful feature to dynamically provide autocomplete suggestions via GDScript (and likely GDExtension).

Digging around in the source I'm seeing that there is a function to shim in this autocomplete logic.
Below is an example from AnimationPlayer.

void AnimationPlayer::get_argument_options(const StringName &p_function, int p_idx, List<String> *r_options) const {
	const String pf = p_function;
	if (p_idx == 0 && (pf == "play" || pf == "play_backwards" || pf == "has_animation" || pf == "queue")) {
		List<StringName> al;
		get_animation_list(&al);
		for (const StringName &name : al) {
			r_options->push_back(String(name).quote());
		}
	}
	AnimationMixer::get_argument_options(p_function, p_idx, r_options);
}

This feature is similar to _get_property_list, allowing us to provide context for the editor.
The way these existing functions work is already so simple, flexible, and consistent, it would be great to extend it into GDScript and GDExtension.

I'm still learning this code base, and C++, so I'm not sure how I'd go about implementing it yet.
Currently trying to learn from examples of the existing virtual/overridable functions.
If this idea passes, I'd sure like to take a stab at it.

Any thoughts, suggestion, questions, or other discussion around this is appreciated. Thanks.

[HolonProduction]

Implementation wise it is important to ensure that it does not break the native argument options, so the best place would probably be in Node::get_argumnet_options (which would mean native argument options take priority).

The problem I see with this, is that how the editor uses this isn't really fool proof. It only handles strings well, we use it for enum options as well but the UX is bad (only being displayed before the user manually types something). Exposing this now will make it much harder to improve UX on this in the future, since backwards compatibility would become an issue.

[pkmollman]

Thanks for taking a look at this!

I do think it's important to implement it in such a way to avoid breaking the intended priority.
Also accounting for how extended GDSscript classes would handle inheriting the proposed "_get_argument_options" from parent extended classes. For example would the convention be to call super() at the end of logic, similar to the current get_argument_options convention?

I'm not sure I understand how get_argument_options "only handles strings well", do you mean how the list is filtered based on what you have typed?
For context, I can start to call play() on an AnimationPlayer, and it will provide all animation names.

Then when I start typing the argument myself, the suggested options are filtered to match, and pretty loosely too.

Is the above filtering what you mean by "how the editor uses this isn't really fool proof. It only handles strings well"?

What do you mean by "only being displayed before the user manually types something"?
If I start manually typing an argument the editor filters the suggestion list, like the above example.

It seems like get_argument_options and the way the editor presents the results are pretty decoupled.
If there are core issues with how the currently implemented get_argument_options works it should definitely be tackled before implementing a feature like this. Do we see issues with that current system?

Thanks again for entertaining the idea.

[HolonProduction]

You are showing the best case which works very well, when the options are strings. But take the following script:

As soon as you type the argument options won't be suggested anymore.

This case could be considered a "core" issue, but the current implementation is pretty much fine for how we use it internally. It just doesn't feel ready to let users throw arbitrary options at it and expect it to deliver a good UX in any case.

[dalexeev]

• See also Add Input action autocompletion for user define function #12009.

I think before exposing we could extend the method's functionality to match CodeEdit.add_code_completion_option():

add_code_completion_option(type: CodeCompletionKind, display_text: String, insert_text: String, text_color: Color = Color(1, 1, 1, 1), icon: Resource = null, value: Variant = null, location: int = 1024) -> void

Before:

virtual void get_argument_options(const StringName &p_function, int p_idx, List<String> *r_options) const;

After:

virtual void get_argument_options(const StringName &p_method, int p_arg_idx, List<ScriptLanguage::CodeCompletionOption> *r_options) const;

_get_argument_options(method: StringName, arg_idx: int) -> Array[Dictionary]

[Mickeon]

I've thought about it for quite a while and I always felt like the internal _get_argument_options is too limited as is. Sure, it's functional, but it lacks too much context. Most importantly, the previously written arguments. Inevitably users are going to suggest these if it's exposed, so it should be ready for it beforehand.
If it were exposed using a struct it would also be more convenient, but that's taking some time...

[HolonProduction]

Argument dependent stuff (e.g. tween autocompletion) is a hardcoded route at the moment. And making it modular and exposing it, would probably require exposing parts of the AST, not sure if we want that.

[Mickeon]

Indeed. There's many code paths that are actually hardcoded for the built-in editor. But there is a certain appeal in making the entire argument-fetching not hardcoded, and by extension exposed to the user, eventually. Not in the current state, though.

[dalexeev]

Please note that even if it is not perfect (strings only, not taking previous arguments into account), this feature can be a very useful QoL change.

Users would be able to easily implement smart completion for file paths, node paths, class properties, character stats, item names, and other component identifiers. Yes, in some cases you can use enums and protect yourself from typos and other errors thanks to static typing, but the string-based approach also has its place and is hard to avoid if some entities are added in modules/mods.

Also, strings are in my opinion the most common use case for this feature. It is unlikely that you will often want to implement custom completion for other data types or for complex expressions that would require exposing the AST. This is the job of the built-in contextual completion. While neither the GDScript type system nor the editor's completion can know much about the structure of the project, what kind of strings there are.

After all, even if we find a better solution in the future, it won't stop us from deprecating _get_argument_options() and exposing another virtual function.

[HolonProduction]

Yeah we can expose it in the current state, given that:

• it is marked as experimental
• we clearly document that it might not work as expected for other things than strings
• if Instantiate type before getting argument options for autocompletion godot#85364 gets merged, I don't think we should support script types with it, to prevent obscure side effects