From 5761b90f3c7d66f5a93aef57e6a21feb807d24bf Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Fri, 3 Dec 2021 20:36:47 +0100
Subject: [PATCH] Add an `OS.crash()` method for testing system crash handler

This makes it possible to test the system's crash handler without
having to modify engine code or exploit an engine bug.
---
 core/core_bind.cpp | 5 +++++
 core/core_bind.h   | 1 +
 doc/classes/OS.xml | 9 ++++++++-
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/core/core_bind.cpp b/core/core_bind.cpp
index 0bf6efc96db..e71c7648e83 100644
--- a/core/core_bind.cpp
+++ b/core/core_bind.cpp
@@ -207,6 +207,10 @@ void OS::alert(const String &p_alert, const String &p_title) {
 	::OS::get_singleton()->alert(p_alert, p_title);
 }
 
+void OS::crash(const String &p_message) {
+	CRASH_NOW_MSG(p_message);
+}
+
 String OS::get_executable_path() const {
 	return ::OS::get_singleton()->get_executable_path();
 }
@@ -542,6 +546,7 @@ void OS::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("close_midi_inputs"), &OS::close_midi_inputs);
 
 	ClassDB::bind_method(D_METHOD("alert", "text", "title"), &OS::alert, DEFVAL("Alert!"));
+	ClassDB::bind_method(D_METHOD("crash", "message"), &OS::crash);
 
 	ClassDB::bind_method(D_METHOD("set_low_processor_usage_mode", "enable"), &OS::set_low_processor_usage_mode);
 	ClassDB::bind_method(D_METHOD("is_in_low_processor_usage_mode"), &OS::is_in_low_processor_usage_mode);
diff --git a/core/core_bind.h b/core/core_bind.h
index 4bacfa720c6..920f2b539ba 100644
--- a/core/core_bind.h
+++ b/core/core_bind.h
@@ -161,6 +161,7 @@ public:
 	int get_low_processor_usage_mode_sleep_usec() const;
 
 	void alert(const String &p_alert, const String &p_title = "ALERT!");
+	void crash(const String &p_message);
 
 	String get_executable_path() const;
 	int execute(const String &p_path, const Vector<String> &p_arguments, Array r_output = Array(), bool p_read_stderr = false);
diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml
index 7088844547c..a5bd8e2768a 100644
--- a/doc/classes/OS.xml
+++ b/doc/classes/OS.xml
@@ -31,6 +31,13 @@
 				[b]Note:[/b] This method is implemented on Linux, macOS and Windows.
 			</description>
 		</method>
+		<method name="crash">
+			<return type="void" />
+			<argument index="0" name="message" type="String" />
+			<description>
+				Crashes the engine (or the editor if called within a [code]@tool[/code] script). This should [i]only[/i] be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) [method @GDScript.assert], [method @GlobalScope.push_error] or [method alert]. See also [method kill].
+			</description>
+		</method>
 		<method name="create_instance">
 			<return type="int" />
 			<argument index="0" name="arguments" type="PackedStringArray" />
@@ -374,7 +381,7 @@
 			<return type="int" enum="Error" />
 			<argument index="0" name="pid" type="int" />
 			<description>
-				Kill (terminate) the process identified by the given process ID ([code]pid[/code]), e.g. the one returned by [method execute] in non-blocking mode.
+				Kill (terminate) the process identified by the given process ID ([code]pid[/code]), e.g. the one returned by [method execute] in non-blocking mode. See also [method crash].
 				[b]Note:[/b] This method can also be used to kill processes that were not spawned by the game.
 				[b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows.
 			</description>