Utils
Interface which provides access to a range of miscellaneous utility functions.
Available in both the main GodotSteam branches and GodotSteam Server branches
Functions
checkFileSignature
checkFileSignature( string
filename )
Argument | Type | Notes |
---|---|---|
filename | string | Name of the file you want to check the signature on. |
Asynchronous call to check if an executable file has been signed using the public key set on the signing tab of the partner site; for example, to refuse to load modified executable files.
Returns: void
Triggers
Read more in the official Steamworks SDK documentation Added GodotSteam 4.15
dismissFloatingGamepadTextInput
dismissFloatingGamepadTextInput( )
Dismisses the floating keyboard.
Returns: bool
dismissGamepadTextInput
dismissGamepadTextInput( )
Dismisses the full-screen text input dialog.
Returns: bool
filterText
filterText( TextFilteringContext
context, uint64_t
steam_id, string
message )
Argument | Type | Notes |
---|---|---|
context | TextFilteringContext enum | The type of content in the input string. |
steam_id | uint64_t | Steam ID of the input string source; the player who entered the chat text. |
message | string | The input string that should be filtered. |
Filters the provided input message and returns the filtered result. Legally required filtering is always applied. Additional filtering may occur, based on the context and user settings.
Returns: string
Returns the filtered message, even if no filtering is performed.
getAPICallFailureReason
getAPICallFailureReason( )
Used to get the failure reason of a call result.
The primary usage for this function is debugging. The failure reasons are typically out of your control and tend to not be very important. Just keep retrying your API Call until it works.
Returns: string
getAppID
getAppID( )
Gets the App ID of the current process.
Returns: uint32_t
getConnectedUniverse
getConnectedUniverse( )
Gets the uinverse the current client is connected to. Supposed to be for Valve's use only.
Returns: Universe enum
Read more in the official Steamworks SDK documentation Added GodotSteam 4.15
getCurrentBatteryPower
getCurrentBatteryPower( )
Gets the current amount of battery power on the computer.
Returns: int
The current battery power ranging from 0 to 100%. Returns 255 when the user in on AC power.
getImageRGBA
getImageRGBA( int
image_handle )
Argument | Type | Notes |
---|---|---|
image_handle | int | The handle of the image that will be obtained; usually retrieved from an avatar function. |
Gets the image bytes from an image handle.
Prior to calling this you must get the size of the image by calling getImageSize so that you can create your buffer with an appropriate size. You can then allocate your buffer with the width and height as: width * height * 4. The image is provided in RGBA format.
This call can be somewhat expensive as it converts from the compressed type (JPG, PNG, TGA) and provides no internal caching of returned buffer, thus it is highly recommended to only call this once per image handle and cache the result. This function is only used for Steam Avatars and Achievement images and those are not expected to change mid game.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
buffer | PackedByteArray | The image buffer to translate into a texture. |
success | bool | Returns true upon success if the image handle is valid and the buffer was filled out; otherwise, false. |
getImageSize
getImageSize( int
image_handle )
Argument | Type | Notes |
---|---|---|
image_handle | int | The handle of the image that will be obtained; usually retrieved from an avatar function. |
Gets the size of a Steam image handle.
This must be called before calling getImageRGBA to create an appropriately sized buffer that will be filled with the raw image data.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
width | uint32_t | Returns the width of the image. |
height | uint32_t | Returns the height of the image. |
getIPCCallCount
getIPCCallCount( )
Used for perf debugging so you can determine how many IPC (Inter-Process Communication) calls your game makes per frame.
Every IPC call is at minimum a thread context switch if not a process one so you want to rate control how often you do them.
Returns: uint32_t
Returns the number of IPC calls made since the last time this function was called.
getIPCountry
getIPCountry( )
This is looked up via an IP-to-location database.
Returns: string
Returns the 2 digit ISO 3166-1-alpha-2 format country code which client is running in. e.g "US" or "UK".
getIPv6ConnectivityState
getIPv6ConnectivityState( IPv6ConnectivityProtocol
protocol )
Argument | Type | Notes |
---|---|---|
protocol | IPv6ConnectivityProtocol enum | The IPv6 protocol you are getting the state for; typically HTTP or UDP. |
Return what we believe your current ipv6 connectivity to "the internet" is on the specified protocol. This does not tell you if the Steam client is currently connected to Steam via IPv6.
Returns: IPv6ConnectivityState enum
getSecondsSinceAppActive
getSecondsSinceAppActive( )
Returns the number of seconds since the application was active.
Returns: int
getSecondsSinceComputerActive
getSecondsSinceComputerActive( )
Returns the number of seconds since the user last moved the mouse.
Returns: int
getServerRealTime
getServerRealTime( )
Returns the Steam server time in Unix epoch format. (Number of seconds since Jan 1, 1970 UTC).
Returns: int
getSteamUILanguage
getSteamUILanguage( )
Returns the language the steam client is running in.
You probably want getCurrentGameLanguage instead, this should only be used in very special cases.
For a full list of languages see Supported Languages.
Returns: string
initFilterText
initFilterText( )
Initializes text filtering, loading dictionaries for the language the game is running in.
Users can customize the text filter behavior in their Steam Account preferences.
Returns: bool
Returns true if initialization succeeds. False if filtering is unavailable for the game's language, in which case filtetText will act as a passthrough.
isAPICallCompleted
isAPICallCompleted( )
Checks if an API Call is completed. Provides the backend of the CallResult wrapper.
It's generally not recommended that you use this yourself.
Returns: dictionary
Contains the following keys:
Key | Type | Notes |
---|---|---|
completed | bool | Returns true if the API Call is valid and has completed; otherwise, false. |
failed | bool | Returns whether the API call has encountered a failure (true) or not (false). |
isOverlayEnabled
isOverlayEnabled( )
Checks if the Steam Overlay is running & the user can access it.
The overlay process could take a few seconds to start & hook the game process, so this function will initially return false while the overlay is loading.
Returns: bool
isSteamChinaLauncher
isSteamChinaLauncher( )
Returns whether the current launcher is a Steam China launcher. You can cause the client to behave as the Steam China launcher by adding -dev -steamchina
to the command line when running Steam.
Returns: bool
isSteamInBigPictureMode
isSteamInBigPictureMode( )
Checks if Steam & the Steam Overlay are running in Big Picture mode.
Games must be launched through the Steam client to enable the Big Picture overlay. During development, a game can be added as a non-steam game to the developers library to test this feature.
Returns: bool
Returns true if the Big Picture overlay is visible; otherwise, false. This will always return false if your app is not the "game" application type.
isSteamRunningInVR
isSteamRunningInVR( )
Checks if Steam is running in VR mode.
Returns: bool
isSteamRunningOnSteamDeck
isSteamRunningOnSteamDeck( )
Checks if Steam is running on a Steam Deck device.
Returns: bool
isVRHeadsetStreamingEnabled
isVRHeadsetStreamingEnabled( )
Checks if the HMD view will be streamed via Steam In-Home Streaming.
Returns: bool
Returns true if VR is enabled and the HMD view is currently being streamed; otherwise, false.
overlayNeedsPresent
overlayNeedsPresent( )
Checks if the Overlay needs a present. Only required if using event driven render updates.
Typically this call is unneeded if your game has a constantly running frame loop that calls the D3D Present API, or OGL SwapBuffers API every frame as is the case in most games. However, if you have a game that only refreshes the screen on an event driven basis then that can break the overlay, as it uses your Present/SwapBuffers calls to drive it's internal frame loop and it may also need to Present() to the screen any time a notification happens or when the overlay is brought up over the game by a user.
You can use this API to ask the overlay if it currently need a present in that case, and then you can check for this periodically (roughly 33hz is desirable) and make sure you refresh the screen with Present or SwapBuffers to allow the overlay to do it's work.
Returns: bool
Returns true if the overlay needs you to refresh the screen; otherwise, false.
setGameLauncherMode
setGameLauncherMode( bool
mode )
Argument | Type | Notes |
---|---|---|
mode | bool | Whether a launcher is active or not. |
In game launchers that don't have controller support you can call this to have Steam Input translate the controller input into mouse / keyboard to navigate the launcher.
Returns: void
setOverlayNotificationInset
setOverlayNotificationInset( int
horizontal, int
vertical )
Argument | Type | Notes |
---|---|---|
horizontal | int | The horizontal (left-right) distance in pixels from the corner. |
vertical | int | The vertical (up-down) distance in pixels from the corner. |
Sets the inset of the overlay notification from the corner specified by setOverlayNotificationPosition. Integer should be number of pixels.
A value of (0, 0) resets the position into the corner.
This position is per-game and is reset each launch.
Returns: void
setOverlayNotificationPosition
setOverlayNotificationPosition( NotificationPosition
position )
Argument | Type | Notes |
---|---|---|
position | NotificationPosition enum | The corner the notification displays from. |
Set the position where overlay shows notifications.
You can also set the distance from the specified corner by using setOverlayNotificationInset.
This position is per-game and is reset each launch.
Returns: void
setVRHeadsetStreamingEnabled
setVRHeadsetStreamingEnabled( bool
enabled = true )
Argument | Type | Notes |
---|---|---|
enabled | bool | Turns VR HMD Streaming on (true) or off (false); defaults to true. |
Set whether the HMD content will be streamed via Steam In-Home Streaming.
If this is enabled, then the scene in the HMD headset will be streamed, and remote input will not be allowed. Otherwise if this is disabled, then the application window will be streamed instead, and remote input will be allowed. VR games default to enabled unless "VRHeadsetStreaming" "0" is in the extended appinfo for a game.
This is useful for games that have asymmetric multiplayer gameplay.
Returns: void
showFloatingGamepadTextInput
showFloatingGamepadTextInput( FloatingGamepadTextInputMode
input_mode, int
text_field_x_position, int
text_field_y_position, int
text_field_width, int
text_field_height )
Argument | Type | Notes |
---|---|---|
input_mode | FloatingGamepadTextInputMode enum | Selects the keyboard type to use. |
text_field_x_position | int | X coordinate of text field which shouldn't be obscured by the floating keyboard. |
text_field_y_position | int | Y coordinate of text field which shouldn't be obscured by the floating keyboard. |
text_field_width | int | Width of text field which shouldn't be obscured by the floating keyboard. |
text_field_height | int | Height of text field which shouldn't be obscured by the floating keyboard. |
Opens a floating keyboard over the game content and sends OS keyboard keys directly to the game.
The text field position is specified in pixels relative the origin of the game window and is used to position the floating keyboard in a way that doesn't cover the text field.
Returns: bool
Returns true if the floating keyboard was shown; otherwise, false.
showGamepadTextInput
showGamepadTextInput( GamepadTextInputMode
input_mode, GamepadTextInputLineMode
line_input_mode, string
description, uint32_t
max_text, string
preset_text )
Argument | Type | Notes |
---|---|---|
input_mode | GamepadTextInputMode enum | Selects the input mode to use, either Normal or Password (hidden text). |
line_input_mode | GamepadTextInputLineMode enum | Controls whether to use single or multi line input. |
description | string | Sets the description that should inform the user what the input dialog is for. |
max_text | uint32_t | The maximum number of characters that the user can input. |
preset_text | string | Sets the preexisting text which the user can edit. |
Activates the Big Picture text input dialog which only supports gamepad input.
Returns: bool
Returns true if the Big Picture overlay is running; otherwise, false.
startVRDashboard
startVRDashboard( )
Ask SteamUI to create and render its OpenVR dashboard.
Returns: void
Signals
These callbacks require you to setup one of the three callback methods to receive them.
app_resuming_from_suspend
app_resuming_from_suspend
Sent after the device returns from sleep/suspend mode.
Returns
Nothing.
check_file_signature
check_file_signature
Call result for checkFileSignature.
Returns
Key | Type | Notes |
---|---|---|
signature | string | Contains the result of the file signature check. |
filter_text_dictionary_changed
filter_text_dictionary_changed
Sent when the text filtering dictionary has changed languages.
Returns
Key | Type | Notes |
---|---|---|
language | int | Numerical code for the new language. |
floating_gamepad_text_input_dismissed
floating_gamepad_text_input_dismissed
Called when the floating keyboard invoked from showFloatingGamepadTextInput has been closed.
Returns
Nothing.
gamepad_text_input_dismissed
gamepad_text_input_dismissed
Called when the Big Picture gamepad text input has been closed.
Returns
Key | Type | Notes |
---|---|---|
submitted | bool | Returns true if the user entered and accepted text. Otherwise, false if the input was canceled. |
text | string | Contains the text that was submitted. |
app_id | uint32_t | The app ID for the game this text was submitted for. |
ip_country
ip_country
Called when the country of the user changed. The country should be updated with getIPCountry.
Returns
Nothing.
low_power
low_power
Called when running on a laptop and less than 10 minutes of battery is left, and then fires then every minute afterwards.
Returns
Key | Type | Notes |
---|---|---|
power | uint8 | The estimated amount of battery life left in minutes. |
steam_api_call_completed
steam_api_call_completed
Called when a SteamAPICall_t has completed or failed.
Returns
Key | Type | Notes |
---|---|---|
async_call | uint64_t | The handle of the Steam API Call that completed. |
callback | int | This is the callback constant which uniquely identifies the completed callback. |
parameter | uint32_t | The size in bytes of the completed callback. |
steam_shutdown
steam_shutdown
Called when Steam wants to shut down.
Returns
Nothing.
Enums
CheckFileSignature
Results for checkFileSignature.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
CHECK_FILE_SIGNATURE_INVALID_SIGNATURE | k_ECheckFileSignatureInvalidSignature | 0 | The file exists, and the signing tab has been set for this file, but the file is either not signed or the signature does not match. |
CHECK_FILE_SIGNATURE_VALID_SIGNATURE | k_ECheckFileSignatureValidSignature | 1 | The file is signed and the signature is valid. |
CHECK_FILE_SIGNATURE_FILE_NOT_FOUND | k_ECheckFileSignatureFileNotFound | 2 | The file does not exist on disk. |
CHECK_FILE_SIGNATURE_NO_SIGNATURES_FOUND_FOR_THIS_APP | k_ECheckFileSignatureNoSignaturesFoundForThisApp | 3 | This app has not been configured on the signing tab of the partner site to enable this function. |
CHECK_FILE_SIGNATURE_NO_SIGNATURES_FOUND_FOR_THIS_FILE | k_ECheckFileSignatureNoSignaturesFoundForThisFile | 4 | This file is not listed on the signing tab for the partner site. |
GamepadTextInputLineMode
Controls number of allowed lines for the Big Picture gamepad text entry.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
GAMEPAD_TEXT_INPUT_LINE_MODE_SINGLE_LINE | k_EGamepadTextInputLineModeSingleLine | 0 | - |
GAMEPAD_TEXT_INPUT_LINE_MODE_MULTIPLE_LINES | k_EGamepadTextInputLineModeMultipleLines | 1 | - |
GamepadTextInputMode
Input modes for the Big Picture gamepad text entry.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
GAMEPAD_TEXT_INPUT_MODE_NORMAL | k_EGamepadTextInputModeNormal | 0 | - |
GAMEPAD_TEXT_INPUT_MODE_PASSWORD | k_EGamepadTextInputModePassword | 1 | - |
FloatingGamepadTextInputMode
Controls number of allowed lines for the Big Picture gamepad text entry.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
FLOATING_GAMEPAD_TEXT_INPUT_MODE_SINGLE_LINE | k_EFloatingGamepadTextInputModeModeSingleLine | 0 | Enter dismisses the keyboard. |
FLOATING_GAMEPAD_TEXT_INPUT_MODE_MULTIPLE_LINES | k_EFloatingGamepadTextInputModeModeMultipleLines | 1 | User needs to explictly close the keyboard. |
FLOATING_GAMEPAD_TEXT_INPUT_MODE_EMAIL | k_EFloatingGamepadTextInputModeModeEmail | 2 | Keyboard layout is email, enter dismisses the keyboard. |
FLOATING_GAMEPAD_TEXT_INPUT_MODE_NUMERIC | k_EFloatingGamepadTextInputModeModeNumeric | 3 | Keyboard layout is numeric, enter dismisses the keyboard. |
SteamAPICallFailure
Steam API call failure results.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
STEAM_API_CALL_FAILURE_NONE | k_ESteamAPICallFailureNone | -1 | No failure. |
STEAM_API_CALL_FAILURE_STEAM_GONE | k_ESteamAPICallFailureSteamGone | 0 | The local Steam process has gone away. |
STEAM_API_CALL_FAILURE_NETWORK_FAILURE | k_ESteamAPICallFailureNetworkFailure | 1 | The network connection to Steam has been broken or was already broken. steam_server_disconnected callback will be sent around the same time. steam_server_connected will be sent when the client is able to talk to the Steam servers again. |
STEAM_API_CALL_FAILURE_INVALID_HANDLE | k_ESteamAPICallFailureInvalidHandle | 2 | The SteamAPICall_t handle passed in no longer exists. |
STEAM_API_CALL_FAILURE_MISMATCHED_CALLBACK | k_ESteamAPICallFailureMismatchedCallback | 3 | getAPICallResult was called with the wrong callback type for this API call. |
TextFilteringContext
The context where text filtering is being done.
Enumerator | SDK Name | Value | Notes |
---|---|---|---|
TEXT_FILTERING_CONTEXT_UNKNOWN | k_ETextFilteringContextUnknown | 0 | Unknown context. |
TEXT_FILTERING_CONTEXT_GAME_CONTENT | k_ETextFilteringContextGameContent | 1 | Game content, only legally required filtering is performed. |
TEXT_FILTERING_CONTEXT_CHAT | k_ETextFilteringContextChat | 2 | Chat from another player. |
TEXT_FILTERING_CONTEXT_NAME | k_ETextFilteringContextName | 3 | Character or item name. |