System API documentation

Version: stable

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

Functions

sys.exit()

sys.exit(code)

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

PARAMETERS

EXAMPLES

This examples demonstrates how to exit the application when some kind of quit messages is received (maybe from gui or similar):

function on_message(self, message_id, message, sender)
    if message_id == hash("quit") then
        sys.exit(0)
    end
end

sys.get_application_info()

sys.get_application_info(app_string)

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.

PARAMETERS

RETURNS

EXAMPLES

Check if 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>
...

sys.get_application_path()

sys.get_application_path()

The path from which the application is run.

PARAMETERS

RETURNS

EXAMPLES

Find a path where we can store data (the example path is on the macOS platform):

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

sys.get_config()

sys.get_config(key)

Get config value from the game.project configuration file.

In addition to the project file, configuration values can also be passed to the runtime as command line arguments with the --config argument.

PARAMETERS

RETURNS

EXAMPLES

Get display width

local width = tonumber(sys.get_config("display.width"))

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

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

Set and read a custom config value

local testmode = tonumber(sys.get_config("mygame.testmode"))

sys.get_config()

sys.get_config(key,default_value)

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

PARAMETERS

RETURNS

EXAMPLES

Get user config value

local speed = tonumber(sys.get_config("my_game.speed", "10.23"))

sys.get_connectivity()

sys.get_connectivity()

Returns the current network connectivity status on mobile platforms.

On desktop, this function always return sys.NETWORK_CONNECTED.

PARAMETERS

RETURNS

EXAMPLES

Check if we are connected through a cellular connection

if (sys.NETWORK_CONNECTED_CELLULAR == sys.get_connectivity()) then
  print("Connected via cellular, avoid downloading big files!")
end

sys.get_engine_info()

sys.get_engine_info()

Returns a table with engine information.

PARAMETERS

RETURNS

EXAMPLES

How to retrieve engine information:

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

sys.get_ifaddrs()

sys.get_ifaddrs()

Returns an array of tables with information on network interfaces.

PARAMETERS

RETURNS

EXAMPLES

How to get the IP address of interface "en0":

ifaddrs = sys.get_ifaddrs()
for _,interface in ipairs(ifaddrs) do
  if interface.name == "en0" then
    local ip = interface.address
  end
end

sys.get_save_file()

sys.get_save_file(application_id,file_name)

The save-file path is operating system specific and is typically located under the user's home directory.

PARAMETERS

RETURNS

EXAMPLES

Find a path where we can store data (the example path is on the macOS platform):

local my_file_path = sys.get_save_file("my_game", "my_file")
print(my_file_path) --> /Users/my_users/Library/Application Support/my_game/my_file

sys.get_sys_info()

sys.get_sys_info()

Returns a table with system information.

PARAMETERS

RETURNS

EXAMPLES

How to get system information:

local info = sys.get_sys_info()
if info.system_name == "HTML5" then
  -- We are running in a browser.
end

sys.load()

sys.load(filename)

If the file exists, it must have been created by sys.save to be loaded.

PARAMETERS

RETURNS

EXAMPLES

Load data that was previously saved, e.g. an earlier game session:

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

sys.load_resource()

sys.load_resource(filename)

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".

PARAMETERS

RETURNS

EXAMPLES

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

sys.open_url()

sys.open_url(url)

Open URL in default application, typically a browser

PARAMETERS

RETURNS

EXAMPLES

Open an URL:

local success = sys.open_url("http://www.defold.com")
if not success then
  -- could not open the url...
end

sys.reboot()

sys.reboot(arg1,arg2,arg3,arg4,arg5,arg6)

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.

PARAMETERS

EXAMPLES

How to reboot engine with a specific bootstrap collection.

local arg1 = '--config=bootstrap.main_collection=/my.collectionc'
local arg2 = 'build/default/game.projectc'
sys.reboot(arg1, arg2)

sys.save()

sys.save(filename,table)

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.

PARAMETERS

RETURNS

EXAMPLES

Save data:

local my_table = {}
table.insert(my_table, "my_value")
local my_file_path = sys.get_save_file("my_game", "my_file")
if not sys.save(my_file_path, my_table) then
  -- Alert user that the data could not be saved
end

sys.set_connectivity_host()

sys.set_connectivity_host(host)

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

PARAMETERS

EXAMPLES

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

sys.set_error_handler()

sys.set_error_handler(error_handler)

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

PARAMETERS

EXAMPLES

Install error handler that just prints the errors

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

sys.set_update_frequency()

sys.set_update_frequency(frequency)

Set game update-frequency (frame cap). This option is equivalent to display.update_frequency in the "game.project" settings but set in run-time. If Vsync checked in "game.project", the rate will be clamped to a swap interval that matches any detected main monitor refresh rate. If Vsync is unchecked the engine will try to respect the rate in software using timers. There is no guarantee that the frame cap will be achieved depending on platform specifics and hardware settings.

PARAMETERS

EXAMPLES

Setting the update frequency to 60 frames per second

sys.set_update_frequency(60)

sys.set_vsync_swap_interval()

sys.set_vsync_swap_interval(swap_interval)

Set the vsync swap interval. The interval with which to swap the front and back buffers in sync with vertical blanks (v-blank), the hardware event where the screen image is updated with data from the front buffer. A value of 1 swaps the buffers at every v-blank, a value of 2 swaps the buffers every other v-blank and so on. A value of 0 disables waiting for v-blank before swapping the buffers. Default value is 1.

When setting the swap interval to 0 and having vsync disabled in "game.project", the engine will try to respect the set frame cap value from "game.project" in software instead.

This setting may be overridden by driver settings.

PARAMETERS

EXAMPLES

Setting the swap intervall to swap every v-blank

sys.set_vsync_swap_interval(1)

Constants

sys.NETWORK_CONNECTED

network connected through other, non cellular, connection

sys.NETWORK_CONNECTED_CELLULAR

network connected through mobile cellular

sys.NETWORK_DISCONNECTED

no network connection found

Messages

exit

exits application

Terminates the game application and reports the specified code to the OS. This message can only be sent to the designated @system socket.

EXAMPLES

This examples demonstrates how to exit the application when some kind of quit messages is received (maybe from gui or similar):

function on_message(self, message_id, message, sender)
    if message_id == hash("quit") then
        msg.post("@system:", "exit", {code = 0})
    end
end

reboot

reboot engine with arguments

Reboots the game engine with a specified set of arguments. Arguments will be translated into command line arguments. Sending the reboot command is equivalent to starting the engine with the same arguments.

On startup the engine reads configuration from "game.project" in the project root.

This message can only be sent to the designated @system socket.

EXAMPLES

How to reboot engine with a specific bootstrap collection.

local arg1 = '--config=bootstrap.main_collection=/my.collectionc'
local arg2 = 'build/default/game.projectc'
msg.post("@system:", "reboot", {arg1 = arg1, arg2 = arg2})

set_update_frequency

set update frequency

Set game update-frequency (frame cap). This option is equivalent to display.update_frequency in the "game.project" settings but set in run-time. If Vsync checked in "game.project", the rate will be clamped to a swap interval that matches any detected main monitor refresh rate. If Vsync is unchecked the engine will try to respect the rate in software using timers. There is no guarantee that the frame cap will be achieved depending on platform specifics and hardware settings.

This message can only be sent to the designated @system socket.

EXAMPLES

msg.post("@system:", "set_update_frequency", { frequency = 60 } )

set_vsync

set vsync swap interval

Set the vsync swap interval. The interval with which to swap the front and back buffers in sync with vertical blanks (v-blank), the hardware event where the screen image is updated with data from the front buffer. A value of 1 swaps the buffers at every v-blank, a value of 2 swaps the buffers every other v-blank and so on. A value of 0 disables waiting for v-blank before swapping the buffers. Default value is 1.

When setting the swap interval to 0 and having vsync disabled in "game.project", the engine will try to respect the set frame cap value from "game.project" in software instead.

This setting may be overridden by driver settings.

This message can only be sent to the designated @system socket.

EXAMPLES

msg.post("@system:", "set_vsync", { swap_interval = 1 } )

start_record

starts video recording

Starts video recording of the game frame-buffer to file. Current video format is the open vp8 codec in the ivf container. It's possible to upload this format directly to YouTube. The VLC video player has native support but with the known issue that not the entire file is played back. It's probably an issue with VLC. The Miro Video Converter has support for vp8/ivf.

Video recording is only supported on desktop platforms.

Audio is currently not supported

Window width and height must be a multiple of 8 to be able to record video.

This message can only be sent to the designated @system socket.

EXAMPLES

Record a video in 30 fps given that the native game fps is 60:

msg.post("@system:", "start_record", { file_name = "test_rec.ivf" } )

To write a video in 60 fps given that the native game fps is 60:

msg.post("@system:", "start_record", { file_name = "test_rec.ivf", frame_period = 1, fps = 60 } )

stop_record

stop current video recording

Stops the currently active video recording.

Video recording is only supported on desktop platforms.

This message can only be sent to the designated @system socket.

EXAMPLES

msg.post("@system:", "stop_record")

toggle_physics_debug

shows/hides the on-screen physics visual debugging

Toggles the on-screen physics visual debugging mode which is very useful for tracking down issues related to physics. This mode visualizes all collision object shapes and normals at detected contact points. Toggling this mode on is equal to setting physics.debug in the "game.project" settings, but set in run-time.

This message can only be sent to the designated @system socket.

EXAMPLES

msg.post("@system:", "toggle_physics_debug")

toggle_profile

shows/hides the on-screen profiler

Toggles the on-screen profiler. The profiler is a real-time tool that shows the numbers of milliseconds spent in each scope per frame as well as counters. The profiler is very useful for tracking down performance and resource problems.

In addition to the on-screen profiler, Defold includes a web-based profiler that allows you to sample a series of data points and then analyze them in detail. The web profiler is available at http://<device IP>:8002 where is the IP address of the device you are running your game on.

This message can only be sent to the designated @system socket.

EXAMPLES

msg.post("@system:", "toggle_profile")