Bite-sized Godot: The OS Class

Sample project

Godot’s OS class offers you direct communication with the user’s operating system, and while there’s a lot here that is best left alone, there’s also a lot of convenience to be found in order to provide a better experience to the user. Let’s take a look.

Display settings

Arguably, the most important features the OS class offers are related to how your game is displayed to the user. Controls for fullscreen display, vsync, and window size and positioning (including centering the window on the screen) are all available in this class via simple interfaces. Since all of these features are a single line to use, here’s a rapid fire overview of them:


# Make the application fullscreen
OS.window_fullscreen = true

# Toggle fullscreen settings
func toggle_fullscreen() -> void:
    OS.window_fullscreen = !OS.window_fullscreen


# Turn on vsync
OS.vsync_enabled = true

# Toggle vsync settings
func toggle_vsync() -> void:
    OS.vsync_enabled = !OS.vsync_enabled

Window size

# Adjust window size
OS.window_size = Vector2(1280, 720)

Window position and centering

# From the docs:
# 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.

# Move the window to the top-left corner of the screen
OS.window_position = Vector2(0, 0)

# Automatically center the window on the screen

Information about the user’s machine

There’s also some handy information available to you regarding the user’s machine. Here’s three options that you might find useful.

The current date and time

You’ve got two options to get the system time, depending on what you’re interested in.

# Returns current date as a dictionary of keys: year, month, day, weekday, dst (Daylight Savings Time).
# Can change parameter to true to get the UTC time

# Returns current datetime as a dictionary of keys: year, month, day, weekday, dst (Daylight Savings Time), hour, minute, second.
# Can change parameter to true to get the UTC time

Additionally, you can convert epoch seconds to this same format using the get_datetime_from_unix_time method (possibly useful if you’re pulling in data from an external source).

Clipboard contents

You can also read from and write to the system clipboard using OS.clipboard like you would any other string variable.

# Copy string to system clipboard
OS.clipboard = 'My clipboard entry'

# Print out whatever is in the system clipboard

Monitor size

There’s a few variations of these data available depending on what you need, but here’s some samples of the monitor information your game can access.

# Get the number of screens attached to the machine

# Get the size of the given screen, in pixels
# Note that this value can differ from the actual, physical resolution if display scaling is active

# Get the DPI of the given screen

On some projects I have, for instance, used OS.get_screen_size() to filter the list of available window resolutions to only what is smaller than the user’s screen.

Don’t abuse this

As a final wrap-up, let me just point out that there are several things in the OS class that I would personally consider off limits, in particular any non-read operations outside of your display settings (which are more application oriented anyways). The ability to run arbitrary processes on a system level or kill other processes, for instance, should just about never be used by a game. Not only is it almost certainly not necessary, it’s error prone and system level access is on a whole other level than game development. As a user I would personally consider it a violation of my trust if a program was doing this.

Just remember what Uncle Ben said.