Welcome!

You are just one step away from creating awesome games!

You need a Google account to use Defold

HOW TO SUBMIT

To submit your game, simply log in to your Defold dashboard, click “submit your entry”, and follow the instructions!

HOW TO SUBMIT

Sorry, you can't submit your game from a phone. To submit your game, you need to log in to Defold on a desktop.

Select document

System API documentation

version 1.2.96

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

Functions

sys.get_application_info

sys.get_application_info()

Returns a table with the following members: installed.

Returns

table table with application information

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

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

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

number sys.NETWORK_DISCONNECTED if no network connection is found, sys.NETWORK_CONNECTED_CELLULAR if connected through mobile cellular, otherwise sys.NETWORK_CONNECTED

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 the following members: version, engine_sha1.

Returns

table table with engine information

sys.get_ifaddrs

sys.get_ifaddrs()

returns an array of tables with the following members: name, address (ip-string), mac (hardware address, colon separated string), up (bool), running (bool). NOTE: ip and mac might be nil if not available

Returns

table an array of tables

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

string path to save-file

sys.get_sys_info

sys.get_sys_info()

Returns a table with the following members: device_model, manufacturer, system_name, system_version, api_version, language, device_language, territory, gmt_offset (minutes), device_ident, ad_ident, ad_tracking_enabled and user_agent.

device_model and manufacturer is currently only available on iOS and Android.

language is in ISO-639 format (two characters) and territory in ISO-3166 format (two characters).

device_language is in ISO-639 format (two characters) and if applicable by a dash (-) and an ISO 15924 script code. Reflects device preferred language.

device_ident is "identifierForVendor" and ad_ident is "advertisingIdentifier" on iOS

device_ident is "android_id" and ad_ident is advertising ID provided by Google Play on Android.

Returns

table table with system information

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

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

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, it is returned as a string. In order for the engine to include custom resources in the build process, you need to specify them in the "game.project" settings file:

[project]
title = My project
version = 0.1
custom_resources = main/data/,assets/level_data.json

Parameters

filename string resource to load, full path
filename
string resource to load, full path

Returns

string loaded data, which is empty if the file could not be found

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

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

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

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

Examples

Save data:

local my_table = {}
table.add(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

And load it at a later time, e.g. next 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.set_connectivity_host

sys.set_connectivity_host(host)

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)

Parameters

error_handler function the function to be called on error
error_handler
function the function to be called on error

Examples

Install error handler that just prints the errors

 sys.set_error_handler(function(source, message, traceback)
     print("source: " .. source);
     print("message: " .. message);
     print("traceback: " .. traceback);
 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=… }

Arguments will be translated into command line arguments. Sending the reboot command is equivalent to starting the engine with the same arguments.

Fields

arg1 argument 1
arg2 argument 2
arg3 argument 3
arg4 argument 4
arg5 argument 5
arg6 argument 6
arg1
argument 1
arg2
argument 2
arg3
argument 3
arg4
argument 4
arg5
argument 5
arg6
argument 6

Examples

-- 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 but set in run-time

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. NOTE: Audio is currently not supported

Fields

file_name file name to write the video to
frame_period frame period to record, ie write every nth frame. Default value is 2
fps 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
file name to write the video to
frame_period
frame period to record, ie write every nth frame. Default value is 2
fps
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"

Examples

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

toggle_physics_debug

"toggle_physics_debug"

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

Examples

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

toggle_profile

"toggle_profile"

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

Examples

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

I want to report anonymously.