Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

sys2 changed

Functions and messages for using system resources, controlling the engine, error handling and debugging.

Functions

sys.deserialize(buffer: string): LuaTable<AnyNotNil, unknown>

This function will raise a Lua error if an error occurs while deserializing the buffer.

// Deserialize a table that was previously serialized:
const my_table = { score: 100, level: 3 };
const buffer = sys.serialize(my_table);
const table = sys.deserialize(buffer);
local buffer = sys.serialize(my_table)
local table = sys.deserialize(buffer)

Parameters

  • buffer: string — buffer to deserialize from

Returns

  • table: LuaTable<AnyNotNil, unknown> — lua table with deserialized data

sys.exists(path: string): boolean

Check if a path exists Good for checking if a file exists before loading a large file

// Load data but return nil if path didn't exist
function load_data(path: string) {
  if (!sys.exists(path)) {
    return undefined;
  }
  return sys.load(path); // returns {} if it failed
}
if not sys.exists(path) then
    return nil
end
return sys.load(path) -- returns {} if it failed

Parameters

  • path: string — path to check

Returns

  • result: boolean — true if the path exists, false otherwise

sys.exit(code: number): void

Terminates the game application and reports the specified code to the OS.

// This example demonstrates how to exit the application when some kind of quit
// message is received (maybe from gui or similar):
export default defineScript({
  on_message(self, message_id, message, sender) {
    if (message_id === hash("quit")) {
      sys.exit(0);
    }
  },
});
function on_message(self, message_id, message, sender)
    if message_id == hash("quit") then
        sys.exit(0)
    end
end

Parameters

  • code: number — exit code to report to the OS, 0 means clean exit

sys.get_application_info(app_string: string): sys.ApplicationInfo

Returns a table with application information for the requested app. On iOS, the app_string is an url scheme for the app that is queried. Your game needs to list the schemes that are queried in an LSApplicationQueriesSchemes array in a custom "Info.plist". On Android, the app_string is the package identifier for the app.

Check if twitter is installed:

const sysinfo = sys.get_sys_info();
let twitter: { installed?: boolean } = {};

if (sysinfo.system_name === "Android") {
  twitter = sys.get_application_info("com.twitter.android");
} else if (sysinfo.system_name === "iPhone OS") {
  twitter = sys.get_application_info("twitter:");
}

if (twitter.installed) {
  // twitter is installed!
}
sysinfo = sys.get_sys_info()
twitter = {}

if sysinfo.system_name == "Android" then
  twitter = sys.get_application_info("com.twitter.android")
elseif sysinfo.system_name == "iPhone OS" then
  twitter = sys.get_application_info("twitter:")
end

if twitter.installed then
  -- twitter is installed!
end

Info.plist for the iOS app needs to list the schemes that are queried:

// ...
// <key>LSApplicationQueriesSchemes</key>
//  <array>
//    <string>twitter</string>
//  </array>
// ...
...
<key>LSApplicationQueriesSchemes</key>
 <array>
   <string>twitter</string>
 </array>
...

Parameters

  • app_string: string — platform specific string with application package or query, see above for details.

Returns

sys.get_application_path(): string

The path from which the application is run. This function will raise a Lua error if unable to get the application support path.

// Find a path where we can store data (the example path is on the macOS platform):
// macOS: /Applications/my_game.app
const application_path = sys.get_application_path();
print(application_path); //> /Applications/my_game.app

// Windows: C:\Program Files\my_game\my_game.exe
print(application_path); //> C:\Program Files\my_game

// Linux: /home/foobar/my_game/my_game
print(application_path); //> /home/foobar/my_game

// Android package name: com.foobar.my_game
print(application_path); //> /data/user/0/com.foobar.my_game

// iOS: my_game.app
print(application_path); //> /var/containers/Bundle/Applications/123456AB-78CD-90DE-12345678ABCD/my_game.app

// HTML5: http://www.foobar.com/my_game/
print(application_path); //> http://www.foobar.com/my_game
-- macOS: /Applications/my_game.app
local application_path = sys.get_application_path()
print(application_path) --> /Applications/my_game.app

-- Windows: C:\Program Files\my_game\my_game.exe
print(application_path) --> C:\Program Files\my_game

