summaryrefslogtreecommitdiff
path: root/doc/classes/OS.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/classes/OS.xml')
-rw-r--r--doc/classes/OS.xml132
1 files changed, 116 insertions, 16 deletions
diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml
index f4d48f5db2..266a2573de 100644
--- a/doc/classes/OS.xml
+++ b/doc/classes/OS.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8" ?>
-<class name="OS" inherits="Object" version="4.0">
+<class name="OS" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Operating System functions.
</brief_description>
@@ -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" />
@@ -44,8 +51,10 @@
<return type="int" />
<argument index="0" name="path" type="String" />
<argument index="1" name="arguments" type="PackedStringArray" />
+ <argument index="2" name="open_console" type="bool" default="false" />
<description>
Creates a new process that runs independently of Godot. It will not terminate if Godot terminates. The path specified in [code]path[/code] must exist and be executable file or macOS .app bundle. Platform path resolution will be used. The [code]arguments[/code] are used in the given order and separated by a space.
+ On Windows, if [code]open_console[/code] is [code]true[/code] and the process is a console app, a new terminal window will be opened. This is ignored on other platforms.
If the process creation succeeds, the method will return the new process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process creation fails, the method will return [code]-1[/code].
For example, running another instance of the project:
[codeblocks]
@@ -102,8 +111,10 @@
<argument index="1" name="arguments" type="PackedStringArray" />
<argument index="2" name="output" type="Array" default="[]" />
<argument index="3" name="read_stderr" type="bool" default="false" />
+ <argument index="4" name="open_console" type="bool" default="false" />
<description>
Executes a command. The file specified in [code]path[/code] must exist and be executable. Platform path resolution will be used. The [code]arguments[/code] are used in the given order and separated by a space. If an [code]output[/code] [Array] is provided, the complete shell output of the process will be appended as a single [String] element in [code]output[/code]. If [code]read_stderr[/code] is [code]true[/code], the output to the standard error stream will be included too.
+ On Windows, if [code]open_console[/code] is [code]true[/code] and the process is a console app, a new terminal window will be opened. This is ignored on other platforms.
If the command is successfully executed, the method will return the exit code of the command, or [code]-1[/code] if it fails.
[b]Note:[/b] The Godot thread will pause its execution until the executed command terminates. Use [Thread] to create a separate thread that will not pause the Godot thread, or use [method create_process] to create a completely independent process.
For example, to retrieve a list of the working directory's contents:
@@ -117,7 +128,7 @@
int exitCode = OS.Execute("ls", new string[] {"-l", "/tmp"}, output);
[/csharp]
[/codeblocks]
- To execute a composite command, a platform-specific shell can be invoked. For example:
+ If you wish to access a shell built-in or execute a composite command, a platform-specific shell can be invoked. For example:
[codeblocks]
[gdscript]
var output = []
@@ -129,11 +140,14 @@
[/csharp]
[/codeblocks]
[b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows.
+ [b]Note:[/b] To execute a Windows command interpreter built-in command, specify [code]cmd.exe[/code] in [code]path[/code], [code]/c[/code] as the first argument, and the desired command as the second argument.
+ [b]Note:[/b] To execute a PowerShell built-in command, specify [code]powershell.exe[/code] in [code]path[/code], [code]-Command[/code] as the first argument, and the desired command as the second argument.
+ [b]Note:[/b] To execute a Unix shell built-in command, specify shell executable name in [code]path[/code], [code]-c[/code] as the first argument, and the desired command as the second argument.
[b]Note:[/b] On macOS, sandboxed applications are limited to run only embedded helper executables, specified during export.
</description>
</method>
<method name="find_keycode_from_string" qualifiers="const">
- <return type="int" />
+ <return type="int" enum="Key" />
<argument index="0" name="string" type="String" />
<description>
Returns the keycode of the given string (e.g. "Escape").
@@ -142,7 +156,7 @@
<method name="get_cache_dir" qualifiers="const">
<return type="String" />
<description>
- Returns the [i]global[/i] cache data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the [code]XDG_CACHE_HOME[/code] environment variable before starting the project. See [url=https://docs.godotengine.org/en/latest/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_config_dir] and [method get_data_dir].
+ Returns the [i]global[/i] cache data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the [code]XDG_CACHE_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_config_dir] and [method get_data_dir].
Not to be confused with [method get_user_data_dir], which returns the [i]project-specific[/i] user data path.
</description>
</method>
@@ -179,7 +193,7 @@
<method name="get_config_dir" qualifiers="const">
<return type="String" />
<description>
- Returns the [i]global[/i] user configuration directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the [code]XDG_CONFIG_HOME[/code] environment variable before starting the project. See [url=https://docs.godotengine.org/en/latest/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_data_dir].
+ Returns the [i]global[/i] user configuration directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the [code]XDG_CONFIG_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_data_dir].
Not to be confused with [method get_user_data_dir], which returns the [i]project-specific[/i] user data path.
</description>
</method>
@@ -194,7 +208,7 @@
<method name="get_data_dir" qualifiers="const">
<return type="String" />
<description>
- Returns the [i]global[/i] user data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the [code]XDG_DATA_HOME[/code] environment variable before starting the project. See [url=https://docs.godotengine.org/en/latest/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_config_dir].
+ Returns the [i]global[/i] user data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the [code]XDG_DATA_HOME[/code] environment variable before starting the project. See [url=$DOCS_URL/tutorials/io/data_paths.html]File paths in Godot projects[/url] in the documentation for more information. See also [method get_cache_dir] and [method get_config_dir].
Not to be confused with [method get_user_data_dir], which returns the [i]project-specific[/i] user data path.
</description>
</method>
@@ -222,7 +236,7 @@
</method>
<method name="get_keycode_string" qualifiers="const">
<return type="String" />
- <argument index="0" name="code" type="int" />
+ <argument index="0" name="code" type="int" enum="Key" />
<description>
Returns the given keycode as a string (e.g. Return values: [code]"Escape"[/code], [code]"Shift+Escape"[/code]).
See also [member InputEventKey.keycode] and [method InputEventKey.get_keycode_with_modifiers].
@@ -246,6 +260,13 @@
This can be used to narrow down fully specified locale strings to only the "common" language code, when you don't need the additional information about country code or variants. For example, for a French Canadian user with [code]fr_CA[/code] locale, this would return [code]fr[/code].
</description>
</method>
+ <method name="get_main_thread_id" qualifiers="const">
+ <return type="int" />
+ <description>
+ Returns the ID of the main thread. See [method get_thread_caller_id].
+ [b]Note:[/b] Thread IDs are not deterministic and may be reused across application restarts.
+ </description>
+ </method>
<method name="get_model_name" qualifiers="const">
<return type="String" />
<description>
@@ -256,7 +277,60 @@
<method name="get_name" qualifiers="const">
<return type="String" />
<description>
- Returns the name of the host OS. Possible values are: [code]"Android"[/code], [code]"iOS"[/code], [code]"HTML5"[/code], [code]"macOS"[/code], [code]"Server"[/code], [code]"Windows"[/code], [code]"UWP"[/code], [code]"X11"[/code].
+ Returns the name of the host OS.
+ On Windows, this is [code]"Windows"[/code] or [code]"UWP"[/code] if exported on Universal Windows Platform.
+ On macOS, this is [code]"macOS"[/code].
+ On Linux-based operating systems, this is [code]"Linux"[/code].
+ On BSD-based operating systems, this is [code]"FreeBSD"[/code], [code]"NetBSD"[/code], [code]"OpenBSD"[/code], or [code]"BSD"[/code] as a fallback.
+ On Android, this is [code]"Android"[/code].
+ On iOS, this is [code]"iOS"[/code].
+ On the web, this is [code]"HTML5"[/code].
+ [b]Note:[/b] Custom builds of the engine may support additional platforms, such as consoles, yielding other return values.
+ [codeblocks]
+ [gdscript]
+ match OS.get_name():
+ "Windows", "UWP":
+ print("Windows")
+ "macOS":
+ print("macOS")
+ "Linux", "FreeBSD", "NetBSD", "OpenBSD", "BSD":
+ print("Linux/BSD")
+ "Android":
+ print("Android")
+ "iOS":
+ print("iOS")
+ "HTML5":
+ print("Web")
+ [/gdscript]
+ [csharp]
+ switch (OS.GetName())
+ {
+ case "Windows":
+ case "UWP":
+ GD.Print("Windows");
+ break;
+ case "macOS":
+ GD.Print("macOS");
+ break;
+ case "Linux":
+ case "FreeBSD":
+ case "NetBSD":
+ case "OpenBSD"
+ case "BSD":
+ GD.Print("Linux/BSD");
+ break;
+ case "Android":
+ GD.Print("Android");
+ break;
+ case "iOS":
+ GD.Print("iOS");
+ break;
+ case "HTML5":
+ GD.Print("Web");
+ break;
+ }
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="get_process_id" qualifiers="const">
@@ -269,7 +343,14 @@
<method name="get_processor_count" qualifiers="const">
<return type="int" />
<description>
- Returns the number of threads available on the host machine.
+ Returns the number of [i]logical[/i] CPU cores available on the host machine. On CPUs with HyperThreading enabled, this number will be greater than the number of [i]physical[/i] CPU cores.
+ </description>
+ </method>
+ <method name="get_processor_name" qualifiers="const">
+ <return type="String" />
+ <description>
+ Returns the name of the CPU model on the host machine (e.g. "Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz").
+ [b]Note:[/b] This method is only implemented on Windows, macOS, Linux and iOS. On Android, HTML5 and UWP, [method get_processor_name] returns an empty string.
</description>
</method>
<method name="get_static_memory_peak_usage" qualifiers="const">
@@ -281,7 +362,7 @@
<method name="get_static_memory_usage" qualifiers="const">
<return type="int" />
<description>
- Returns the amount of static memory being used by the program in bytes.
+ Returns the amount of static memory being used by the program in bytes (only works in debug).
</description>
</method>
<method name="get_system_dir" qualifiers="const">
@@ -313,11 +394,13 @@
<return type="String" />
<description>
Returns the absolute directory path where user data is written ([code]user://[/code]).
- On Linux, this is [code]~/.local/share/godot/app_userdata/[project_name][/code], or [code]~/.local/share/[custom_name][/code] if [code]use_custom_user_dir[/code] is set.
+ On Windows, this is [code]%AppData%\Godot\app_userdata\[project_name][/code], or [code]%AppData%\[custom_name][/code] if [code]use_custom_user_dir[/code] is set. [code]%AppData%[/code] expands to [code]%UserProfile%\AppData\Roaming[/code].
On macOS, this is [code]~/Library/Application Support/Godot/app_userdata/[project_name][/code], or [code]~/Library/Application Support/[custom_name][/code] if [code]use_custom_user_dir[/code] is set.
- On Windows, this is [code]%APPDATA%\Godot\app_userdata\[project_name][/code], or [code]%APPDATA%\[custom_name][/code] if [code]use_custom_user_dir[/code] is set. [code]%APPDATA%[/code] expands to [code]%USERPROFILE%\AppData\Roaming[/code].
- If the project name is empty, [code]user://[/code] falls back to [code]res://[/code].
- Not to be confused with [method get_data_dir], which returns the [i]global[/i] (non-project-specific) user data directory.
+ On Linux and BSD, this is [code]~/.local/share/godot/app_userdata/[project_name][/code], or [code]~/.local/share/[custom_name][/code] if [code]use_custom_user_dir[/code] is set.
+ On Android and iOS, this is a sandboxed directory in either internal or external storage, depending on the user's configuration.
+ On the web, this is a virtual directory managed by the browser.
+ If the project name is empty, [code][project_name][/code] falls back to [code][unnamed project][/code].
+ Not to be confused with [method get_data_dir], which returns the [i]global[/i] (non-project-specific) user home directory.
</description>
</method>
<method name="has_environment" qualifiers="const">
@@ -332,7 +415,7 @@
<return type="bool" />
<argument index="0" name="tag_name" type="String" />
<description>
- Returns [code]true[/code] if the feature for the given feature tag is supported in the currently running instance, depending on the platform, build, etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the [url=https://docs.godotengine.org/en/latest/getting_started/workflow/export/feature_tags.html]Feature Tags[/url] documentation for more details.
+ Returns [code]true[/code] if the feature for the given feature tag is supported in the currently running instance, depending on the platform, build, etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the [url=$DOCS_URL/getting_started/workflow/export/feature_tags.html]Feature Tags[/url] documentation for more details.
[b]Note:[/b] Tag names are case-sensitive.
</description>
</method>
@@ -351,6 +434,15 @@
Returns [code]true[/code] if the input keycode corresponds to a Unicode character.
</description>
</method>
+ <method name="is_process_running" qualifiers="const">
+ <return type="bool" />
+ <argument index="0" name="pid" type="int" />
+ <description>
+ Returns [code]true[/code] if the child process ID ([code]pid[/code]) is still running or [code]false[/code] if it has terminated.
+ Must be a valid ID generated from [method create_process].
+ [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows.
+ </description>
+ </method>
<method name="is_stdout_verbose" qualifiers="const">
<return type="bool" />
<description>
@@ -367,11 +459,19 @@
<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>
</method>
+ <method name="move_to_trash" qualifiers="const">
+ <return type="int" enum="Error" />
+ <argument index="0" name="path" type="String" />
+ <description>
+ Moves the file or directory to the system's recycle bin. See also [method Directory.remove].
+ [b]Note:[/b] If the user has disabled the recycle bin on their system, the file will be permanently deleted instead.
+ </description>
+ </method>
<method name="open_midi_inputs">
<return type="void" />
<description>
generated by cgit v1.2.3 (git 2.25.1) at 2025-02-01 06:41:54 +0000