View source

final class Sys

package defold

@:native("_G.sys")
  • Functions and messages for using system resources, controlling the engine, error handling and debugging.

See SysMessages for standard system messages.

Static methods

staticdeserialize(buffer:String):AnyTable

  • Deserializes buffer into a lua table.

Parameters:

buffer

buffer to deserialize from

Returns:

lua table with deserialized data

staticexists(path:String):Bool

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

Parameters:

path

path to check

Returns:

true if the path exists, false otherwise

staticexit(code:Int):Void

  • Exits application.

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

Parameters:

code

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

@:native("get_application_info")staticgetApplicationInfo(appString:String):SysApplicationInfo

  • Get application information.

Parameters:

appString

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

Returns:

table with application information

@:native("get_application_path")staticgetApplicationPath():String

  • The path from which the application is run.

Returns:

path to application executable

@:native("get_config_int")staticgetConfigInt(key:String, ?defaultValue:Int):Null<Int>

  • Get int 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:

key

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

defaultValue

default value to return if the value does not exist

Returns:

config value as an integer. nil or defaultValue if the config key doesn't exists

@:native("get_config_number")staticgetConfigNumber(key:String, ?defaultValue:Float):Null<Float>

  • Get float 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:

key

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

defaultValue

default value to return if the value does not exist

Returns:

config value as a float. nil or defaultValue if the config key doesn't exists

@:native("get_config_string")staticgetConfigString(key:String, ?defaultValue:String):Null<String>

  • Get string 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:

key

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

defaultValue

default value to return if the value does not exist

Returns:

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

@:native("get_connectivity")staticgetConnectivity():SysConnectivity

  • Returns the current network connectivity status on mobile platforms.

On desktop, this function always return NETWORK_CONNECTED.

@:native("get_engine_info")staticgetEngineInfo():SysEngineInfo

  • Get engine information.

Returns:

table with engine information

@:native("get_ifaddrs")staticgetIfAddrs():LuaArray<SysIfaddr>

  • Enumerate network cards.

Returns:

an array of tables

@:native("get_save_file")staticgetSaveFile(applicationId:String, fileName:String):String

  • Gets the save-file path.

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

Parameters:

applicationId

user defined id of the application, which helps define the location of the save-file

fileName

file-name to get path for

Returns:

path to save-file

@:native("get_sys_info")staticgetSysInfo(?options:Null<GetSysInfoOptions>):SysSysInfo

  • Get system information.

Parameters:

options

table

Returns:

table with system information

staticload(filename:String):AnyTable

  • Loads a lua table from a file on disk.

If the file exists, it must have been created by 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

@:native("load_buffer")staticloadBuffer(path:String):AnyTable

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

Parameters:

path

the path to load the buffer from

Returns:

lua table with deserialized data

@:has_untypedstaticinlineloadBufferAsync(path:String, statusCallback:LoadBufferAsyncCallback):LoadBufferAsyncHandle

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

Parameters:

path

the path to load the buffer from

@:native("load_resource")staticloadResource(filename:String):SysResource

  • Loads resource from game data.

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

resource to load, full path

Returns:

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

@:native("open_url")staticopenUrl(url:String):Bool

  • Open url in default application.

Open URL in default application, typically a browser

Parameters:

url

url to open

Returns:

a boolean indicating if the url could be opened or not

staticreboot(?arg1:String, ?arg2:String, ?arg3:String, ?arg4:String, ?arg5:String, ?arg6:String):Void

  • Reboot engine with arguments.

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.

staticsave(filename:String, table:AnyTable):Bool

  • Saves a lua table to a file stored on disk.

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:

filename

file to write to

table

lua table to save

Returns:

a boolean indicating if the table could be saved or not

staticserialize(buffer:AnyTable):String

  • The buffer can later deserialized by sys.deserialize(). This method has all the same limitations as sys.save().

Parameters:

buffer

lua table to serialize

Returns:

serialized data buffer

@:native("set_connectivity_host")staticsetConnectivityHost(host:String):Void

  • Set host to check for network connectivity against.

Parameters:

host

hostname to check against

@:native("set_error_handler")staticsetErrorHandler(errorHandler:ErrorHandlerCallback):Void

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

Parameters:

errorHandler

the function to be called on error (arguments: source, message, traceback)

@:native("set_update_frequency")staticsetUpdateFrequency(frequency:Int):Void

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

Parameters:

frequency

target frequency. 60 for 60 fps

@:native("set_vsync_swap_interval")staticsetVsyncSwapInterval(swapInterval:Int):Void

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

Parameters:

swapInterval

target swap interval.