Defold c++
• Overview
• Align
• dmAndroid
• Array
• Atomic
• dmBuffer
• dmGameSystem
• dmGameObject
• dmConditionVariable
• dmConfigFile
• dmConnectionPool
• dmCrypt
• dmDDF
• DStrings
• engine
• dmEngine
• Extension
• dmExtension
• dmFileDescriptor
• dmGraphics
• dmGui
• Hash
• Hashtable
• dmHid
• dmHttpClient
• dmImage
• dmIntersection
• Log
• dmMath
• dmMemory
• dmMessage
• dmMutex
• ObjectPool
• dmPhysics
• dmProfile
• dmRender
• Resource
• dmResource
• dmScript
• SharedLibrary
• dmSocket
• dmSpinlock
• dmSSLSocket
• dmStaticAssert
• dmSys
• dmThread
• dmTime
• dmTransform
• dmURI
• dmUtf8
• dmVMath
• dmWebServer
Defold lua
• Overview
• b2d.body
• b2d
• base
• bit
• buffer
• builtins
• camera
• collectionfactory
• collectionproxy
• physics
• coroutine
• crash
• debug
• editor
• factory
• go
• graphics
• gui
• html5
• http
• image
• io
• json
• label
• liveupdate
• socket
• math
• msg
• model
• os
• package
• particlefx
• profiler
• render
• resource
• sound
• sprite
• string
• sys
• table
• tilemap
• timer
• types
• vmath
• window
• zlib
Extension
• Overview
• adinfo
• admob
• adpf
• camera
• crazygames
• crypt
• facebook
• firebase
• firebase
• firebase
• fontgen
• instantapp
• gpgs
• iac
• iap
• ironsource
• permissions
• poki_sdk
• push
• review
• rive
• safearea
• siwa
• spine
• gui
• steam
• websocket
• webview
• shop
• zendesk
Version
• alpha
• beta
• stable

System API documentation

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

Version: stable

Functions

sys.deserialize()

sys.deserialize(buffer)

deserializes buffer into a lua table

PARAMETERS

RETURNS

EXAMPLES

localbuffer=sys.serialize(my_table)localtable=sys.deserialize(buffer)

sys.exists()

sys.exists(path)

Check if a path existsGood for checking if a file exists before loading a large file

PARAMETERS

RETURNS

EXAMPLES

ifnotsys.exists(path)thenreturnnilendreturnsys.load(path)-- returns {} if it failed

sys.exit()

sys.exit(code)

Terminates the game application and reports the specifiedcode to the OS.

PARAMETERS

EXAMPLES

functionon_message(self,message_id,message,sender)ifmessage_id==hash("quit")thensys.exit(0)endend

sys.get_application_info()

sys.get_application_info(app_string)

Returns a table with application information for the requested app. On iOS, theapp_string is an url scheme for the app that is queried. Yourgame needs to list the schemes that are queried in anLSApplicationQueriesSchemes arrayin a custom "Info.plist". On Android, theapp_string is the package identifier for the app.

PARAMETERS

RETURNS

EXAMPLES

sysinfo=sys.get_sys_info()twitter={}ifsysinfo.system_name=="Android"thentwitter=sys.get_application_info("com.twitter.android")elseifsysinfo.system_name=="iPhone OS"thentwitter=sys.get_application_info("twitter:")endiftwitter.installedthen-- twitter is installed!end

...<key>LSApplicationQueriesSchemes</key><array><string>twitter</string></array>...

sys.get_application_path()

sys.get_application_path()

The path from which the application is run.

PARAMETERS

None

RETURNS

EXAMPLES

-- macOS: /Applications/my_game.applocalapplication_path=sys.get_application_path()print(application_path)--> /Applications/my_game.app-- Windows: C:\Program Files\my_game\my_game.exeprint(application_path)--> C:\Program Files\my_game-- Linux: /home/foobar/my_game/my_gameprint(application_path)--> /home/foobar/my_game-- Android package name: com.foobar.my_gameprint(application_path)--> /data/user/0/com.foobar.my_game-- iOS: my_game.appprint(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_int()

sys.get_config_int(key,default_value)

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

PARAMETERS

RETURNS

EXAMPLES

localspeed=sys.get_config_int("my_game.speed",20)-- with default value

localtestmode=sys.get_config_int("my_game.testmode")-- without default valueiftestmode~=nilthen-- do stuffend

sys.get_config_number()

sys.get_config_number(key,default_value)

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

PARAMETERS

RETURNS

EXAMPLES

localspeed=sys.get_config_number("my_game.speed",20.0)

sys.get_config_string()

sys.get_config_string(key,default_value)

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

PARAMETERS

RETURNS

EXAMPLES

localtext=sys.get_config_string("my_game.text","default text"))

