Up to date
This page is up to date for Godot 4.0.
If you still find outdated information, please open an issue.
OS¶
Inherits: Object
Operating System functions.
Description¶
Operating System functions. OS wraps the most common functionality to communicate with the host operating system, such as the clipboard, video driver, delays, environment variables, execution of binaries, command line, etc.
Note: In Godot 4, OS functions related to window management were moved to the DisplayServer singleton.
Tutorials¶
Properties¶
|
||
|
Methods¶
Enumerations¶
enum RenderingDriver:
RenderingDriver RENDERING_DRIVER_VULKAN = 0
The Vulkan rendering driver. It requires Vulkan 1.0 support and automatically uses features from Vulkan 1.1 and 1.2 if available.
RenderingDriver RENDERING_DRIVER_OPENGL3 = 1
The OpenGL 3 rendering driver. It uses OpenGL 3.3 Core Profile on desktop platforms, OpenGL ES 3.0 on mobile devices, and WebGL 2.0 on Web.
enum SystemDir:
SystemDir SYSTEM_DIR_DESKTOP = 0
Desktop directory path.
SystemDir SYSTEM_DIR_DCIM = 1
DCIM (Digital Camera Images) directory path.
SystemDir SYSTEM_DIR_DOCUMENTS = 2
Documents directory path.
SystemDir SYSTEM_DIR_DOWNLOADS = 3
Downloads directory path.
SystemDir SYSTEM_DIR_MOVIES = 4
Movies directory path.
SystemDir SYSTEM_DIR_MUSIC = 5
Music directory path.
SystemDir SYSTEM_DIR_PICTURES = 6
Pictures directory path.
SystemDir SYSTEM_DIR_RINGTONES = 7
Ringtones directory path.
Property Descriptions¶
bool low_processor_usage_mode = false
If true, the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile.
int low_processor_usage_mode_sleep_usec = 6900
void set_low_processor_usage_mode_sleep_usec ( int value )
int get_low_processor_usage_mode_sleep_usec ( )
The amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU usage.
Method Descriptions¶
void alert ( String text, String title="Alert!" )
Displays a modal dialog box using the host OS' facilities. Execution is blocked until the dialog is closed.
void close_midi_inputs ( )
Shuts down system MIDI driver.
Note: This method is implemented on Linux, macOS and Windows.
void crash ( String message )
Crashes the engine (or the editor if called within a @tool script). This should only be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) @GDScript.assert, @GlobalScope.push_error or alert. See also kill.
int create_instance ( PackedStringArray arguments )
Creates a new instance of Godot that runs independently. The arguments are used in the given order and separated by a space.
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 kill). If the process creation fails, the method will return -1.
Note: This method is implemented on Android, iOS, Linux, macOS and Windows.
int create_process ( String path, PackedStringArray arguments, bool open_console=false )
Creates a new process that runs independently of Godot. It will not terminate if Godot terminates. The path specified in path must exist and be executable file or macOS .app bundle. Platform path resolution will be used. The arguments are used in the given order and separated by a space.
On Windows, if open_console is true 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 kill). If the process creation fails, the method will return -1.
For example, running another instance of the project:
var pid = OS.create_process(OS.get_executable_path(), [])
var pid = OS.CreateProcess(OS.GetExecutablePath(), new string[] {});
See execute if you wish to run an external command and retrieve the results.
Note: This method is implemented on Android, iOS, Linux, macOS and Windows.
Note: On macOS, sandboxed applications are limited to run only embedded helper executables, specified during export or system .app bundle, system .app bundles will ignore arguments.
void delay_msec ( int msec ) const
Delays execution of the current thread by msec milliseconds. msec must be greater than or equal to 0. Otherwise, delay_msec will do nothing and will print an error message.
Note: delay_msec is a blocking way to delay code execution. To delay code execution in a non-blocking way, see SceneTree.create_timer. Awaiting with SceneTree.create_timer will delay the execution of code placed below the await without affecting the rest of the project (or editor, for EditorPlugins and EditorScripts).
Note: When delay_msec is called on the main thread, it will freeze the project and will prevent it from redrawing and registering input until the delay has passed. When using delay_msec as part of an EditorPlugin or EditorScript, it will freeze the editor but won't freeze the project if it is currently running (since the project is an independent child process).
void delay_usec ( int usec ) const
Delays execution of the current thread by usec microseconds. usec must be greater than or equal to 0. Otherwise, delay_usec will do nothing and will print an error message.
Note: delay_usec is a blocking way to delay code execution. To delay code execution in a non-blocking way, see SceneTree.create_timer. Awaiting with SceneTree.create_timer will delay the execution of code placed below the await without affecting the rest of the project (or editor, for EditorPlugins and EditorScripts).
Note: When delay_usec is called on the main thread, it will freeze the project and will prevent it from redrawing and registering input until the delay has passed. When using delay_usec as part of an EditorPlugin or EditorScript, it will freeze the editor but won't freeze the project if it is currently running (since the project is an independent child process).
int execute ( String path, PackedStringArray arguments, Array output=[], bool read_stderr=false, bool open_console=false )
Executes a command. The file specified in path must exist and be executable. Platform path resolution will be used. The arguments are used in the given order and separated by a space. If an output Array is provided, the complete shell output of the process will be appended as a single String element in output. If read_stderr is true, the output to the standard error stream will be included too.
On Windows, if open_console is true 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 -1 if it fails.
Note: 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 create_process to create a completely independent process.
For example, to retrieve a list of the working directory's contents:
var output = []
var exit_code = OS.execute("ls", ["-l", "/tmp"], output)
var output = new Godot.Collections.Array();
int exitCode = OS.Execute("ls", new string[] {"-l", "/tmp"}, output);
If you wish to access a shell built-in or execute a composite command, a platform-specific shell can be invoked. For example:
var output = []
OS.execute("CMD.exe", ["/C", "cd %TEMP% && dir"], output)
var output = new Godot.Collections.Array();
OS.Execute("CMD.exe", new string[] {"/C", "cd %TEMP% && dir"}, output);
Note: This method is implemented on Android, iOS, Linux, macOS and Windows.
Note: To execute a Windows command interpreter built-in command, specify cmd.exe in path, /c as the first argument, and the desired command as the second argument.
Note: To execute a PowerShell built-in command, specify powershell.exe in path, -Command as the first argument, and the desired command as the second argument.
Note: To execute a Unix shell built-in command, specify shell executable name in path, -c as the first argument, and the desired command as the second argument.
Note: On macOS, sandboxed applications are limited to run only embedded helper executables, specified during export.
Key find_keycode_from_string ( String string ) const
Returns the keycode of the given string (e.g. "Escape").
String get_cache_dir ( ) const
Returns the global cache data directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the XDG_CACHE_HOME environment variable before starting the project. See File paths in Godot projects in the documentation for more information. See also get_config_dir and get_data_dir.
Not to be confused with get_user_data_dir, which returns the project-specific user data path.
PackedStringArray get_cmdline_args ( )
Returns the command-line arguments passed to the engine.
Command-line arguments can be written in any form, including both --key value and --key=value forms so they can be properly parsed, as long as custom command-line arguments do not conflict with engine arguments.
You can also incorporate environment variables using the get_environment method.
You can set ProjectSettings.editor/run/main_run_args to define command-line arguments to be passed by the editor when running the project.
Here's a minimal example on how to parse command-line arguments into a dictionary using the --key=value form for arguments:
var arguments = {}
for argument in OS.get_cmdline_args():
if argument.find("=") > -1:
var key_value = argument.split("=")
arguments[key_value[0].lstrip("--")] = key_value[1]
else:
# Options without an argument will be present in the dictionary,
# with the value set to an empty string.
arguments[argument.lstrip("--")] = ""
var arguments = new Godot.Collections.Dictionary();
foreach (var argument in OS.GetCmdlineArgs())
{
if (argument.Find("=") > -1)
{
string[] keyValue = argument.Split("=");
arguments[keyValue[0].LStrip("--")] = keyValue[1];
}
else
{
// Options without an argument will be present in the dictionary,
// with the value set to an empty string.
arguments[keyValue[0].LStrip("--")] = "";
}
}
Note: Passing custom user arguments directly is not recommended, as the engine may discard or modify them. Instead, the best way is to use the standard UNIX double dash (--) and then pass custom arguments, which the engine itself will ignore. These can be read via get_cmdline_user_args.
PackedStringArray get_cmdline_user_args ( )
Similar to get_cmdline_args, but this returns the user arguments (any argument passed after the double dash -- or double plus ++ argument). These are left untouched by Godot for the user. ++ can be used in situations where -- is intercepted by another program (such as startx).
For example, in the command line below, --fullscreen will not be returned in get_cmdline_user_args and --level 1 will only be returned in get_cmdline_user_args:
godot --fullscreen -- --level 1
# Or:
godot --fullscreen ++ --level 1
String get_config_dir ( ) const
Returns the global user configuration directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the XDG_CONFIG_HOME environment variable before starting the project. See File paths in Godot projects in the documentation for more information. See also get_cache_dir and get_data_dir.
Not to be confused with get_user_data_dir, which returns the project-specific user data path.
PackedStringArray get_connected_midi_inputs ( )
Returns an array of MIDI device names.
The returned array will be empty if the system MIDI driver has not previously been initialized with open_midi_inputs.
Note: This method is implemented on Linux, macOS and Windows.
String get_data_dir ( ) const
Returns the global user data directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the XDG_DATA_HOME environment variable before starting the project. See File paths in Godot projects in the documentation for more information. See also get_cache_dir and get_config_dir.
Not to be confused with get_user_data_dir, which returns the project-specific user data path.
String get_distribution_name ( ) const
Returns the name of the distribution for Linux and BSD platforms (e.g. Ubuntu, Manjaro, OpenBSD, etc.).
Returns the same value as get_name for stock Android ROMs, but attempts to return the custom ROM name for popular Android derivatives such as LineageOS.
Returns the same value as get_name for other platforms.
Note: This method is not supported on the web platform. It returns an empty string.
String get_environment ( String variable ) const
Returns the value of an environment variable. Returns an empty string if the environment variable doesn't exist.
Note: Double-check the casing of variable. Environment variable names are case-sensitive on all platforms except Windows.
String get_executable_path ( ) const
Returns the path to the current engine executable.
Note: On macOS, always use create_instance instead of relying on executable path.
PackedStringArray get_granted_permissions ( ) const
With this function, you can get the list of dangerous permissions that have been granted to the Android application.
Note: This method is implemented on Android.
String get_keycode_string ( Key code ) const
Returns the given keycode as a string (e.g. Return values: "Escape", "Shift+Escape").
See also InputEventKey.keycode and InputEventKey.get_keycode_with_modifiers.
String get_locale ( ) const
Returns the host OS locale as a string of the form language_Script_COUNTRY_VARIANT@extra. If you want only the language code and not the fully specified locale from the OS, you can use get_locale_language.
language - 2 or 3-letter language code, in lower case.
Script - optional, 4-letter script code, in title case.
COUNTRY - optional, 2 or 3-letter country code, in upper case.
VARIANT - optional, language variant, region and sort order. Variant can have any number of underscored keywords.
extra - optional, semicolon separated list of additional key words. Currency, calendar, sort order and numbering system information.
String get_locale_language ( ) const
Returns the host OS locale's 2 or 3-letter language code as a string which should be consistent on all platforms. This is equivalent to extracting the language part of the get_locale string.
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 fr_CA locale, this would return fr.
int get_main_thread_id ( ) const
Returns the ID of the main thread. See get_thread_caller_id.
Note: Thread IDs are not deterministic and may be reused across application restarts.
String get_model_name ( ) const
Returns the model name of the current device.
Note: This method is implemented on Android and iOS. Returns "GenericDevice" on unsupported platforms.
String get_name ( ) const
Returns the name of the host OS.
On Windows, this is "Windows" or "UWP" if exported on Universal Windows Platform.
On macOS, this is "macOS".
On Linux-based operating systems, this is "Linux".
On BSD-based operating systems, this is "FreeBSD", "NetBSD", "OpenBSD", or "BSD" as a fallback.
On Android, this is "Android".
On iOS, this is "iOS".
On the web, this is "Web".
Note: Custom builds of the engine may support additional platforms, such as consoles, yielding other return values.
match OS.get_name():