Operating System functions.
    public static class OS

Operating System functions. OS wraps the most common functionality to communicate with the host operating system, such as the clipboard, video driver, date and time, timers, environment variables, execution of binaries, command line, etc.

Inheritance Chain

Static Properties

    public static string Clipboard { get; set; }

The clipboard from the host OS. Might be unavailable on some platforms.

    public static int CurrentScreen { get; set; }

The current screen index (starting from 0).

    public static int ExitCode { get; set; }

The exit code passed to the OS when the main loop exits.

    public static bool KeepScreenOn { get; set; }

If true, the engine tries to keep the screen on while the game is running. Useful on mobile.

    public static bool LowProcessorUsageMode { get; set; }

If true, the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile.

    public static Vector2 MaxWindowSize { get; set; }

The maximum size of the window (without counting window manager decorations). Does not affect fullscreen mode. Set to (0, 0) to reset to the system default value.

    public static Vector2 MinWindowSize { get; set; }

The minimum size of the window (without counting window manager decorations). Does not affect fullscreen mode. Set to (0, 0) to reset to the system default value.

    public static ScreenOrientationEnum ScreenOrientation { get; set; }

The current screen orientation.

    public static Object Singleton { get; }

    public static bool VsyncEnabled { get; set; }

If true, vertical synchronization (Vsync) is enabled.

    public static bool WindowBorderless { get; set; }

If true, removes the window frame.

Note: Setting window_borderless to false disables per-pixel transparency.

    public static bool WindowFullscreen { get; set; }

If true, the window is fullscreen.

    public static bool WindowMaximized { get; set; }

If true, the window is maximized.

    public static bool WindowMinimized { get; set; }

If true, the window is minimized.

    public static bool WindowPerPixelTransparencyEnabled { get; set; }

If true, the window background is transparent and window frame is removed.

Use get_tree().get_root().set_transparent_background(true) to disable main viewport background rendering.

Note: This property has no effect if Project > Project Settings > Display > Window > Per-pixel transparency > Allowed setting is disabled.

    public static Vector2 WindowPosition { get; set; }

The window position relative to the screen, the origin is the top left corner, +Y axis goes to the bottom and +X axis goes to the right.

    public static bool WindowResizable { get; set; }

If true, the window is resizable by the user.

    public static Vector2 WindowSize { get; set; }

The size of the window (without counting window manager decorations).

Static Methods

    public static 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.

    public static bool CanDraw()

Returns true if the host OS allows drawing.

    public static bool CanUseThreads()

Returns true if the current host platform is using multiple threads.

    public static void CenterWindow()

Centers the window on the screen if in windowed mode.

    public static void CloseMidiInputs()

    public static void DelayMsec(uint msec)

    public static void DelayUsec(uint usec)

    public static void DumpMemoryToFile(string file)

Dumps the memory allocation ringlist to a file (only works in debug).

Entry format per line: “Address - Size - Description”.

    public static void DumpResourcesToFile(string file)

Dumps all used resources to file (only works in debug).

Entry format per line: “Resource Type : Resource Location”.

At the end of the file is a statistic of all used Resource Types.

    public static int Execute(string path, string[] arguments, bool blocking, Godot.Collections.Array output = null, bool readStderr = false)

Execute the file at the given path with the arguments passed as an array of strings. Platform path resolution will take place. The resolved file must exist and be executable.

The arguments are used in the given order and separated by a space, so OS.execute("ping", ["-w", "3", "godotengine.org"], false) will resolve to ping -w 3 godotengine.org in the system’s shell.

This method has slightly different behavior based on whether the blocking mode is enabled.

If blocking is true, the Godot thread will pause its execution while waiting for the process to terminate. The shell output of the process will be written to the output array as a single string. When the process terminates, the Godot thread will resume execution.

If blocking is false, the Godot thread will continue while the new process runs. It is not possible to retrieve the shell output in non-blocking mode, so output will be empty.

