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
Provides access to common operating system functionalities.
Description¶
This class wraps the most common functionalities for communicating with the host operating system, such as the 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, separated by spaces, and wrapped in quotes. 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[]