$ dmengine --config=bootstrap.main_collection=/mytest.collectionc --config=mygame.testmode=1

localtestmode=sys.get_config_int("mygame.testmode")

sys.get_connectivity()

sys.get_connectivity()

Returns the current network connectivity statuson mobile platforms.On desktop, this function always returnsys.NETWORK_CONNECTED.

PARAMETERS

None

RETURNS

EXAMPLES

if(sys.NETWORK_CONNECTED_CELLULAR==sys.get_connectivity())thenprint("Connected via cellular, avoid downloading big files!")end

sys.get_engine_info()

sys.get_engine_info()

Returns a table with engine information.

PARAMETERS

None

RETURNS

EXAMPLES

-- Update version text label so our testers know what version we're runninglocalengine_info=sys.get_engine_info()localversion_str="Defold "..engine_info.version.."\n"..engine_info.version_sha1gui.set_text(gui.get_node("version"),version_str)

sys.get_host_path()

sys.get_host_path(filename)

Create a path to the host device for unit testingUseful for saving logs etc during development

PARAMETERS

RETURNS

EXAMPLES

localhost_path=sys.get_host_path("logs/test.txt")sys.save(host_path,mytable)

localhost_path=sys.get_host_path("logs/test.txt")localtable=sys.load(host_path)

sys.get_ifaddrs()

sys.get_ifaddrs()

Returns an array of tables with information on network interfaces.

PARAMETERS

None

RETURNS

EXAMPLES

ifaddrs=sys.get_ifaddrs()for_,interfaceinipairs(ifaddrs)doifinterface.name=="en0"thenlocalip=interface.addressendend

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

RETURNS

EXAMPLES

localmy_file_path=sys.get_save_file("my_game","my_file")-- macOS: /Users/foobar/Library/Application Support/my_game/my_fileprint(my_file_path)--> /Users/foobar/Library/Application Support/my_game/my_file-- Windows: C:\Users\foobar\AppData\Roaming\my_game\my_fileprint(my_file_path)--> C:\Users\foobar\AppData\Roaming\my_game\my_file-- Linux: $XDG_DATA_HOME/my_game/my_file or /home/foobar/.my_game/my_file-- Linux: Defaults to /home/foobar/.local/share/my_game/my_file if neither exist.print(my_file_path)--> /home/foobar/.local/share/my_game/my_file-- Android package name: com.foobar.packagenameprint(my_file_path)--> /data/data/0/com.foobar.packagename/files/my_file-- iOS: /var/mobile/Containers/Data/Application/123456AB-78CD-90DE-12345678ABCD/my_game/my_fileprint(my_file_path)--> /var/containers/Bundle/Applications/123456AB-78CD-90DE-12345678ABCD/my_game.app-- HTML5 path inside the IndexedDB: /data/.my_game/my_file or /.my_game/my_fileprint(my_file_path)--> /data/.my_game/my_file

sys.get_sys_info()

sys.get_sys_info(options)

Returns a table with system information.

PARAMETERS

RETURNS

EXAMPLES

localinfo=sys.get_sys_info()ifinfo.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 bysys.save to be loaded.

PARAMETERS

RETURNS

EXAMPLES

localmy_file_path=sys.get_save_file("my_game","my_file")localmy_table=sys.load(my_file_path)ifnotnext(my_table)then-- empty tableend

sys.load_buffer()

sys.load_buffer(path)

The sys.load_buffer function will first try to load the resourcefrom any of the mounted resource locations and return the data ifany matching entries found. If not, the path will be triedas is from the primary disk on the device.In order for the engine to include custom resources in the build process, you needto 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 includedin the resource list, all files and directories in that directory is recursivelyincluded:For example "main/data/,assets/level_data.json".

PARAMETERS

RETURNS

EXAMPLES

