Window API documentation

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

Version: beta (1.14.1)

RECORDS
window.event_data	Window event data
window.reserved_area	Window reserved-area data
window.safe_area	Window safe-area data

ENUMS
window.DIMMING	Screen-dimming modes
window.WINDOW_EVENT	Window events

FUNCTIONS
window.get_dim_mode()	get the mode for screen dimming
window.get_display_scale()	get the display scale
window.get_mouse_lock()	get the cursor lock state
window.get_reserved_areas()	get reserved areas
window.get_safe_area()	get the safe area
window.get_size()	get the window size
window.set_dim_mode()	set the mode for screen dimming
window.set_listener()	sets a window event listener
window.set_mouse_lock()	set the locking state for current mouse cursor
window.set_position()	set the position of the window
window.set_size()	set the size of the window
window.set_title()	set the title of the window

Records

window.event_data

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

FIELDS

`[width]`	`integer`	Window width after a resize.
`[height]`	`integer`	Window height after a resize.

window.reserved_area

Window reserved-area data

FIELDS

`x`	`integer`	Left edge in window pixels.
`y`	`integer`	Bottom edge in window pixels.
`width`	`integer`	Rectangle width in window pixels.
`height`	`integer`	Rectangle height in window pixels.

window.safe_area

Window safe-area data

FIELDS

`x`	`integer`	Safe-area x-coordinate.
`y`	`integer`	Safe-area y-coordinate.
`width`	`integer`	Safe-area width.
`height`	`integer`	Safe-area height.
`inset_left`	`integer`	Inset from the left window edge.
`inset_top`	`integer`	Inset from the top window edge.
`inset_right`	`integer`	Inset from the right window edge.
`inset_bottom`	`integer`	Inset from the bottom window edge.

Enums

window.DIMMING

window.DIMMING: integer

Screen-dimming modes

VALUES

`window.DIMMING_OFF`	dimming mode off Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
`window.DIMMING_ON`	dimming mode on Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
`window.DIMMING_UNKNOWN`	dimming mode unknown Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction. This mode indicates that the dim mode can't be determined, or that the platform doesn't support dimming.

window.WINDOW_EVENT

window.WINDOW_EVENT: integer

Window events

VALUES

`window.WINDOW_EVENT_DEICONIFIED`	deiconified window event This event is sent to a window event listener when the game window or app screen is restored after being iconified.
`window.WINDOW_EVENT_FOCUS_GAINED`	focus gained window event This event is sent to a window event listener when the game window or app screen has gained focus. This event is also sent at game startup and the engine gives focus to the game.
`window.WINDOW_EVENT_FOCUS_LOST`	focus lost window event This event is sent to a window event listener when the game window or app screen has lost focus.
`window.WINDOW_EVENT_ICONIFIED`	iconify window event This event is sent to a window event listener when the game window or app screen is iconified (reduced to an application icon in a toolbar, application tray or similar).
`window.WINDOW_EVENT_RESIZED`	resized window event This event is sent to a window event listener when the game window or app screen is resized. On iOS, it is also sent after orientation transitions and safe-area inset changes, even when the size is unchanged. After window.get_reserved_areas has been queried, changes to reserved areas also trigger this event on supported platforms. The current size is passed along in the data field to the event listener.

Functions

window.get_dim_mode()

window.get_dim_mode()→mode:window.DIMMING

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.

PARAMETERS

None

RETURNS

mode window.DIMMING The mode for screen dimming

window.get_display_scale()

window.get_display_scale()→scale:number

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.

PARAMETERS

None

RETURNS

scale number The display scale

window.get_mouse_lock()

window.get_mouse_lock()→state:boolean

This returns the current lock state of the mouse cursor

PARAMETERS

None

RETURNS

state boolean The lock state

window.get_reserved_areas()

window.get_reserved_areas()→areas:window.reserved_area[]

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.

PARAMETERS

None

RETURNS

areas window.reserved_area[] array of window.reserved_area rectangles

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()

window.get_safe_area()→safe_area:window.safe_area

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.

PARAMETERS

None

RETURNS

safe_area window.safe_area safe area data

window.get_size()

window.get_size()→(width:integer, height:integer)

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

PARAMETERS

None

RETURNS

`width`	`integer`	The window width
`height`	`integer`	The window height

window.set_dim_mode()

window.set_dim_mode(mode:window.DIMMING)

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

mode window.DIMMING The mode for screen dimming

window.set_listener()

window.set_listener(callback:fun(self:script_instance, event:window.WINDOW_EVENT, data:window.event_data)|nil)

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

PARAMETERS

callback function( self:script_instance, event:window.WINDOW_EVENT, data:window.event_data)
nil A callback which receives info about window events. Pass an empty function or nil if you no longer wish to receive callbacks.

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()

window.set_mouse_lock(flag:boolean)

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

flag boolean The lock state for the mouse cursor

window.set_position()

window.set_position(x:integer, y:integer)

Sets the window position.

PARAMETERS

`x`	`integer`	Horizontal position of window
`y`	`integer`	Vertical position of window

window.set_size()

window.set_size(width:integer, height:integer)

Sets the window size. Works on desktop platforms only.

PARAMETERS

`width`	`integer`	Width of window
`height`	`integer`	Height of window

window.set_title()

window.set_title(title:string)

Sets the window title. Works on desktop platforms.

PARAMETERS

title string The title, encoded as UTF-8