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:

Fullscreen

# Make the application fullscreen
OS.window_fullscreen = true

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

Vsync

# 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
OS.center_window()

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
OS.get_date(false)

# 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
OS.get_datetime(false)

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
print(OS.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
OS.get_screen_count()

# 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
OS.get_screen_size()

# Get the DPI of the given screen
OS.get_screen_dpi()

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.