localmy_buffer=sys.load_buffer("/assets/my_level_data.bin")localdata_str=buffer.get_bytes(my_buffer,"data")localhas_my_header=string.sub(data_str,1,6)=="D3F0LD"

localasset_1=sys.load_buffer("folder_next_to_binary/my_level_asset.txt")localasset_2=sys.load_buffer("/my/absolute/path")

sys.load_buffer_async()

sys.load_buffer_async(path,status_callback)

The sys.load_buffer function will first try to load the resourcefrom any of the mounted resource locations and return the data ifany matching entries found. If not, the path will be triedas is from the primary disk on the device.In order for the engine to include custom resources in the build process, you needto 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 includedin the resource list, all files and directories in that directory is recursivelyincluded:For example "main/data/,assets/level_data.json".Note that issuing multiple requests of the same resource will yieldindividual buffers per request. There is no implic caching of the buffersbased on request path.

PARAMETERS

RETURNS

EXAMPLES

functionmy_callback(self,request_id,result)ifresult.status==resource.REQUEST_STATUS_FINISHEDthenresource.set_texture("/my_texture",{...},result.buf)endendlocalmy_request=sys.load_buffer_async("/assets/my_level_data.bin",my_callback)

functionmy_callback(self,request_id,result)ifresult.status~=sys.REQUEST_STATUS_FINISHEDthen-- uh oh! File could not be found, do something gracefulelseifrequest_id==self.first_assetthen-- result.buffer contains data from my_level_asset.binelifrequest_id==self.second_assetthen-- result.buffer contains data from 'my_level.bin'endendfunctioninit(self)self.first_asset=hash("folder_next_to_binary/my_level_asset.bin")self.second_asset=hash("/some_absolute_path/my_level.bin")self.first_request=sys.load_buffer_async(self.first_asset,my_callback)self.second_request=sys.load_buffer_async(self.second_asset,my_callback)end

sys.load_resource()

sys.load_resource(filename)

Loads a custom resource. Specify the full filename of the resource that you wantto load. When loaded, the file data is returned as a string.If loading fails, the function returnsnil plus the error message.In order for the engine to include custom resources in the build process, you needto 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 includedin the resource list, all files and directories in that directory is recursivelyincluded:For example "main/data/,assets/level_data.json".

PARAMETERS

RETURNS

EXAMPLES

-- Load level data into a stringlocaldata,error=sys.load_resource("/assets/level_data.json")-- Decode json string to a Lua tableifdatathenlocaldata_table=json.decode(data)pprint(data_table)elseprint(error)end

sys.open_url()

sys.open_url(url,attributes)

Open URL in default application, typically a browser

PARAMETERS

RETURNS

EXAMPLES

localsuccess=sys.open_url("http://www.defold.com",{target="_blank"})ifnotsuccessthen-- could not open the url...end

sys.reboot()

sys.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. Calling rebootfunction is equivalent to starting the engine with the same arguments.On startup the engine reads configuration from "game.project" in theproject root.

PARAMETERS

EXAMPLES

localarg1='--config=bootstrap.main_collection=/my.collectionc'localarg2='build/game.projectc'sys.reboot(arg1,arg2)

sys.save()

sys.save(filename,table)

The table can later be loaded bysys.load.Usesys.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 ofkeys are permitted to fall within a 32 bit range, supporting sparse arrays, howeverthe limit on the total number of rows remains in effect.

PARAMETERS

RETURNS

EXAMPLES

localmy_table={}table.insert(my_table,"my_value")localmy_file_path=sys.get_save_file("my_game","my_file")ifnotsys.save(my_file_path,my_table)then-- Alert user that the data could not be savedend

sys.serialize()

sys.serialize(table)

The buffer can later deserialized bysys.deserialize.This method has all the same limitations assys.save.

PARAMETERS

RETURNS

EXAMPLES

localmy_table={}table.insert(my_table,"my_value")localbuffer=sys.serialize(my_table)

sys.set_connectivity_host()

sys.set_connectivity_host(host)

Sets the host that is used to check for network connectivity against.

PARAMETERS

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

EXAMPLES

localfunctionmy_error_handler(source,message,traceback)print(source)--> luaprint(message)--> main/my.script:10: attempt to perform arithmetic on a string valueprint(traceback)--> stack traceback:-->         main/test.script:10: in function 'boom'-->         main/test.script:15: in function <main/my.script:13>endlocalfunctionboom()return10+"string"endfunctioninit(self)sys.set_error_handler(my_error_handler)boom()end

