Window

Namespace: window Language: Lua Type: Defold Lua File: script_window.cpp Source: engine/gamesys/src/gamesys/scripts/script_window.cpp

Functions and constants to access the window, window event listeners and screen dimming.

API

window.DIMMING

Type: ENUM Screen-dimming modes

Members

window.event_data

Type: STRUCT Width and height are present for window.WINDOW_EVENT_RESIZED and absent for other window events.

Members

window.get_dim_mode

Type: FUNCTION Returns the current dimming mode set on a mobile device. The dimming mode specifies whether or not a mobile device should dim the screen after a period without user interaction. On platforms that does not support dimming, window.DIMMING_UNKNOWN is always returned.

Returns

window.get_display_scale

Type: FUNCTION This returns the content scale of the current display. On HTML5, the scale respects display.high_dpi, html5.min_pixel_ratio and html5.max_pixel_ratio. When High DPI is disabled, the scale is 1.

Returns

window.get_mouse_lock

Type: FUNCTION This returns the current lock state of the mouse cursor

Returns

window.get_reserved_areas

Type: FUNCTION Returns an array of active occlusion rectangles intersecting the game window, such as camera cutouts and the Dynamic Island. Each rectangle is clipped to the window and uses a bottom-left origin and pixel units matching window.get_size. These coordinates are independent of GUI adjustment and the project’s logical resolution. Supported on iOS 27.1+ and Android 9 (API level 28)+. On iOS, rectangles include the interaction margins supplied by UIKit. On Android, rectangles describe display cutouts. Folds, system bars, keyboards, and gesture areas are not reported by this API. Unsupported platforms and windows with no reported occlusions return an empty table. An empty result does not guarantee that the whole window is safe; use window.get_safe_area when a safe layout rectangle is needed. Query once during initialization and again following window.WINDOW_EVENT_RESIZED. On supported platforms this event also refreshes reserved areas when their geometry changes without a size change. The returned table is a snapshot and is not modified by subsequent events.

Returns

Examples

local function update_reserved_areas(self)
    self.reserved_areas = window.get_reserved_areas()
end

function init(self)
    update_reserved_areas(self)
    window.set_listener(function(self, event, data)
        if event == window.WINDOW_EVENT_RESIZED then
            update_reserved_areas(self)
        end
    end)
end

window.get_safe_area

Type: FUNCTION This returns the safe area rectangle (x, y, width, height) and the inset values relative to the window edges. On platforms without a safe area, this returns the full window size and zero insets.

Returns

window.get_size

Type: FUNCTION This returns the current window size (width and height).

Returns

window.reserved_area

Type: STRUCT Window reserved-area data

Members

window.safe_area

Type: STRUCT Window safe-area data

Members

window.set_dim_mode

Type: FUNCTION Sets the dimming mode on a mobile device. The dimming mode specifies whether or not a mobile device should dim the screen after a period without user interaction. The dimming mode will only affect the mobile device while the game is in focus on the device, but not when the game is running in the background. This function has no effect on platforms that does not support dimming.

Parameters

window.set_listener

Type: FUNCTION Sets a window event listener. Only one window event listener can be set at a time.

Parameters

Examples

function window_callback(self, event, data)
    if event == window.WINDOW_EVENT_FOCUS_LOST then
        print("window.WINDOW_EVENT_FOCUS_LOST")
    elseif event == window.WINDOW_EVENT_FOCUS_GAINED then
        print("window.WINDOW_EVENT_FOCUS_GAINED")
    elseif event == window.WINDOW_EVENT_ICONIFIED then
        print("window.WINDOW_EVENT_ICONIFIED")
    elseif event == window.WINDOW_EVENT_DEICONIFIED then
        print("window.WINDOW_EVENT_DEICONIFIED")
    elseif event == window.WINDOW_EVENT_RESIZED then
        print("Window resized: ", data.width, data.height)
    end
end

function init(self)
    window.set_listener(window_callback)
end

window.set_mouse_lock

Type: FUNCTION Set the locking state for current mouse cursor on a PC platform. This function locks or unlocks the mouse cursor to the center point of the window. While the cursor is locked, mouse position updates will still be sent to the scripts as usual.

Parameters

window.set_position

Type: FUNCTION Sets the window position.

Parameters

window.set_size

Type: FUNCTION Sets the window size. Works on desktop platforms only.

Parameters

window.set_title

Type: FUNCTION Sets the window title. Works on desktop platforms.

Parameters

window.WINDOW_EVENT

Type: ENUM Window events

Members