The return value also depends on the blocking mode. When blocking, the method will return an exit code of the process. When non-blocking, the method returns a process ID, which you can use to monitor the process (and potentially terminate it with Kill(int)). If the process forking (non-blocking) or opening (blocking) fails, the method will return -1 or another exit code.

Example of blocking mode and retrieving the shell output:

[codeblock]

var output = []

var exit_code = OS.execute(“ls”, [“-l”, “/tmp”], true, output)

[/codeblock]

Example of non-blocking mode, running another instance of the project and storing its process ID:

[codeblock]

var pid = OS.execute(OS.get_executable_path(), [], false)

[/codeblock]

If you wish to access a shell built-in or perform a composite command, a platform-specific shell can be invoked. For example:

[codeblock]

OS.execute(“CMD.exe”, [“/C”, “cd %TEMP% && dir”], true, output)

[/codeblock]

    public static int FindScancodeFromString(string @string)

Returns the scancode of the given string (e.g. “Escape”).

    public static int GetAudioDriverCount()

Returns the total number of available audio drivers.

    public static string GetAudioDriverName(int driver)

Returns the audio driver name for the given index.

    [Obsolete("GetBorderlessWindow is deprecated. Use the WindowBorderless property instead.")]
    public static bool GetBorderlessWindow()

Getter for WindowBorderless

    [Obsolete("GetClipboard is deprecated. Use the Clipboard property instead.")]
    public static string GetClipboard()

Getter for Clipboard

    public static string[] GetCmdlineArgs()

Returns the command line arguments passed to the engine.

    public static string[] GetConnectedMidiInputs()

    [Obsolete("GetCurrentScreen is deprecated. Use the CurrentScreen property instead.")]
    public static int GetCurrentScreen()

Getter for CurrentScreen

    public static VideoDriver GetCurrentVideoDriver()

Returns the currently used video driver, using one of the values from VideoDriver.

    public static Dictionary GetDate(bool utc = false)

Returns current date as a dictionary of keys: year, month, day, weekday, dst (Daylight Savings Time).

    public static Dictionary GetDatetime(bool utc = false)

Returns current datetime as a dictionary of keys: year, month, day, weekday, dst (Daylight Savings Time), hour, minute, second.

    public static Dictionary GetDatetimeFromUnixTime(long unixTimeVal)

    public static ulong GetDynamicMemoryUsage()

    public static string GetEnvironment(string environment)

Returns an environment variable.

    public static string GetExecutablePath()

Returns the path to the current engine executable.

    [Obsolete("GetExitCode is deprecated. Use the ExitCode property instead.")]
    public static int GetExitCode()

Getter for ExitCode

    public static Vector2 GetImeSelection()

Returns the IME cursor position (the currently-edited portion of the string) relative to the characters in the composition string.

[constant MainLoop.NOTIFICATION_OS_IME_UPDATE] is sent to the application to notify it of changes to the IME cursor position.

    public static string GetImeText()

Returns the IME intermediate composition string.

[constant MainLoop.NOTIFICATION_OS_IME_UPDATE] is sent to the application to notify it of changes to the IME composition string.

    public static string GetLatinKeyboardVariant()

Returns the current latin keyboard variant as a String.

Possible return values are: "QWERTY", "AZERTY", "QZERTY", "DVORAK", "NEO", "COLEMAK" or "ERROR".

    public static string GetLocale()

Returns the host OS locale.

    [Obsolete("GetMaxWindowSize is deprecated. Use the MaxWindowSize property instead.")]
    public static Vector2 GetMaxWindowSize()

Getter for MaxWindowSize

    [Obsolete("GetMinWindowSize is deprecated. Use the MinWindowSize property instead.")]
    public static Vector2 GetMinWindowSize()

Getter for MinWindowSize

    public static string GetModelName()

Returns the model name of the current device.

    public static string GetName()

Returns the name of the host OS. Possible values are: "Android", "Haiku", "iOS", "HTML5", "OSX", "Server", "Windows", "UWP", "X11".

    public static int GetPowerPercentLeft()

Returns the amount of battery left in the device as a percentage.

    public static int GetPowerSecondsLeft()

