Welcome!

You are just one step away from creating awesome games!

You need a Google account to use Defold

Select document

System API documentation

version 1.2.100

Functions

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

app_string

string platform specific string with application package or query, see above for details.

app_string

string platform specific string with application package or query, see above for details.

Returns

app_info

table table with application information in the following fields:

installed
boolean true if the application is installed, false otherwise.
app_info

table table with application information in the following fields:

installed
boolean true if the application is installed, false otherwise.

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_config

sys.get_config(key)

Get config value from the game.project configuration file.

Parameters

key

string key to get value for. The syntax is SECTION.KEY

key

string key to get value for. The syntax is SECTION.KEY

Returns

value

string config value as a string. nil if the config key doesn't exists

value

string config value as a string. nil if the config key doesn't exists

Examples

Get display width

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

sys.get_config

sys.get_config(key, default_value)

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

Parameters

key

string key to get value for. The syntax is SECTION.KEY

default_value

string default value to return if the value does not exist

key

string key to get value for. The syntax is SECTION.KEY

default_value

string 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

value

string config value as a string. default_value if the config key does not exist

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.

Returns

status

constant network connectivity status:

  • sys.NETWORK_DISCONNECTED (no network connection is found)
  • sys.NETWORK_CONNECTED_CELLULAR (connected through mobile cellular)
  • sys.NETWORK_CONNECTED (otherwise)
status

constant network connectivity status:

  • sys.NETWORK_DISCONNECTED (no network connection is found)
  • sys.NETWORK_CONNECTED_CELLULAR (connected through mobile cellular)
  • sys.NETWORK_CONNECTED (otherwise)

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.

Returns

engine_info

table table with engine information in the following fields:

version
string The current Defold engine version, i.e. "1.2.96"
engine_sha1
string The SHA1 for the current engine build, i.e. "0060183cce2e29dbd09c85ece83cbb72068ee050"
engine_info

table table with engine information in the following fields:

version
string The current Defold engine version, i.e. "1.2.96"
engine_sha1
string The SHA1 for the current engine build, i.e. "0060183cce2e29dbd09c85ece83cbb72068ee050"

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.

Returns

ifaddrs

table an array of tables. Each table entry contain the followind fields:

name
string Interface name
address
string IP address. might be nil if not available.
mac
string Hardware MAC address. might be nil if not available.
up
boolean true if the interface is up (available to transmit and receive data), false otherwise.
running
boolean true if the interface is running, false otherwise.
ifaddrs

table an array of tables. Each table entry contain the followind fields:

name
string Interface name
address
string IP address. might be nil if not available.
mac
string Hardware MAC address. might be nil if not available.
up
boolean true if the interface is up (available to transmit and receive data), false otherwise.
running
boolean true if the interface is running, false otherwise.

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

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

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

path

string path to save-file

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.

Returns

sys_info

table table with system information in the following fields:

device_model
string Only available on iOS and Android.
manufacturer
string Only available on iOS and Android.
system_name
string The system OS name: "Darwin", "Linux", "Windows", "HTML5", "Android" or "iPhone OS"
system_version
string The system OS version.
api_version
string The API version on the system.
language
string Two character ISO-639 format, i.e. "en".
device_language
string Two character ISO-639 format (i.e. "sr") and, if applicable, followed by a dash (-) and an ISO 15924 script code (i.e. "sr-Cyrl" or "sr-Latn"). Reflects the device preferred language.
territory
string Two character ISO-3166 format, i.e. "US".
gmt_offset
number The current offset from GMT (Greenwich Mean Time), in minutes.
device_ident
string "identifierForVendor" on iOS. "android_id" on Android.
ad_ident
string "advertisingIdentifier" on iOS. advertising ID provided by Google Play on Android.
ad_tracking_enabled
boolean true if ad tracking is enabled, false otherwise.
user_agent
string The HTTP user agent, i.e. "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/602.4.8 (KHTML, like Gecko) Version/10.0.3 Safari/602.4.8"
sys_info

table table with system information in the following fields:

