GDScript: Implement @if_features annotation

Author: RandomShaper

modules/gdscript/doc_classes/@GDScript.xml

@@ -730,6 +730,17 @@
 				[b]Note:[/b] Unlike most other annotations, the argument of the [annotation @icon] annotation must be a string literal (constant expressions are not supported).
 			</description>
 		</annotation>
+		<annotation name="@if_features" qualifiers="vararg">
+			<return type="void" />
+			<param index="0" name="feature" type="String" default="null" />
+			<description>
+				Marks the following function to be taken into account only if all the features passed as arguments are declared by the platform or export preset.
+				This is meant to be applied to a set of functions with the same name so at runtime you have a single implementation of some feature according to the features supported. All the functions in such a set must have the exact same signature.
+				If the annotation has no features specified, it's considered a default one as so it's only used if none of the other functions with the same name are proper fits.
+				At runtime from an editor build, the features are checked at the moment the script is parsed, against what the OS advertises.
+				At export time, the features are checked against the target platform's OS as well as the list of custom features specified in an export preset. Moreover, [b]the functions not matching the features, are removed from the source code[/b] so the exported project won't contain them at all.
+			</description>
+		</annotation>
 		<annotation name="@onready">
 			<return type="void" />
 			<description>

modules/gdscript/gdscript_cache.cpp

@@ -46,6 +46,10 @@ String GDScriptParserRef::get_path() const {
 	return path;
 }
 
+void GDScriptParserRef::set_path(const String &p_path) {
+	path = p_path;
+}
+
 uint32_t GDScriptParserRef::get_source_hash() const {
 	return source_hash;
 }
@@ -134,9 +138,15 @@ void GDScriptParserRef::clear() {
 }
 
 GDScriptParserRef::~GDScriptParserRef() {
+#ifdef TOOLS_ENABLED
+	bool remove_from_map = !parser || !parser->is_for_export();
+#else
+	bool remove_from_map = true;
+#endif
+
 	clear();
 
-	if (!abandoned) {
+	if (remove_from_map && !abandoned) {
 		MutexLock lock(GDScriptCache::singleton->mutex);
 		GDScriptCache::singleton->parser_map.erase(path);
 	}

modules/gdscript/gdscript_cache.h

@@ -67,6 +67,7 @@ class GDScriptParserRef : public RefCounted {
 public:
 	Status get_status() const;
 	String get_path() const;
+	void set_path(const String &p_path);
 	uint32_t get_source_hash() const;
 	GDScriptParser *get_parser();
 	GDScriptAnalyzer *get_analyzer();

modules/gdscript/gdscript_compiler.cpp

@@ -2947,6 +2947,14 @@ Error GDScriptCompiler::_compile_class(GDScript *p_script, const GDScriptParser:
 		const GDScriptParser::ClassNode::Member &member = p_class->members[i];
 		if (member.type == member.FUNCTION) {
 			const GDScriptParser::FunctionNode *function = member.function;
+#ifdef TOOLS_ENABLED
+			if (!Engine::get_singleton()->is_editor_hint()) {
+				// Runtime in editor build. Ignore @if_features-decorated function if unfitting.
+				if (function->if_features.potential_candidate_index != -1) {
+					continue;
+				}
+			}
+#endif
 			Error err = OK;
 			_parse_function(err, p_script, p_class, function);
 			if (err) {

modules/gdscript/gdscript_editor.cpp

@@ -36,6 +36,7 @@
 #include "gdscript_utility_functions.h"
 
 #ifdef TOOLS_ENABLED
+#include "editor/export/editor_export.h"
 #include "editor/gdscript_docgen.h"
 #include "editor/script_templates/templates.gen.h"
 #endif
@@ -982,6 +983,26 @@ static void _find_annotation_arguments(const GDScriptParser::AnnotationNode *p_a
 				r_result.insert(option.display, option);
 			}
 		}
+	} else if (p_annotation->name == SNAME("@if_features")) {
+#ifdef TOOLS_ENABLED
+		HashSet<String> features;
+		for (int i = 0; i < EditorExport::get_singleton()->get_export_preset_count(); i++) {
+			const Ref<EditorExportPreset> &preset = EditorExport::get_singleton()->get_export_preset(i);
+			for (const String &feature : preset->get_custom_features().split(",", false)) {
+				features.insert(feature.strip_edges());
+			}
+			List<String> platform_features;
+			preset->get_platform()->get_platform_features(&platform_features);
+			for (const String &feature : platform_features) {
+				features.insert(feature.strip_edges());
+			}
+		}
+		for (const String &feature : features) {
+			ScriptLanguage::CodeCompletionOption option(feature, ScriptLanguage::CODE_COMPLETION_KIND_PLAIN_TEXT);
+			option.insert_text = option.display.quote(p_quote_style);
+			r_result.insert(option.display, option);
+		}
+#endif
 	}
 }
 

modules/gdscript/gdscript_parser.cpp

@@ -132,6 +132,8 @@ GDScriptParser::GDScriptParser() {
 		register_annotation(MethodInfo("@warning_ignore_restore", PropertyInfo(Variant::STRING, "warning")), AnnotationInfo::STANDALONE, &GDScriptParser::warning_ignore_region_annotations, varray(), true);
 		// Networking.
 		register_annotation(MethodInfo("@rpc", PropertyInfo(Variant::STRING, "mode"), PropertyInfo(Variant::STRING, "sync"), PropertyInfo(Variant::STRING, "transfer_mode"), PropertyInfo(Variant::INT, "transfer_channel")), AnnotationInfo::FUNCTION, &GDScriptParser::rpc_annotation, varray("authority", "call_remote", "unreliable", 0));
+		// Preprocessing.
+		register_annotation(MethodInfo("@if_features", PropertyInfo(Variant::STRING, "feature")), AnnotationInfo::FUNCTION, &GDScriptParser::if_features_annotation, varray(Variant()), true);
 	}
 
 #ifdef DEBUG_ENABLED
@@ -944,11 +946,22 @@ void GDScriptParser::parse_class_member(T *(GDScriptParser::*p_parse_function)(b
 
 	// Consume annotations.
 	List<AnnotationNode *> annotations;
+#ifdef TOOLS_ENABLED
+	constexpr bool parsing_function = std::is_same_v<T, FunctionNode>;
+	AnnotationNode *if_features = nullptr;
+#endif
 	while (!annotation_stack.is_empty()) {
 		AnnotationNode *last_annotation = annotation_stack.back()->get();
 		if (last_annotation->applies_to(p_target)) {
 			annotations.push_front(last_annotation);
 			annotation_stack.pop_back();
+#ifdef TOOLS_ENABLED
+			if constexpr (parsing_function) {
+				if (last_annotation->name == StringName("@if_features")) {
+					if_features = last_annotation;
+				}
+			}
+#endif
 		} else {
 			push_error(vformat(R"(Annotation "%s" cannot be applied to a %s.)", last_annotation->name, p_member_kind));
 			clear_unused_annotations();
@@ -994,6 +1007,32 @@ void GDScriptParser::parse_class_member(T *(GDScriptParser::*p_parse_function)(b
 	}
 
 	min_member_doc_line = member->end_line + 1; // Prevent multiple members from using the same doc comment.
+
+	if constexpr (parsing_function) {
+		if (if_features) {
+			// Mark this one as a default implementation if the annotation provides no features.
+			member->if_features.is_default_impl = if_features->arguments.is_empty();
+
+			// Let the first default one with of same name fully in.
+			// The others are added so they are parsed, but not indexed so name clash error is avoided.
+			HashMap<StringName, int>::Iterator E = current_class->members_indices.find(member->identifier->name);
+			if (E) {
+				// Member with that name already exists.
+				const ClassNode::Member &existing = current_class->members[E->value];
+				if (existing.type == ClassNode::Member::FUNCTION) { // Otherwise, an error is raised anyway.
+					// HACK: Compare compatibility of functions via TreePrinter.
+					const String &existing_str = TreePrinter().strinfigy_function_declaration(existing.function);
+					const String &incoming_str = TreePrinter().strinfigy_function_declaration(member);
+					if (existing_str != incoming_str) {
+						push_error(vformat(R"(%s "%s" does not match the signature of a previously declared function of the same name.)", p_member_kind.capitalize(), member->identifier->name), member->identifier);
+					} else {
+						current_class->add_if_features_potential_candidate(member);
+					}
+					return;
+				}
+			}
+		}
+	}
 #endif // TOOLS_ENABLED
 
 	if (member->identifier != nullptr) {
@@ -4975,6 +5014,106 @@ bool GDScriptParser::warning_ignore_region_annotations(AnnotationNode *p_annotat
 #endif // DEBUG_ENABLED
 }
 
+bool GDScriptParser::if_features_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class) {
+#if defined(TOOLS_ENABLED)
+	ERR_FAIL_COND_V_MSG(p_target->type != Node::FUNCTION, false, vformat(R"("%s" annotation can only be applied to functions.)", p_annotation->name));
+
+	FunctionNode *function = static_cast<FunctionNode *>(p_target);
+	if (function->if_features.used) {
+		push_error("The @if_features annotation can only be used once per function.");
+		return false;
+	}
+
+	function->if_features.used = true;
+
+	thread_local LocalVector<String> features;
+	features.clear();
+	for (const ExpressionNode *arg : p_annotation->arguments) {
+		DEV_ASSERT(arg->reduced);
+		if (arg->reduced_value.get_type() == Variant::STRING) {
+			features.push_back(arg->reduced_value);
+		} else {
+			push_error("The arguments to @if_features must be strings.");
+			return false;
+		}
+	}
+
+	if (Engine::get_singleton()->is_editor_hint() && !for_export) {
+		// At edit time there's nothing else to process.
+		return true;
+	}
+
+	// The idea is to keep the first one fitting, with only the default possibly overridden by another one coming later.
+
+	FunctionNode *target_function = static_cast<FunctionNode *>(p_target);
+	const StringName &function_name = target_function->identifier->name;
+
+	auto _check_incoming_fits = [&]() -> bool {
+		if (features.is_empty()) {
+			return false; // Defaults are considered non-fitting.
+		}
+		bool fitting = true;
+		for (const String &feature : features) {
+			if (for_export) {
+				// Export time in editor build.
+				if (!export_features.has(feature)) {
+					fitting = false;
+					break;
+				}
+			} else {
+				// Runtime in editor build.
+				if (!OS::get_singleton()->has_feature(feature)) {
+					fitting = false;
+					break;
+				}
+			}
+		}
+		return fitting;
+	};
+
+	if (target_function->if_features.potential_candidate_index == -1) {
+		// Chosen one at parsing time because it was the first one found. Only keep if fitting.
+		if (!_check_incoming_fits()) {
+			HashMap<StringName, int>::Iterator E = p_class->members_indices.find(function_name);
+			int64_t current_match_index = E->value;
+			target_function->if_features.potential_candidate_index = current_match_index;
+			p_class->members_indices.remove(E);
+		}
+	} else {
+		HashMap<StringName, int>::Iterator E = p_class->members_indices.find(function_name);
+		if ((bool)E) {
+			// There's a current one. Override if current is default and incoming fits.
+			bool current_match_is_default = p_class->members[E->value].function->if_features.is_default_impl;
+			if (current_match_is_default && _check_incoming_fits()) {
+				E->value = target_function->if_features.potential_candidate_index;
+				target_function->if_features.potential_candidate_index = -1;
+			}
+		} else {
+			// Incoming fits and there's no current chosen. Pick if it's default or fits.
+			if (target_function->if_features.is_default_impl || _check_incoming_fits()) {
+				p_class->members_indices.insert(function_name, target_function->if_features.potential_candidate_index);
+				target_function->if_features.potential_candidate_index = -1;
+			}
+		}
+	}
+#endif
+
+	return true;
+}
+
+#ifdef TOOLS_ENABLED
+void GDScriptParser::collect_unfitting_functions(ClassNode *p_class, LocalVector<Pair<ClassNode *, FunctionNode *>> &r_functions) {
+	for (const ClassNode::Member &member : p_class->members) {
+		if (member.type == ClassNode::Member::CLASS) {
+			collect_unfitting_functions(member.m_class, r_functions);
+		}
+		if (member.type == ClassNode::Member::FUNCTION && member.function->if_features.potential_candidate_index != -1) {
+			r_functions.push_back(Pair(p_class, member.function));
+		}
+	}
+}
+#endif
+
 bool GDScriptParser::rpc_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class) {
 	ERR_FAIL_COND_V_MSG(p_target->type != Node::FUNCTION, false, vformat(R"("%s" annotation can only be applied to functions.)", p_annotation->name));
 
@@ -5833,9 +5972,11 @@ void GDScriptParser::TreePrinter::print_for(ForNode *p_for) {
 	decrease_indent();
 }
 
-void GDScriptParser::TreePrinter::print_function(FunctionNode *p_function, const String &p_context) {
-	for (const AnnotationNode *E : p_function->annotations) {
-		print_annotation(E);
+void GDScriptParser::TreePrinter::print_function(FunctionNode *p_function, const String &p_context, bool p_signature_only) {
+	if (!p_signature_only) {
+		for (const AnnotationNode *E : p_function->annotations) {
+			print_annotation(E);
+		}
 	}
 	if (p_function->is_static) {
 		push_text("Static ");
@@ -5859,10 +6000,12 @@ void GDScriptParser::TreePrinter::print_function(FunctionNode *p_function, const
 		push_text("-> ");
 		print_type(p_function->return_type);
 	}
-	push_line(" :");
-	increase_indent();
-	print_suite(p_function->body);
-	decrease_indent();
+	if (!p_signature_only) {
+		push_line(" :");
+		increase_indent();
+		print_suite(p_function->body);
+		decrease_indent();
+	}
 }
 
 void GDScriptParser::TreePrinter::print_get_node(GetNodeNode *p_get_node) {
@@ -6283,4 +6426,9 @@ void GDScriptParser::TreePrinter::print_tree(const GDScriptParser &p_parser) {
 	print_line(String(printed));
 }
 
+String GDScriptParser::TreePrinter::strinfigy_function_declaration(FunctionNode *p_function) {
+	print_function(p_function, "Function", true);
+	return String(printed);
+}
+
 #endif // DEBUG_ENABLED

modules/gdscript/gdscript_parser.h

@@ -785,6 +785,13 @@ class GDScriptParser {
 			members_indices[p_member_node->identifier->name] = members.size();
 			members.push_back(Member(p_member_node));
 		}
+#ifdef TOOLS_ENABLED
+		template <typename T>
+		void add_if_features_potential_candidate(T *p_member_node) {
+			p_member_node->if_features.potential_candidate_index = members.size();
+			members.push_back(Member(p_member_node));
+		}
+#endif
 		void add_member(const EnumNode::Value &p_enum_value) {
 			members_indices[p_enum_value.identifier->name] = members.size();
 			members.push_back(Member(p_enum_value));
@@ -862,6 +869,12 @@ class GDScriptParser {
 #ifdef TOOLS_ENABLED
 		MemberDocData doc_data;
 		int min_local_doc_line = 0;
+		struct {
+			bool used = false;
+			bool is_default_impl = false;
+			bool fitting_verified = false;
+			int potential_candidate_index = -1;
+		} if_features;
 #endif // TOOLS_ENABLED
 
 		bool resolved_signature = false;
@@ -1335,6 +1348,10 @@ class GDScriptParser {
 	bool _is_tool = false;
 	String script_path;
 	bool for_completion = false;
+#ifdef TOOLS_ENABLED
+	bool for_export = false;
+	HashSet<String> export_features;
+#endif
 	bool parse_body = true;
 	bool panic_mode = false;
 	bool can_break = false;
@@ -1519,6 +1536,7 @@ class GDScriptParser {
 	bool warning_ignore_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool warning_ignore_region_annotations(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool rpc_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
+	bool if_features_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	// Statements.
 	Node *parse_statement();
 	VariableNode *parse_variable(bool p_is_static);
@@ -1590,6 +1608,15 @@ class GDScriptParser {
 	void get_annotation_list(List<MethodInfo> *r_annotations) const;
 	bool annotation_exists(const String &p_annotation_name) const;
 
+#ifdef TOOLS_ENABLED
+	bool is_for_export() const { return for_export; }
+	void set_export_features(const HashSet<String> &p_features) {
+		for_export = true;
+		export_features = p_features;
+	}
+	void collect_unfitting_functions(ClassNode *p_class, LocalVector<Pair<ClassNode *, FunctionNode *>> &r_functions);
+#endif
+
 	const List<ParserError> &get_errors() const { return errors; }
 	const List<String> get_dependencies() const {
 		// TODO: Keep track of deps.
@@ -1636,7 +1663,7 @@ class GDScriptParser {
 		void print_expression(ExpressionNode *p_expression);
 		void print_enum(EnumNode *p_enum);
 		void print_for(ForNode *p_for);
-		void print_function(FunctionNode *p_function, const String &p_context = "Function");
+		void print_function(FunctionNode *p_function, const String &p_context = "Function", bool p_signature_only = false);
 		void print_get_node(GetNodeNode *p_get_node);
 		void print_if(IfNode *p_if, bool p_is_elif = false);
 		void print_identifier(IdentifierNode *p_identifier);
@@ -1662,6 +1689,7 @@ class GDScriptParser {
 
 	public:
 		void print_tree(const GDScriptParser &p_parser);
+		String strinfigy_function_declaration(FunctionNode *p_function);
 	};
 #endif // DEBUG_ENABLED
 	static void cleanup();