Returns an estimate of the time left in seconds before the device runs out of battery.

    public static PowerState GetPowerState()

Returns the current state of the device regarding battery and power. See PowerState constants.

    public static int GetProcessId()

Returns the project’s process ID.

    public static int GetProcessorCount()

Returns the number of threads available on the host machine.

    public static Vector2 GetRealWindowSize()

Returns the window size including decorations like window borders.

    public static string GetScancodeString(uint code)

    public static int GetScreenCount()

Returns the number of displays attached to the host machine.

    public static int GetScreenDpi(int screen = -1)

Returns the dots per inch density of the specified screen.

On Android devices, the actual screen densities are grouped into six generalized densities:

[codeblock]

ldpi - 120 dpi

mdpi - 160 dpi

hdpi - 240 dpi

xhdpi - 320 dpi

xxhdpi - 480 dpi

xxxhdpi - 640 dpi

[/codeblock]

    [Obsolete("GetScreenOrientation is deprecated. Use the ScreenOrientation property instead.")]
    public static ScreenOrientationEnum GetScreenOrientation()

Getter for ScreenOrientation

    public static Vector2 GetScreenPosition(int screen = -1)

Returns the position of the specified screen by index. If no screen index is provided, the current screen will be used.

    public static Vector2 GetScreenSize(int screen = -1)

Returns the dimensions in pixels of the specified screen.

    public static uint GetSplashTickMsec()

    public static ulong GetStaticMemoryPeakUsage()

    public static ulong GetStaticMemoryUsage()

    public static string GetSystemDir(SystemDir dir)

Returns the actual path to commonly used folders across different platforms. Available locations are specified in SystemDir.

    public static ulong GetSystemTimeMsecs()

    public static ulong GetSystemTimeSecs()

    public static uint GetTicksMsec()

    public static ulong GetTicksUsec()

    public static Dictionary GetTime(bool utc = false)

Returns current time as a dictionary of keys: hour, minute, second.

    public static Dictionary GetTimeZoneInfo()

Returns the current time zone as a dictionary with the keys: bias and name.

    public static string GetUniqueId()

Returns a string that is unique to the device.

Note: Returns an empty string on HTML5 and UWP, as this method isn’t implemented on those platforms yet.

    public static ulong GetUnixTime()

    public static long GetUnixTimeFromDatetime(Dictionary datetime)

    public static string GetUserDataDir()

