Version: stable
FUNCTION | |
---|---|
sys.save() | saves a lua table to a file stored on disk |
sys.load() | loads a lua table from a file on disk |
sys.get_save_file() | gets the save-file path |
sys.get_application_path() | gets the application path |
sys.get_config() | get config value |
sys.get_config() | get config value with default value |
sys.open_url() | open url in default application |
sys.load_resource() | loads resource from game data |
sys.get_sys_info() | get system information |
sys.get_engine_info() | get engine information |
sys.get_application_info() | get application information |
sys.get_ifaddrs() | enumerate network interfaces |
sys.set_error_handler() | set the error handler |
sys.set_connectivity_host() | set host to check for network connectivity against |
sys.get_connectivity() | get current network connectivity status |
sys.exit() | exits application |
sys.reboot() | reboot engine with arguments |
sys.set_vsync_swap_interval() | set vsync swap interval |
sys.set_update_frequency() | set update frequency |
CONSTANT | |
---|---|
sys.NETWORK_DISCONNECTED | no network connection found |
sys.NETWORK_CONNECTED_CELLULAR | network connected through mobile cellular |
sys.NETWORK_CONNECTED | network connected through other, non cellular, connection |
MESSAGE | |
---|---|
exit | exits application |
toggle_profile | shows/hides the on-screen profiler |
toggle_physics_debug | shows/hides the on-screen physics visual debugging |
start_record | starts video recording |
stop_record | stop current video recording |
reboot | reboot engine with arguments |
set_vsync | set vsync swap interval |
set_update_frequency | set update frequency |
sys.save(filename,table)
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
filename |
file to write to |
table |
lua table to save |
RETURNS
success |
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.load(filename)
sys.save
to be loaded.
PARAMETERS
filename |
file to read from |
RETURNS
loaded |
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.get_save_file(application_id,file_name)
PARAMETERS
application_id |
user defined id of the application, which helps define the location of the save-file |
file_name |
file-name to get path for |
RETURNS
path |
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_application_path()
PARAMETERS
RETURNS
path |
path to application executable |
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(key)
--config
argument.
PARAMETERS
key |
key to get value for. The syntax is SECTION.KEY |
RETURNS
value |
config value as a string. nil if the config key doesn't exists |
EXAMPLES
Get display widthlocal width = tonumber(sys.get_config("display.width"))
$ mygame --config=bootstrap.main_collection=/mytest.collectionc --config=mygame.testmode=1
local testmode = tonumber(sys.get_config("mygame.testmode"))
sys.get_config(key,default_value)
PARAMETERS
key |
key to get value for. The syntax is SECTION.KEY |
default_value |
default value to return if the value does not exist |
RETURNS
value |
config value as a string. default_value if the config key does not exist |
EXAMPLES
Get user config valuelocal speed = tonumber(sys.get_config("my_game.speed", "10.23"))
sys.open_url(url,[attributes])
PARAMETERS
url |
url to open |
[attributes] |
table with attributes
target
- string : Optional. Specifies the target attribute or the name of the window. The following values are supported:
- _self - URL replaces the current page. This is default.
- _blank - URL is loaded into a new window, or tab.
- _parent - URL is loaded into the parent frame.
- _top - URL replaces any framesets that may be loaded.
- name - The name of the window (Note: the name does not specify the title of the new window). |
RETURNS
success |
a boolean indicating if the url could be opened or not |
EXAMPLES
Open an URL:local success = sys.open_url("http://www.defold.com", {target = "_blank"}) if not success then -- could not open the url... end
sys.load_resource(filename)
PARAMETERS
filename |
resource to load, full path |
RETURNS
data |
loaded data, or nil if the resource could not be loaded |
error |
the error message, or nil if no error occurred |
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.get_sys_info()
PARAMETERS
RETURNS
sys_info |
table with system information in the following fields:
|
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.get_engine_info()
PARAMETERS
RETURNS
engine_info |
table with engine information in the following fields:
|
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_application_info(app_string)
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 |
platform specific string with application package or query, see above for details. |
RETURNS
app_info |
table with application information in the following fields:
|
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
... <key>LSApplicationQueriesSchemes</key> <array> <string>twitter</string> </array> ...
sys.get_ifaddrs()
PARAMETERS
RETURNS
ifaddrs |
an array of tables. Each table entry contain the following fields:
|
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.set_error_handler(error_handler)
PARAMETERS
error_handler |
the function to be called on error
|
EXAMPLES
Install error handler that just prints the errorslocal 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_connectivity_host(host)
PARAMETERS
host |
hostname to check against |
EXAMPLES
sys.set_connectivity_host("www.google.com")
sys.get_connectivity()
sys.NETWORK_CONNECTED
.
PARAMETERS
RETURNS
status |
network connectivity status:
|
EXAMPLES
Check if we are connected through a cellular connectionif (sys.NETWORK_CONNECTED_CELLULAR == sys.get_connectivity()) then print("Connected via cellular, avoid downloading big files!") end
sys.exit(code)
code
to the OS.
PARAMETERS
code |
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 sys.exit(0) end end
sys.reboot(arg1,arg2,arg3,arg4,arg5,arg6)
PARAMETERS
arg1 |
argument 1 |
arg2 |
argument 2 |
arg3 |
argument 3 |
arg4 |
argument 4 |
arg5 |
argument 5 |
arg6 |
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' sys.reboot(arg1, arg2)
sys.set_vsync_swap_interval(swap_interval)
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
swap_interval |
target swap interval. |
EXAMPLES
Setting the swap intervall to swap every v-blanksys.set_vsync_swap_interval(1)
sys.set_update_frequency(frequency)
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
frequency |
target frequency. 60 for 60 fps |
EXAMPLES
Setting the update frequency to 60 frames per secondsys.set_update_frequency(60)
no network connection found
no network connection found
network connected through mobile cellular
network connected through mobile cellular
network connected through other, non cellular, connection
network connected through other, non cellular, connection
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.
code |
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
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 @system
socket.
EXAMPLES
msg.post("@system:", "toggle_profile")
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")
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.
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" } )
msg.post("@system:", "start_record", { file_name = "test_rec.ivf", frame_period = 1, fps = 60 } )
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")
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.
arg1 |
argument 1 |
arg2 |
argument 2 |
arg3 |
argument 3 |
arg4 |
argument 4 |
arg5 |
argument 5 |
arg6 |
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 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.
swap_interval |
target swap interval. |
EXAMPLES
msg.post("@system:", "set_vsync", { swap_interval = 1 } )
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.
frequency |
target frequency. 60 for 60 fps |
EXAMPLES
msg.post("@system:", "set_update_frequency", { frequency = 60 } )