-- Linux: /home/foobar/my_game/my_game
print(application_path) --> /home/foobar/my_game

-- Android package name: com.foobar.my_game
print(application_path) --> /data/user/0/com.foobar.my_game

-- iOS: my_game.app
print(application_path) --> /var/containers/Bundle/Applications/123456AB-78CD-90DE-12345678ABCD/my_game.app

-- HTML5: http://www.foobar.com/my_game/
print(application_path) --> http://www.foobar.com/my_game

Returns

  • path: string — path to application executable

sys.get_config_boolean(key: string, default_value?: boolean): boolean

Get boolean config value from the game.project configuration file with optional default value

// Get user config value
const vsync = sys.get_config_boolean("display.vsync", false);
local vsync = sys.get_config_boolean("display.vsync", false)

Parameters

  • key: string — key to get value for. The syntax is SECTION.KEY
  • default_value?: boolean — (optional) default value to return if the value does not exist

Returns

  • value: boolean — config value as a boolean. default_value if the config key does not exist. false if no default value was supplied.

sys.get_config_int(2 overloads): number

Get integer config value from the game.project configuration file with optional default value

  1. (key: string)

  2. (key: string, default_value: number)

    Parameters

    • key: string — key to get value for. The syntax is SECTION.KEY
    • default_value: number — (optional) default value to return if the value does not exist

    Returns

    • value: number — config value as an integer. default_value if the config key does not exist. 0 if no default value was supplied.

Get user config value

const speed = sys.get_config_int("my_game.speed", 20); // with default value
local speed = sys.get_config_int("my_game.speed", 20) -- with default value
const testmode = sys.get_config_int("my_game.testmode"); // without default value
if (testmode !== undefined) {
  // do stuff
}
local testmode = sys.get_config_int("my_game.testmode") -- without default value
if testmode ~= nil then
    -- do stuff
end

sys.get_config_number(2 overloads): number

Get number config value from the game.project configuration file with optional default value

  1. (key: string)

  2. (key: string, default_value: number)

    Parameters

    • key: string — key to get value for. The syntax is SECTION.KEY
    • default_value: number — (optional) default value to return if the value does not exist

    Returns

    • value: number — config value as an number. default_value if the config key does not exist. 0 if no default value was supplied.
// Get user config value
const speed = sys.get_config_number("my_game.speed", 20.0);
local speed = sys.get_config_number("my_game.speed", 20.0)

sys.get_config_string(2 overloads)C

  1. (key: string): string | undefined

    Get string config value from the game.project configuration file, or nil when the key does not exist.

  2. (key: string, default_value: string): string

    Get string config value from the game.project configuration file with a default value.

    Parameters

    • key: string — key to get value for. The syntax is SECTION.KEY
    • default_value: string — (optional) default value to return if the value does not exist

    Returns

    • value: string — config value as a string. default_value if the config key does not exist. nil if no default value was supplied.

Get user config value

const text = sys.get_config_string("my_game.text", "default text");
local text = sys.get_config_string("my_game.text", "default text"))

Start the engine with a bootstrap config override and add a custom config value

// $ dmengine --config=bootstrap.main_collection=/mytest.collectionc --config=mygame.testmode=1
$ dmengine --config=bootstrap.main_collection=/mytest.collectionc --config=mygame.testmode=1

Read the custom config value from the command line

const testmode = sys.get_config_int("mygame.testmode");
local testmode = sys.get_config_int("mygame.testmode")

sys.get_connectivity(): sys.Network

Returns the current network connectivity status on mobile platforms. On desktop, this function always return sys.NETWORK_CONNECTED.

// Check if we are connected through a cellular connection
if (sys.NETWORK_CONNECTED_CELLULAR === sys.get_connectivity()) {
  print("Connected via cellular, avoid downloading big files!");
}
if (sys.NETWORK_CONNECTED_CELLULAR == sys.get_connectivity()) then
  print("Connected via cellular, avoid downloading big files!")
end

Returns

  • status: sys.Network — network connectivity status

sys.get_engine_info(): sys.EngineInfo

Returns a table with engine information.

// How to retrieve engine information:
// Update version text label so our testers know what version we're running
const engine_info = sys.get_engine_info();
const version_str = `Defold ${engine_info.version}\n${engine_info.version_sha1}`;
gui.set_text(gui.get_node("version"), version_str);
-- Update version text label so our testers know what version we're running
local engine_info = sys.get_engine_info()
local version_str = "Defold " .. engine_info.version .. "\n" .. engine_info.version_sha1
gui.set_text(gui.get_node("version"), version_str)

Returns

sys.get_host_path(filename: string): string

Create a path to the host device for unit testing Useful for saving logs etc during development

Save data on the host

const mytable = { score: 100, level: 3 };
const host_path = sys.get_host_path("logs/test.txt");
sys.save(host_path, mytable);
local host_path = sys.get_host_path("logs/test.txt")
sys.save(host_path, mytable)

Load data from the host

const host_path = sys.get_host_path("logs/test.txt");
const table = sys.load(host_path);
local host_path = sys.get_host_path("logs/test.txt")
local table = sys.load(host_path)

Parameters

  • filename: string — file to read from

Returns

  • host_path: string — the path prefixed with the proper host mount

sys.get_ifaddrs(): sys.InterfaceInfo[]

Returns an array of tables with information on network interfaces.

// How to get the IP address of interface "en0":
const ifaddrs = sys.get_ifaddrs();
for (const iface of ifaddrs) {
  if (iface.name === "en0") {
    const ip = iface.address;
  }
}
ifaddrs = sys.get_ifaddrs()
for _,interface in ipairs(ifaddrs) do
  if interface.name == "en0" then
    local ip = interface.address
  end
end

Returns

sys.get_save_file(application_id: string, file_name: string): string

The save-file path is operating system specific and is typically located under the user's home directory. This function will raise a Lua error if unable to get the save file path.

// Find a path where we can store data:
const my_file_path = sys.get_save_file("my_game", "my_file");
// macOS: /Users/foobar/Library/Application Support/my_game/my_file
print(my_file_path); //> /Users/foobar/Library/Application Support/my_game/my_file

// Windows: C:\Users\foobar\AppData\Roaming\my_game\my_file
print(my_file_path); //> C:\Users\foobar\AppData\Roaming\my_game\my_file

// Linux: $XDG_DATA_HOME/my_game/my_file or /home/foobar/.my_game/my_file
// Linux: Defaults to /home/foobar/.local/share/my_game/my_file if neither exist.
print(my_file_path); //> /home/foobar/.local/share/my_game/my_file

// Android package name: com.foobar.packagename
print(my_file_path); //> /data/data/0/com.foobar.packagename/files/my_file

// iOS: my_game.app
print(my_file_path); //> /var/mobile/Containers/Data/Application/123456AB-78CD-90DE-12345678ABCD/my_game/my_file

// HTML5 path inside the IndexedDB: /data/.my_game/my_file or /.my_game/my_file
print(my_file_path); //> /data/.my_game/my_file
local my_file_path = sys.get_save_file("my_game", "my_file")
-- macOS: /Users/foobar/Library/Application Support/my_game/my_file
print(my_file_path) --> /Users/foobar/Library/Application Support/my_game/my_file

-- Windows: C:\Users\foobar\AppData\Roaming\my_game\my_file
print(my_file_path) --> C:\Users\foobar\AppData\Roaming\my_game\my_file

-- Linux: $XDG_DATA_HOME/my_game/my_file or /home/foobar/.my_game/my_file
-- Linux: Defaults to /home/foobar/.local/share/my_game/my_file if neither exist.
print(my_file_path) --> /home/foobar/.local/share/my_game/my_file

-- Android package name: com.foobar.packagename
print(my_file_path) --> /data/data/0/com.foobar.packagename/files/my_file

-- iOS: my_game.app
print(my_file_path) --> /var/mobile/Containers/Data/Application/123456AB-78CD-90DE-12345678ABCD/my_game/my_file

-- HTML5 path inside the IndexedDB: /data/.my_game/my_file or /.my_game/my_file
print(my_file_path) --> /data/.my_game/my_file

Parameters

  • application_id: string — user defined id of the application, which helps define the location of the save-file
  • file_name: string — file-name to get path for

Returns

  • path: string — path to save-file

sys.get_sys_info(2 overloads): sys.SysInfo

Returns a table with system information.

  1. ()

  2. (options: sys.SysInfoOptions)

    Parameters

    Returns

// How to get system information:
const info = sys.get_sys_info();
if (info.system_name === "HTML5") {
  // We are running in a browser.
}
local info = sys.get_sys_info()
if info.system_name == "HTML5" then
  -- We are running in a browser.
end

sys.load(filename: string): LuaTable<AnyNotNil, unknown>

If the file exists, it must have been created by sys.save to be loaded. This function will raise a Lua error if an error occurs while loading the file.

// Load data that was previously saved, e.g. an earlier game session:
const my_file_path = sys.get_save_file("my_game", "my_file");
const my_table = sys.load(my_file_path);
if (!next(my_table)) {
  // empty table
}
local my_file_path = sys.get_save_file("my_game", "my_file")
local my_table = sys.load(my_file_path)
if not next(my_table) then
  -- empty table
end

Parameters

  • filename: string — file to read from

Returns

  • loaded: LuaTable<AnyNotNil, unknown> — lua table, which is empty if the file could not be found

sys.load_buffer(path: string): Opaque<"buffer"> & { length: LuaLengthMethod<number> }

The sys.load_buffer function will first try to load the resource from any of the mounted resource locations and return the data if any matching entries found. If not, the path will be tried as is from the primary disk on the device. In order for the engine to include custom resources in the build process, you need to specify them in the "custom_resources" key in your "game.project" settings file. You can specify single resource files or directories. If a directory is included in the resource list, all files and directories in that directory is recursively included: For example "main/data/,assets/level_data.json".

Load binary data from a custom project resource:

const my_buffer = sys.load_buffer("/assets/my_level_data.bin");
const data_str = buffer.get_bytes(my_buffer, "data");
const has_my_header = data_str.slice(0, 6) === "D3F0LD";
local my_buffer = sys.load_buffer("/assets/my_level_data.bin")
local data_str = buffer.get_bytes(my_buffer, "data")
local has_my_header = string.sub(data_str,1,6) == "D3F0LD"

Load binary data from non-custom resource files on disk:

const asset_1 = sys.load_buffer("folder_next_to_binary/my_level_asset.txt");
const asset_2 = sys.load_buffer("/my/absolute/path");
local asset_1 = sys.load_buffer("folder_next_to_binary/my_level_asset.txt")
local asset_2 = sys.load_buffer("/my/absolute/path")

Parameters

  • path: string — the path to load the buffer from

Returns

  • buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> } — the buffer with data

sys.load_buffer_async(path: string, status_callback: (self: unknown, request_id: number, result: sys.LoadBufferResult) => void): number

The sys.load_buffer function will first try to load the resource from any of the mounted resource locations and return the data if any matching entries found. If not, the path will be tried as is from the primary disk on the device. In order for the engine to include custom resources in the build process, you need to specify them in the "custom_resources" key in your "game.project" settings file. You can specify single resource files or directories. If a directory is included in the resource list, all files and directories in that directory is recursively included: For example "main/data/,assets/level_data.json". Note that issuing multiple requests of the same resource will yield individual buffers per request. There is no implicit caching of the buffers based on request path.

Load binary data from a custom project resource and update a texture resource:

// Load binary data from a custom project resource and update a texture resource:
function my_callback(self: unknown, request_id: number, result: sys.LoadBufferResult) {
  const format = graphics.TEXTURE_FORMAT_RGBA;
  if (result.status === sys.REQUEST_STATUS_FINISHED && result.buffer !== undefined && format !== undefined) {
    resource.set_texture("/my_texture", { type: graphics.TEXTURE_TYPE_2D, width: 128, height: 128, format }, result.buffer);
  }
}

const my_request = sys.load_buffer_async("/assets/my_level_data.bin", my_callback);
function my_callback(self, request_id, result)
  if result.status == sys.REQUEST_STATUS_FINISHED then
     resource.set_texture("/my_texture", { ... }, result.buffer)
  end
end

local my_request = sys.load_buffer_async("/assets/my_level_data.bin", my_callback)

Load binary data from non-custom resource files on disk:

// Load binary data from non-custom resource files on disk:
function my_callback(self: unknown, request_id: number, result: sys.LoadBufferResult) {
  const { first_request, second_request } = self as { first_request: number; second_request: number };
  if (result.status !== sys.REQUEST_STATUS_FINISHED) {
    // uh oh! File could not be found, do something graceful
  } else if (request_id === first_request) {
    // result.buffer contains data from my_level_asset.bin
  } else if (request_id === second_request) {
    // result.buffer contains data from 'my_level.bin'
  }
}

export default defineScript({
  init() {
    return {
      first_request: sys.load_buffer_async("folder_next_to_binary/my_level_asset.bin", my_callback),
      second_request: sys.load_buffer_async("/some_absolute_path/my_level.bin", my_callback),
    };
  },
});
function my_callback(self, request_id, result)
  if result.status ~= sys.REQUEST_STATUS_FINISHED then
    -- uh oh! File could not be found, do something graceful
  elseif request_id == self.first_request then
    -- result.buffer contains data from my_level_asset.bin
  elseif request_id == self.second_request then
    -- result.buffer contains data from 'my_level.bin'
  end
end

function init(self)
  self.first_request = sys.load_buffer_async("folder_next_to_binary/my_level_asset.bin", my_callback)
  self.second_request = sys.load_buffer_async("/some_absolute_path/my_level.bin", my_callback)
end

Parameters

  • path: string — the path to load the buffer from
  • status_callback: (self: unknown, request_id: number, result: sys.LoadBufferResult) => void — callback invoked when the request completes or fails

Returns

  • handle: number — a handle to the request

sys.load_resource(filename: string): LuaMultiReturn<[string | undefined, string | undefined]>

Loads a custom resource. Specify the full filename of the resource that you want to load. When loaded, the file data is returned as a string. If loading fails, the function returns nil plus the error message. In order for the engine to include custom resources in the build process, you need to specify them in the "custom_resources" key in your "game.project" settings file. You can specify single resource files or directories. If a directory is included in the resource list, all files and directories in that directory is recursively included: For example "main/data/,assets/level_data.json".

// Load level data into a string
const [data, error] = sys.load_resource("/assets/level_data.json");
// Decode json string to a table
if (data) {
  const data_table = json.decode(data);
  pprint(data_table);
} else {
  print(error);
}
-- Load level data into a string
local data, error = sys.load_resource("/assets/level_data.json")
-- Decode json string to a Lua table
if data then
  local data_table = json.decode(data)
  pprint(data_table)
else
  print(error)
end

Parameters

  • filename: string — resource to load, full path

Returns

  • data: string | undefined — loaded data, or nil if the resource could not be loaded
  • error: string | undefined — the error message, or nil if no error occurred

sys.open_url(2 overloads): boolean

Open URL in default application, typically a browser

  1. (url: string)

  2. (url: string, attributes: sys.OpenUrlAttributes)

    Parameters

    Returns

    • success: boolean — a boolean indicating if the url could be opened or not
// Open an URL:
const success = sys.open_url("http://www.defold.com", { target: "_blank" });
if (!success) {
  // could not open the url...
}
local success = sys.open_url("http://www.defold.com", {target = "_blank"})
if not success then
  -- could not open the url...
end

sys.reboot(arg1?: string, arg2?: string, arg3?: string, arg4?: string, arg5?: string, arg6?: string, arg7?: string, arg8?: string): voidC

  • Signature changed in Defold 1.14.1 — before: (arg1?: string, arg2?: string, arg3?: string, arg4?: string, arg5?: string, arg6?: string)

Reboots the game engine with a specified set of arguments. Arguments will be translated into command line arguments. Calling reboot function is equivalent to starting the engine with the same arguments. On startup the engine reads configuration from "game.project" in the project root.

// How to reboot engine with a specific bootstrap collection.
const arg1 = "--config=bootstrap.main_collection=/my.collectionc";
const arg2 = "build/game.projectc";
sys.reboot(arg1, arg2);
local arg1 = '--config=bootstrap.main_collection=/my.collectionc'
local arg2 = 'build/game.projectc'
sys.reboot(arg1, arg2)

Parameters

  • arg1?: string — argument 1
  • arg2?: string — argument 2
  • arg3?: string — argument 3
  • arg4?: string — argument 4
  • arg5?: string — argument 5
  • arg6?: string — argument 6
  • arg7?: string — argument 7
  • arg8?: string — argument 8

sys.save(filename: string, table: LuaPairsIterable<string | number | Hash, unknown> | (PlainTable & { readonly __tstlIterable?: never }) | readonly unknown[]): boolean

The table can later be loaded by sys.load. Use sys.get_save_file to obtain a valid location for the file. Internally, this function uses a workspace buffer sized output file sized 512kb. This size reflects the output file size which must not exceed this limit. Additionally, the total number of rows that any one table may contain is limited to 65536 (i.e. a 16 bit range). When tables are used to represent arrays, the values of keys are permitted to fall within a 32 bit range, supporting sparse arrays, however the limit on the total number of rows remains in effect. This function will raise a Lua error if an error occurs while saving the table.

// Save data:
const my_table = [];
my_table.push("my_value");
const my_file_path = sys.get_save_file("my_game", "my_file");
sys.save(my_file_path, my_table);
local my_table = {}
table.insert(my_table, "my_value")
local my_file_path = sys.get_save_file("my_game", "my_file")
sys.save(my_file_path, my_table)

Parameters

  • filename: string — file to write to
  • table: LuaPairsIterable<string | number | Hash, unknown> | (PlainTable & { readonly __tstlIterable?: never }) | readonly unknown[] — lua table to save

sys.serialize(table: LuaPairsIterable<string | number | Hash, unknown> | (PlainTable & { readonly __tstlIterable?: never }) | readonly unknown[]): string

The buffer can later deserialized by sys.deserialize. This function has all the same limitations as sys.save. This function will raise a Lua error if an error occurs while serializing the table.

// Serialize table:
const my_table = [];
my_table.push("my_value");
const buffer = sys.serialize(my_table);
local my_table = {}
table.insert(my_table, "my_value")
local buffer = sys.serialize(my_table)

Parameters

  • table: LuaPairsIterable<string | number | Hash, unknown> | (PlainTable & { readonly __tstlIterable?: never }) | readonly unknown[] — lua table to serialize

Returns

  • buffer: string — serialized data buffer

sys.set_connectivity_host(host: string): void

Sets the host that is used to check for network connectivity against.

sys.set_connectivity_host("www.google.com");
sys.set_connectivity_host("www.google.com")

Parameters

  • host: string — hostname to check against

sys.set_engine_throttle(2 overloads): void

  1. (enable: false)

    Disables engine throttling.

  2. (enable: boolean, cooldown: number)

    Enables engine throttling. The engine reads cooldown whenever enable is true.

    Parameters

    • enable: boolean — true if throttling should be enabled
    • cooldown: number — the time period to do update + render for (seconds)

Disable throttling

sys.set_engine_throttle(false);
sys.set_engine_throttle(false)

Enable throttling

sys.set_engine_throttle(true, 1.5);
sys.set_engine_throttle(true, 1.5)

sys.set_error_handler(error_handler: (source: string, message: string, traceback: string) => void): void

Set the Lua error handler function. The error handler is a function which is called whenever a lua runtime error occurs.

function boom() {
  return 10 + "string";
}

export default defineScript({
  init() {
    // Install error handler that just prints the errors
    sys.set_error_handler((source, message, traceback) => {
      print(source); //> lua
      print(message); //> main/my.script:10: attempt to perform arithmetic on a string value
      print(traceback); //> stack traceback:
      //>         main/test.script:10: in function 'boom'
      //>         main/test.script:15: in function <main/my.script:13>
    });
    boom();
  },
});
local function my_error_handler(source, message, traceback)
  print(source)    --> lua
  print(message)   --> main/my.script:10: attempt to perform arithmetic on a string value
  print(traceback) --> stack traceback:
                   -->         main/test.script:10: in function 'boom'
                   -->         main/test.script:15: in function <main/my.script:13>
end

local function boom()
  return 10 + "string"
end

function init(self)
  sys.set_error_handler(my_error_handler)
  boom()
end

Parameters

  • error_handler: (source: string, message: string, traceback: string) => void — the function to be called on error source string The runtime context of the error. Currently, this is always "lua". message string The source file, line number and error message. traceback string The stack traceback.

sys.set_render_enabled(enable: boolean): void

Disables rendering

// Disable rendering
sys.set_render_enabled(false);
sys.set_render_enable(false)

Parameters

  • enable: boolean — true if throttling should be enabled

sys.set_update_frequency(frequency: number): void

Set game update-frequency (frame cap). This option is equivalent to display.update_frequency in the "game.project" settings but set at run-time. On platforms where Defold owns the application loop, a positive value uses timer pacing and requests a swap interval of 0 to avoid an additional vsync wait where supported. Setting the frequency to 0 restores the requested swap interval and uses variable-rate updates. Platform-owned loops, such as HTML5 and iOS, retain their platform scheduling and presentation behavior. There is no guarantee that the frame cap will be achieved depending on platform and hardware constraints. With engine-side timer pacing, the update dt can be shortened or enlarged to account for elapsed time; the frame cap does not guarantee a constant dt. Elapsed time beyond max(engine.max_time_step, 1 / frequency) is discarded, so accumulated dt can trail wall-clock time after hitches. An intentional fixed interval longer than engine.max_time_step is allowed. This setting is separate from the fixed_update() timestep.

// Setting the update frequency to 60 frames per second
sys.set_update_frequency(60);
sys.set_update_frequency(60)

Parameters

  • frequency: number — target frequency in hertz. 0 selects a variable frame rate; negative values are treated as 0.

sys.set_vsync_swap_interval(swap_interval: number): void

Request a presentation interval relative to vertical blanks (v-blank). 0 requests disabling vsync and 1 requests presenting every refresh (the default). OpenGL may support larger intervals, such as 2 for every other refresh. Vulkan and Metal treat any nonzero interval as enabling vsync; DX12 clamps intervals to the supported range 0 through 4. Actual behavior depends on the backend, platform, and driver. On platforms where Defold owns the application loop, a positive display.update_frequency or a positive value set by sys.set_update_frequency() uses timer pacing and requests a swap interval of 0. The requested swap interval is retained and applied again when the update frequency is set to 0. This setting may be overridden by driver settings.

// Setting the swap interval to swap every v-blank
sys.set_vsync_swap_interval(1);
sys.set_vsync_swap_interval(1)

Parameters

  • swap_interval: number — target swap interval.

Constants

sys.NETWORK_CONNECTED: number & { readonly __brand: "sys.NETWORK_CONNECTED" }

Connected through Wi-Fi or another non-cellular network.

sys.NETWORK_CONNECTED_CELLULAR: number & { readonly __brand: "sys.NETWORK_CONNECTED_CELLULAR" }

Connected through a cellular network.

sys.NETWORK_DISCONNECTED: number & { readonly __brand: "sys.NETWORK_DISCONNECTED" }

No network connection was found.

sys.REQUEST_STATUS_ERROR_IO_ERROR: number & { readonly __brand: "sys.REQUEST_STATUS_ERROR_IO_ERROR" }

An I/O error occurred.

sys.REQUEST_STATUS_ERROR_NOT_FOUND: number & { readonly __brand: "sys.REQUEST_STATUS_ERROR_NOT_FOUND" }

The requested resource was not found.

sys.REQUEST_STATUS_FINISHED: number & { readonly __brand: "sys.REQUEST_STATUS_FINISHED" }

The request completed successfully.

Types

interface sys.ApplicationInfo { installed: boolean; }

interface sys.EngineInfo { version: string; version_sha1: string; is_debug: boolean; }

interface sys.InterfaceInfo { name: string; address?: string; mac?: string; up: boolean; running: boolean; family?: "ipv4" | "ipv6"; }

interface sys.LoadBufferResult { status: sys.RequestStatus; buffer?: Opaque<"buffer"> & { length: LuaLengthMethod<number> }; }

type sys.Network = typeof sys.NETWORK_CONNECTED | typeof sys.NETWORK_CONNECTED_CELLULAR | typeof sys.NETWORK_DISCONNECTED

interface sys.OpenUrlAttributes { target?: string; }

type sys.RequestStatus = typeof sys.REQUEST_STATUS_ERROR_IO_ERROR | typeof sys.REQUEST_STATUS_ERROR_NOT_FOUND | typeof sys.REQUEST_STATUS_FINISHED

interface sys.SysInfo { device_model: string; manufacturer: string; system_name: string; system_version: string; api_version: string; language: string; device_language: string; territory: string; gmt_offset: number; device_ident: string; user_agent: string; }