Returns the absolute directory path where user data is written (user://).

On Linux, this is ~/.local/share/godot/app_userdata/[project_name], or ~/.local/share/[custom_name] if use_custom_user_dir is set.

On macOS, this is ~/Library/Application Support/Godot/app_userdata/[project_name], or ~/Library/Application Support/[custom_name] if use_custom_user_dir is set.

On Windows, this is %APPDATA%\Godot\app_userdata\[project_name], or %APPDATA%\[custom_name] if use_custom_user_dir is set. %APPDATA% expands to %USERPROFILE%\AppData\Roaming.

If the project name is empty, user:// falls back to res://.

    public static int GetVideoDriverCount()

Returns the number of video drivers supported on the current platform.

    public static string GetVideoDriverName(VideoDriver driver)

Returns the name of the video driver matching the given driver index. This index is a value from VideoDriver, and you can use GetCurrentVideoDriver() to get the current backend’s index.

    public static int GetVirtualKeyboardHeight()

Returns the on-screen keyboard’s height in pixels. Returns 0 if there is no keyboard or if it is currently hidden.

    [Obsolete("GetWindowPerPixelTransparencyEnabled is deprecated. Use the WindowPerPixelTransparencyEnabled property instead.")]
    public static bool GetWindowPerPixelTransparencyEnabled()

Getter for WindowPerPixelTransparencyEnabled

    [Obsolete("GetWindowPosition is deprecated. Use the WindowPosition property instead.")]
    public static Vector2 GetWindowPosition()

Getter for WindowPosition

    public static Rect2 GetWindowSafeArea()

Returns unobscured area of the window where interactive controls should be rendered.

    [Obsolete("GetWindowSize is deprecated. Use the WindowSize property instead.")]
    public static Vector2 GetWindowSize()

Getter for WindowSize

    public static void GlobalMenuAddItem(string menu, string label, object id, object meta)

Add a new item with text “label” to global menu. Use “_dock” menu to add item to the macOS dock icon menu.

    public static void GlobalMenuAddSeparator(string menu)

Add a separator between items. Separators also occupy an index.

    public static void GlobalMenuClear(string menu)

Clear the global menu, in effect removing all items.

    public static void GlobalMenuRemoveItem(string menu, int idx)

Removes the item at index “idx” from the global menu. Note that the indexes of items after the removed item are going to be shifted by one.

    public static bool HasEnvironment(string environment)

Returns true if an environment variable exists.

    public static bool HasFeature(string tagName)

Returns true if the feature for the given feature tag is supported in the currently running instance, depending on 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.

Note: Tag names are case-sensitive.

    public static bool HasTouchscreenUiHint()

Returns true if the device has a touchscreen or emulates one.

    public static bool HasVirtualKeyboard()

Returns true if the platform has a virtual keyboard, false otherwise.

    public static void HideVirtualKeyboard()

Hides the virtual keyboard if it is shown, does nothing otherwise.

    public static bool IsDebugBuild()

Returns true if the build is a debug build.

Returns true when running in the editor.

Returns false if the build is a release build.

    [Obsolete("IsInLowProcessorUsageMode is deprecated. Use the LowProcessorUsageMode property instead.")]
    public static bool IsInLowProcessorUsageMode()

Getter for LowProcessorUsageMode

    [Obsolete("IsKeepScreenOn is deprecated. Use the KeepScreenOn property instead.")]
    public static bool IsKeepScreenOn()

Getter for KeepScreenOn

    public static bool IsOkLeftAndCancelRight()

Returns true if the OK button should appear on the left and Cancel on the right.

    public static bool IsScancodeUnicode(uint code)

    public static bool IsStdoutVerbose()

Returns true if the engine was executed with -v (verbose stdout).

    public static bool IsUserfsPersistent()

If true, the user:// file system is persistent, so that its state is the same after a player quits and starts the game again. Relevant to the HTML5 platform, where this persistence may be unavailable.

    [Obsolete("IsVsyncEnabled is deprecated. Use the VsyncEnabled property instead.")]
    public static bool IsVsyncEnabled()

Getter for VsyncEnabled

    public static bool IsWindowAlwaysOnTop()

Returns true if the window should always be on top of other windows.

    [Obsolete("IsWindowFullscreen is deprecated. Use the WindowFullscreen property instead.")]
    public static bool IsWindowFullscreen()

Getter for WindowFullscreen

    [Obsolete("IsWindowMaximized is deprecated. Use the WindowMaximized property instead.")]
    public static bool IsWindowMaximized()

Getter for WindowMaximized

    [Obsolete("IsWindowMinimized is deprecated. Use the WindowMinimized property instead.")]
    public static bool IsWindowMinimized()

Getter for WindowMinimized

    [Obsolete("IsWindowResizable is deprecated. Use the WindowResizable property instead.")]
    public static bool IsWindowResizable()

Getter for WindowResizable

    public static Error Kill(int pid)

Kill (terminate) the process identified by the given process ID (pid), e.g. the one returned by Execute(string, string[], bool, Godot.Collections.Array, bool) in non-blocking mode.

Note: This method can also be used to kill processes that were not spawned by the game.

    public static void MoveWindowToForeground()

Moves the window to the front.

    public static bool NativeVideoIsPlaying()

Returns true if native video is playing.

    public static void NativeVideoPause()

Pauses native video playback.

    public static Error NativeVideoPlay(string path, float volume, string audioTrack, string subtitleTrack)

Plays native video from the specified path, at the given volume and with audio and subtitle tracks.

Note: This method is only implemented on Android and iOS, and the current Android implementation does not support the volume, audioTrack and subtitleTrack options.

    public static void NativeVideoStop()

Stops native video playback.

    public static void NativeVideoUnpause()

Resumes native video playback.

    public static void OpenMidiInputs()

    public static void PrintAllResources(string tofile = "")

Shows all resources in the game. Optionally, the list can be written to a file by specifying a file path in tofile.

    public static void PrintAllTexturesBySize()

Shows the list of loaded textures sorted by size in memory.

    public static void PrintResourcesByType(string[] types)

Shows the number of resources loaded by the game of the given types.

    public static void PrintResourcesInUse(bool @short = false)

Shows all resources currently used by the game.

    public static void RequestAttention()

Request the user attention to the window. It’ll flash the taskbar button on Windows or bounce the dock icon on OSX.

    public static bool RequestPermission(string name)

At the moment this function is only used by AudioDriverOpenSL to request permission for RECORD_AUDIO on Android.

    [Obsolete("SetBorderlessWindow is deprecated. Use the WindowBorderless property instead.")]
    public static void SetBorderlessWindow(bool borderless)

Setter for WindowBorderless

    [Obsolete("SetClipboard is deprecated. Use the Clipboard property instead.")]
    public static void SetClipboard(string clipboard)

Setter for Clipboard

    [Obsolete("SetCurrentScreen is deprecated. Use the CurrentScreen property instead.")]
    public static void SetCurrentScreen(int screen)

Setter for CurrentScreen

    [Obsolete("SetExitCode is deprecated. Use the ExitCode property instead.")]
    public static void SetExitCode(int code)

Setter for ExitCode

    public static void SetIcon(Image icon)

Sets the game’s icon using an Image resource.

The same image is used for window caption, taskbar/dock and window selection dialog. Image is scaled as needed.

    public static void SetImeActive(bool active)

Sets whether IME input mode should be enabled.

If active IME handles key events before the application and creates an composition string and suggestion list.

Application can retrieve the composition status by using GetImeSelection() and GetImeText() functions.

Completed composition string is committed when input is finished.

    public static void SetImePosition(Vector2 position)

Sets position of IME suggestion list popup (in window coordinates).

    [Obsolete("SetKeepScreenOn is deprecated. Use the KeepScreenOn property instead.")]
    public static void SetKeepScreenOn(bool enabled)

Setter for KeepScreenOn

    [Obsolete("SetLowProcessorUsageMode is deprecated. Use the LowProcessorUsageMode property instead.")]
    public static void SetLowProcessorUsageMode(bool enable)

Setter for LowProcessorUsageMode

    [Obsolete("SetMaxWindowSize is deprecated. Use the MaxWindowSize property instead.")]
    public static void SetMaxWindowSize(Vector2 size)

Setter for MaxWindowSize

    [Obsolete("SetMinWindowSize is deprecated. Use the MinWindowSize property instead.")]
    public static void SetMinWindowSize(Vector2 size)

Setter for MinWindowSize

    public static void SetNativeIcon(string filename)

Sets the game’s icon using a multi-size platform-specific icon file (*.ico on Windows and *.icns on macOS).

Appropriate size sub-icons are used for window caption, taskbar/dock and window selection dialog.

Note: This method is only implemented on macOS and Windows.

    [Obsolete("SetScreenOrientation is deprecated. Use the ScreenOrientation property instead.")]
    public static void SetScreenOrientation(ScreenOrientationEnum orientation)

Setter for ScreenOrientation

    public static Error SetThreadName(string name)

Sets the name of the current thread.

    public static void SetUseFileAccessSaveAndSwap(bool enabled)

Enables backup saves if enabled is true.

    [Obsolete("SetUseVsync is deprecated. Use the VsyncEnabled property instead.")]
    public static void SetUseVsync(bool enable)

Setter for VsyncEnabled

    public static void SetWindowAlwaysOnTop(bool enabled)

Sets whether the window should always be on top.

    [Obsolete("SetWindowFullscreen is deprecated. Use the WindowFullscreen property instead.")]
    public static void SetWindowFullscreen(bool enabled)

Setter for WindowFullscreen

    [Obsolete("SetWindowMaximized is deprecated. Use the WindowMaximized property instead.")]
    public static void SetWindowMaximized(bool enabled)

Setter for WindowMaximized

    [Obsolete("SetWindowMinimized is deprecated. Use the WindowMinimized property instead.")]
    public static void SetWindowMinimized(bool enabled)

Setter for WindowMinimized

    [Obsolete("SetWindowPerPixelTransparencyEnabled is deprecated. Use the WindowPerPixelTransparencyEnabled property instead.")]
    public static void SetWindowPerPixelTransparencyEnabled(bool enabled)

Setter for WindowPerPixelTransparencyEnabled

    [Obsolete("SetWindowPosition is deprecated. Use the WindowPosition property instead.")]
    public static void SetWindowPosition(Vector2 position)

Setter for WindowPosition

    [Obsolete("SetWindowResizable is deprecated. Use the WindowResizable property instead.")]
    public static void SetWindowResizable(bool enabled)

Setter for WindowResizable

    [Obsolete("SetWindowSize is deprecated. Use the WindowSize property instead.")]
    public static void SetWindowSize(Vector2 size)

Setter for WindowSize

    public static void SetWindowTitle(string title)

Sets the window title to the specified string.

Note: This should be used sporadically. Don’t set this every frame, as that will negatively affect performance on some window managers.

    public static Error ShellOpen(string uri)

Requests the OS to open a resource with the most appropriate program. For example:

  • OS.shell_open("C:\\Users\name\Downloads") on Windows opens the file explorer at the user’s Downloads folder.

  • OS.shell_open("https://godotengine.org") opens the default web browser on the official Godot website.

  • OS.shell_open("mailto:example@example.com") opens the default email client with the “To” field set to example@example.com. See [url=https://blog.escapecreative.com/customizing-mailto-links/]Customizing mailto: Links[/url] for a list of fields that can be added.

    public static void ShowVirtualKeyboard(string existingText = "")

Shows the virtual keyboard if the platform has one. The existingText parameter is useful for implementing your own LineEdit, as it tells the virtual keyboard what text has already been typed (the virtual keyboard uses it for auto-correct and predictions).

Inner Types

Month

Name Value Description
January 1 January.
February 2 February.
March 3 March.
April 4 April.
May 5 May.
June 6 June.
July 7 July.
August 8 August.
September 9 September.
October 10 October.
November 11 November.
December 12 December.

PowerState

Name Value Description
Unknown 0 Unknown powerstate.
OnBattery 1 Unplugged, running on battery.
NoBattery 2 Plugged in, no battery available.
Charging 3 Plugged in, battery charging.
Charged 4 Plugged in, battery fully charged.

ScreenOrientationEnum

Name Value Description
Landscape 0 Landscape screen orientation.
Portrait 1 Portrait screen orientation.
ReverseLandscape 2 Reverse landscape screen orientation.
ReversePortrait 3 Reverse portrait screen orientation.
SensorLandscape 4 Uses landscape or reverse landscape based on the hardware sensor.
SensorPortrait 5 Uses portrait or reverse portrait based on the hardware sensor.
Sensor 6 Uses most suitable orientation based on the hardware sensor.

SystemDir

Name Value Description
Desktop 0 Desktop directory path.
Dcim 1 DCIM (Digital Camera Images) directory path.
Documents 2 Documents directory path.
Downloads 3 Downloads directory path.
Movies 4 Movies directory path.
Music 5 Music directory path.
Pictures 6 Pictures directory path.
Ringtones 7 Ringtones directory path.

VideoDriver

Name Value Description
Gles2    
Gles3    

Weekday

Name Value Description
Sunday 0 Sunday.
Monday 1 Monday.
Tuesday 2 Tuesday.
Wednesday 3 Wednesday.
Thursday 4 Thursday.
Friday 5 Friday.
Saturday 6 Saturday.
Tags: