- 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 |
---|
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
staticgetApplicationPath():String
- The path from which the application is run.
Returns:
path to application executable
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
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
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
staticgetConnectivity():SysConnectivity
- Returns the current network connectivity status on mobile platforms.
On desktop, this function always return NETWORK_CONNECTED
.
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
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
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
staticinlineloadBufferAsync(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 |
---|
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
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 assys.save()
.
Parameters:
buffer | lua table to serialize |
---|
Returns:
serialized data buffer
staticsetConnectivityHost(host:String):Void
- Set host to check for network connectivity against.
Parameters:
host | hostname to check against |
---|
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) |
---|
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 |
---|
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. |
---|