device_model
string Only available on iOS and Android.
manufacturer
string Only available on iOS and Android.
system_name
string The system OS name: "Darwin", "Linux", "Windows", "HTML5", "Android" or "iPhone OS"
system_version
string The system OS version.
api_version
string The API version on the system.
language
string Two character ISO-639 format, i.e. "en".
device_language
string Two character ISO-639 format (i.e. "sr") and, if applicable, followed by a dash (-) and an ISO 15924 script code (i.e. "sr-Cyrl" or "sr-Latn"). Reflects the device preferred language.
territory
string Two character ISO-3166 format, i.e. "US".
gmt_offset
number The current offset from GMT (Greenwich Mean Time), in minutes.
device_ident
string "identifierForVendor" on iOS. "android_id" on Android.
ad_ident
string "advertisingIdentifier" on iOS. advertising ID provided by Google Play on Android.
ad_tracking_enabled
boolean true if ad tracking is enabled, false otherwise.
user_agent
string The HTTP user agent, i.e. "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/602.4.8 (KHTML, like Gecko) Version/10.0.3 Safari/602.4.8"

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

filename

string file to read from

filename

string file to read from

Returns

loaded

table lua table, which is empty if the file could not be found

loaded

table lua table, which is empty if the file could not be found

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.

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

filename

string resource to load, full path

filename

string resource to load, full path

Returns

data

string loaded data, or nil if the resource could not be loaded

data

string loaded data, or nil if the resource could not be loaded

Examples

-- Load level data into a string
local data = sys.load_resource("/assets/level_data.json")
-- Decode json string to a Lua table
local data_table = json.decode(data)
pprint(data_table)

sys.open_url

sys.open_url(url)

Open URL in default application, typically a browser

Parameters

url

string url to open

url

string url to open

Returns

success

boolean a boolean indicating if the url could be opened or not

success

boolean a boolean indicating if the url could be opened or not

Examples

Open an URL:

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

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 128kb. 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

filename

string file to write to

table

table lua table to save

filename

string file to write to

table

table lua table to save

Returns

success

boolean a boolean indicating if the table could be saved or not

success

boolean a boolean indicating if the table could be saved or not

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

host

string hostname to check against

host

string hostname to check against

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

error_handler

function(source, message, traceback) 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.
error_handler

function(source, message, traceback) 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.

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

Messages

exit

"exit", { code=… }

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

Fields

code

number exit code to report to the OS, 0 means clean exit

code

number exit code to report to the OS, 0 means clean exit

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", { arg1=…, arg2=…, arg3=…, arg4=…, arg5=…, arg6=… }

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.

Fields

arg1

string argument 1

arg2

string argument 2

arg3

string argument 3

arg4

string argument 4

arg5

string argument 5

arg6

string argument 6

arg1

string argument 1

arg2

string argument 2

arg3

string argument 3

arg4

string argument 4

arg5

string argument 5

arg6

string argument 6

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", { frequency=… }

Set game update-frequency. This option is equivalent to display.update_frequency in the "game.project" settings but set in run-time.

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

Fields

frequency

target frequency. 60 for 60 fps

frequency

target frequency. 60 for 60 fps

Examples

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

start_record

"start_record", { file_name=…, frame_period=…, fps=… }

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 entirely files is played back. It's probably an issue with VLC. The Miro Video Converter has support for vp8/ivf.

Audio is currently not supported

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

Fields

file_name

string file name to write the video to

frame_period

number frame period to record, ie write every nth frame. Default value is 2

fps

number frames per second. Playback speed for the video. Default value is 30. The fps value doens't affect the recording. It's only meta-data in the written video file.

file_name

string file name to write the video to

frame_period

number frame period to record, ie write every nth frame. Default value is 2

fps

number frames per second. Playback speed for the video. Default value is 30. The fps value doens't affect the recording. It's only meta-data in the written video file.

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

Stops the currently active video recording.

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

Examples

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

toggle_physics_debug

"toggle_physics_debug"

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

"toggle_profile"

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

I want to report anonymously.