interface sys.SysInfoOptions { ignore_secure?: boolean; }

On this page

Functionssys.deserialize(buffer: string): LuaTable<AnyNotNil, unknown>sys.exists(path: string): booleansys.exit(code: number): voidsys.get_application_info(app_string: string): sys.ApplicationInfosys.get_application_path(): stringsys.get_config_boolean(key: string, default_value?: boolean): booleansys.get_config_int(2 overloads): numbersys.get_config_number(2 overloads): numbersys.get_config_string(2 overloads)Csys.get_connectivity(): sys.Networksys.get_engine_info(): sys.EngineInfosys.get_host_path(filename: string): stringsys.get_ifaddrs(): sys.InterfaceInfo[]sys.get_save_file(application_id: string, file_name: string): stringsys.get_sys_info(2 overloads): sys.SysInfosys.load(filename: string): LuaTable<AnyNotNil, unknown>sys.load_buffer(path: string): Opaque<"buffer"> & { length: LuaLengthMethod<number> }sys.load_buffer_async(path: string, status_callback: (self: unknown, request_id: number, result: sys.LoadBufferResult) => void): numbersys.load_resource(filename: string): LuaMultiReturn<[string | undefined, string | undefined]>sys.open_url(2 overloads): booleansys.reboot(arg1?: string, arg2?: string, arg3?: string, arg4?: string, arg5?: string, arg6?: string, arg7?: string, arg8?: string): voidCsys.save(filename: string, table: LuaPairsIterable<string | number | Hash, unknown> | (PlainTable & { readonly __tstlIterable?: never }) | readonly unknown[]): booleansys.serialize(table: LuaPairsIterable<string | number | Hash, unknown> | (PlainTable & { readonly __tstlIterable?: never }) | readonly unknown[]): stringsys.set_connectivity_host(host: string): voidsys.set_engine_throttle(2 overloads): voidsys.set_error_handler(error_handler: (source: string, message: string, traceback: string) => void): voidsys.set_render_enabled(enable: boolean): voidsys.set_update_frequency(frequency: number): voidsys.set_vsync_swap_interval(swap_interval: number): voidConstantssys.NETWORK_CONNECTED: number & { readonly __brand: "sys.NETWORK_CONNECTED" }sys.NETWORK_CONNECTED_CELLULAR: number & { readonly __brand: "sys.NETWORK_CONNECTED_CELLULAR" }sys.NETWORK_DISCONNECTED: number & { readonly __brand: "sys.NETWORK_DISCONNECTED" }sys.REQUEST_STATUS_ERROR_IO_ERROR: number & { readonly __brand: "sys.REQUEST_STATUS_ERROR_IO_ERROR" }sys.REQUEST_STATUS_ERROR_NOT_FOUND: number & { readonly __brand: "sys.REQUEST_STATUS_ERROR_NOT_FOUND" }sys.REQUEST_STATUS_FINISHED: number & { readonly __brand: "sys.REQUEST_STATUS_FINISHED" }Typesinterface sys.ApplicationInfo { installed: boolean; }interface sys.EngineInfo { version: string; version_sha1: string; is_debug: boolean; }interface sys.InterfaceInfo { name: string; address?: string; mac?: string; up: boolean; running: boolean; family?: "ipv4" | "ipv6"; }interface sys.LoadBufferResult { status: sys.RequestStatus; buffer?: Opaque<"buffer"> & { length: LuaLengthMethod<number> }; }type sys.Network = typeof sys.NETWORK_CONNECTED | typeof sys.NETWORK_CONNECTED_CELLULAR | typeof sys.NETWORK_DISCONNECTEDinterface sys.OpenUrlAttributes { target?: string; }type sys.RequestStatus = typeof sys.REQUEST_STATUS_ERROR_IO_ERROR | typeof sys.REQUEST_STATUS_ERROR_NOT_FOUND | typeof sys.REQUEST_STATUS_FINISHEDinterface sys.SysInfo { device_model: string; manufacturer: string; system_name: string; system_version: string; api_version: string; language: string; device_language: string; territory: string; gmt_offset: number; device_ident: string; user_agent: string; }interface sys.SysInfoOptions { ignore_secure?: boolean; }