sys.set_update_frequency()

sys.set_update_frequency(frequency)

Set game update-frequency (frame cap). This option is equivalent todisplay.update_frequency inthe "game.project" settings but set in run-time. IfVsync checked in "game.project", the rate willbe clamped to a swap interval that matches any detected main monitor refresh rate. IfVsync isunchecked the engine will try to respect the rate in software using timers. There is noguarantee that the frame cap will be achieved depending on platform specifics and hardware settings.

PARAMETERS

EXAMPLES

sys.set_update_frequency(60)

sys.set_vsync_swap_interval()

sys.set_vsync_swap_interval(swap_interval)

Set the vsync swap interval. The interval with which to swap the front and back buffersin sync with vertical blanks (v-blank), the hardware event where the screen image is updatedwith data from the front buffer. A value of 1 swaps the buffers at every v-blank, a value of2 swaps the buffers every other v-blank and so on. A value of 0 disables waiting for v-blankbefore swapping the buffers. Default value is 1.When setting the swap interval to 0 and havingvsync 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

EXAMPLES

sys.set_vsync_swap_interval(1)

Constants

sys.NETWORK_CONNECTED

network connected through other, non cellular, connection

sys.NETWORK_CONNECTED_CELLULAR

network connected through mobile cellular

sys.NETWORK_DISCONNECTED

no network connection found

sys.REQUEST_STATUS_ERROR_IO_ERROR

an asyncronous request is unable to read the resource

sys.REQUEST_STATUS_ERROR_NOT_FOUND

an asyncronous request is unable to locate the resource

sys.REQUEST_STATUS_FINISHED

an asyncronous request has finished successfully

Messages

exit

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

EXAMPLES

functionon_message(self,message_id,message,sender)ifmessage_id==hash("quit")thenmsg.post("@system:","exit",{code=0})endend

reboot

Reboots the game engine with a specified set of arguments.Arguments will be translated into command line arguments. Sending the rebootcommand is equivalent to starting the engine with the same arguments.On startup the engine reads configuration from "game.project" in theproject root.This message can only be sent to the designated@system socket.

EXAMPLES

localarg1='--config=bootstrap.main_collection=/my.collectionc'localarg2='build/game.projectc'msg.post("@system:","reboot",{arg1=arg1,arg2=arg2})

resume_rendering

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

EXAMPLES

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

set_update_frequency

Set game update-frequency (frame cap). This option is equivalent todisplay.update_frequency inthe "game.project" settings but set in run-time. IfVsync checked in "game.project", the rate willbe clamped to a swap interval that matches any detected main monitor refresh rate. IfVsync isunchecked the engine will try to respect the rate in software using timers. There is noguarantee 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.

EXAMPLES

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

set_vsync

Set the vsync swap interval. The interval with which to swap the front and back buffersin sync with vertical blanks (v-blank), the hardware event where the screen image is updatedwith data from the front buffer. A value of 1 swaps the buffers at every v-blank, a value of2 swaps the buffers every other v-blank and so on. A value of 0 disables waiting for v-blankbefore swapping the buffers. Default value is 1.When setting the swap interval to 0 and havingvsync 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.

EXAMPLES

msg.post("@system:", "set_vsync", { swap_interval = 1 } )

start_record

Starts video recording of the game frame-buffer to file. Current video format is theopen vp8 codec in the ivf container. It's possible to upload this format directlyto YouTube. The VLC video player has native support but with the known issue thatnot 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.

EXAMPLES

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_record

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

toggle_physics_debug

Toggles the on-screen physics visual debugging mode which is very useful fortracking down issues related to physics. This mode visualizesall collision object shapes and normals at detected contact points. Togglingthis mode on is equal to settingphysics.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

Toggles the on-screen profiler.The profiler is a real-time tool that shows the numbers of milliseconds spentin each scope per frame as well as counters. The profiler is very useful fortracking down performance and resource problems.In addition to the on-screen profiler, Defold includes a web-based profiler thatallows you to sample a series of data points and then analyze them in detail.The web profiler is available athttp://<device IP>:8002 where isthe 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")