Defold Kit

A toolkit for Visual Studio Code to develop, build, launch, debug, bundle and deploy a game with Defold.

• 💼 Installing recommended extensions
• 📝 Lua highlighting, autocompletion and linting
• 🛠️ Applying relevant settings to the workspace
• 📘 Lua annotations for Defold API
• 📚 Lua annotations for dependencies
• 🚀 Building and launching
• 🔎 Debugging with breakpoints
• 📦 Bundling for all the platforms
• 📲 Deploying to connected mobile devices

You can not to use the Defold Editor at all if you are only working with code at the moment.

💬 Discuss on the forum

Setup

It's possible to install the extension from Visual Studio Marketplace or manually by downloading the .vsix archive from the releases page.

After installing the extension and opening a Defold project folder, you will be prompted to setup Defold Kit with a step-by-step dialogue.

If for some reason this doesn't happen, you can run the Setup command manually.

Path to Defold

Defold Kit requires Defold installed (surprise).

Select the automatically suggested path if it exists, or select the Defold folder manually.

Extensions

Select the extensions you want to install.

The first two are highly recommended, the next three are optional:

• sumneko.lua - Autocompletion, annotations, diagnostics and etc.
• tomblind.local-lua-debugger-vscode - Launching the game and debugging with breakpoints.
• thejustinwalsh.textproto-grammer - Syntax highlighting for .collection, .go and other Protobuf files.
• slevesque.shader - GLSL support for .vp and .fp files.
• dtoplak.vscode-glsllint - GLSL linting for .vp and .fp files.

Workspace

Some additional settings to apply to the workspace.

Debugger Scripts

Displayed if the tomblind.local-lua-debugger-vscode extension is installed.

To debug the game with breakpoints, it's required to start the debugger on the game side. These files allow you to do that.

Launch Configuration

Displayed if the tomblind.local-lua-debugger-vscode extension is installed.

To launch the game from the Run and Debug panel, it's required to add the relevant configuration to the .vscode/launch.json file. The Defold configuration will be added.

Workspace Settings

These settings are recommended for Defold project workspace to make your development more comfortable.

The settings will only be applied to the installed extensions. You can check them in the settings.ts.

Workspace Recommendations

Adds Defold Kit to the .vscode/extensions.json file to appear in the recommended extensions to install for this workspace.

Annotations Syncing

This step is skipping if the sumneko.lua extension is not installed.

Synchronise Lua annotations with the Defold Editor version and project dependencies.

Defold API Annotations

Fethes Defold API annotations from the repository according the settings and unpacks them to the Defold Kit shared storage.

Dependencies Annotations

Unpacks archives from the .internal/libs folder and copies *.lua files from libraries to the Defold Kit workspace storage.

Opening Files from Defold

To open script files from the Defold Editor directly in Visual Studio Code, you must set the following settings by specifying the path to the executable file:

• Windows (user installer): C:\Users\%USERNAME%\AppData\Local\Programs\Microsoft VS Code\Code.exe
• Windows (system installer): C:\Program Files\Microsoft VS Code\Code.exe
• macOS: /Applications/Visual Studio Code.app/Contents/MacOS/Electron
• Linux: /usr/bin/code

Set these parameters to open specific files and lines:

• Open File: . {file}
• Open File at Line: . -g {file}:{line}

The . character here is required to open the entire workspace, not an individual file.

Debugger

Local Launch

This workflow builds and launches the game locally from VS Code without using the Defold Editor. It is intended for debugging with breakpoints through local-lua-debugger-vscode.

To launch a game this way, ensure that two these steps are done during setting up Defold Kit:

• The local-lua-debugger-vscode extension is installed.
• Launch configiuration are added to the workspace.

Ensure that the Defold configuration selected on the Run and Debug panel and launch it using the F5 keyboard shortcut (default).

Breakpoints

To make the breakpoints work ensure that Debugger scripts are added to the workspace. Then add the debugger.script component to your initial collection or add this code to your initial script:

local debugger = require('debugger.debugger')
debugger.start()

Defold Editor HTTP API

Defold Kit can also talk to a running Defold Editor through the local Defold Editor HTTP API.

These commands are available from the Command Palette with the Defold Editor prefix:

• Defold Editor: Build builds and runs the project from Defold Editor.
• Defold Editor: Build HTML5 builds the project for HTML5 from Defold Editor.
• Defold Editor: Clean Build clears caches and rebuilds from Defold Editor.
• Defold Editor: Hot Reload reloads modified files into a game already running from Defold Editor.
• Defold Editor: Fetch Libraries downloads project library dependencies through Defold Editor.
• Defold Editor: Console streams the Defold Editor console to a VS Code terminal.

Commands

Commands with the Defold Kit and Defold Editor prefixes are available in the Command Palette using the [Ctrl/Cmd]-Shift-P keyboard shortcut (default).

Defold Kit: Setup

Starts the setup dialogue. It's okay to run this command many times if you are not sure you are ready to turn on all the features at once.

Defold Kit: Sync API Annotations

Opens the Annotations Syncing dialogue.

Defold Kit: Clean API Annotations

Deletes all the previously synced annotations from the global storage and workspace storage.

Defold Kit: Open Defold

Opens the current project in the Defold Editor.

On macOS, the window will be switched if Defold is already running.

Defold Kit: Clean Build

Runs a bob instance with the distclean argument to clean the build folder.

Defold Kit: Resolve Dependencies

Runs a bob instance with the resolve argument to resolve the project's dependencies. Then synchronises Lua annotations if the Lua Language Server is installed.

Defold Kit: Bundle

Runs a bob instance with the resolve distclean build biundle arguments, selected options and defined values form settings.

Executes for all selected target platforms one by one. When finished will prompt you to open the bundle folder.

Platforms

Select which target platforms you want to bundle your game.

Options

• Release — Bundle a Release variant (otherwise bundle Debug variant).
• Texture Compression — Enable texture compression as specified in texture profiles.
• Generate Debug Symbols — Generate the symbol file (if applicable).
• Generate Build Report — Generate the build report file.
• Publish Live Update Content — Publish Live update content.

Defold Kit: Deploy to Mobile

Deploy to the connected mobile device with ios-deploy for iOS and adb for Android. These tools must be installed and accessible via shell.

# Will execute for iOS
ios-deploy -b ${ipa_file}

# Will execute for Android
adb install ${apk_file}

The *.ipa or *.apk file is required in the corresponding bundle folder, so run the Bundle command before deploying.

Defold Editor: Build

Sends the build command to the running Defold Editor over the local Editor HTTP API. This builds and runs the project from the editor.

Defold Editor: Build HTML5

Sends the build-html5 command to the running Defold Editor over the local Editor HTTP API. This builds the project for HTML5 and opens it in a web browser.

Defold Editor: Clean Build

Sends the clean-build command to the running Defold Editor over the local Editor HTTP API. This clears the build caches and rebuilds the project from the editor.

Defold Editor: Hot Reload

Sends the hot-reload command to the running Defold Editor over the local Editor HTTP API. This hot-reloads modified files into the running game.

Enable the experimental defoldKit.defoldEditor.hotReloadOnChange setting to run this command automatically when resource files change in the workspace.

Defold Editor Fetch Libraries

Sends the fetch-libraries command to the running Defold Editor over the local Editor HTTP API. This downloads the latest version of project library dependencies.

Defold Editor: Console

Opens the Defold Editor: Console terminal and streams console output from the running Defold Editor. The console uses the Editor HTTP API /console/stream, keeps the terminal open while the stream is active, highlights common log levels, and makes recognized file paths clickable.

Requires Defold Editor 1.13.0 or newer.

Tasks

Build tasks with the Defold Kit prefix are available using the [Ctrl/Cmd]-Shift-B keyboard shortcut (default).

Tasks are aliases of some commands described above to have a quick access to them.

• Resolve Dependencies
• Clean Build
• Bundle
• Deploy to Mobile

Settings

defoldKit.general.editorPath

The path to the Defold Editor folder.

Running the Setup command is the preferred way to update this value, but you can edit it manually if you're sure of what you are doing.

defoldKit.general.suggestSetup

Suggest to setup Defold Kit if the game.project file is found in the current workspace.

defoldKit.general.showBobOutput

Open the Output panel during a bob instance executing.

defoldKit.annotations.repository

Where to get Defold API annotations. Three options are currently available:

• astrochili/defold-annotations
• mikatuo/defold-lua-annotations

defoldKit.annotations.autosync.defold

Automatically synchronize annotations for Defold API with the Defold editor version when needed at extension startup.

defoldKit.annotations.autosync.libs

Automatically synchronize annotations for dependencies when changes are detected in the .internal/libs folder.

defoldKit.extender.buildServer

Custom build server URL for bob.

Adds the --build-server ${buildServer} argument during bob command execution when the setting is not empty.

defoldKit.dependencies.email

User email to resolve dependencies.

Adds the --email ${email} argument during Resolve Dependencies and Bundle commands execution.

defoldKit.dependencies.authToken

Authentication token to resolve dependencies.

Adds the --auth ${authToken} argument during Resolve Dependencies and Bundle commands execution.

defoldKit.bundle.ios.debug.provisioningProfile

Path to the *.mobileprovision profile for Debug variant on iOS.

Adds the --mobileprovisioning ${provisioningProfile} argument during Bundle command execution.

defoldKit.bundle.ios.debug.identity

Code signing identity for the Debug variant on iOS.

Adds the --identity ${identity} argument during Bundle command execution.

defoldKit.bundle.ios.release.provisioningProfile

Path to the *.mobileprovision profile for Release variant on iOS.

Adds the --mobileprovisioning ${provisioningProfile} argument during Bundle command execution.

defoldKit.bundle.ios.release.identity

Code signing identity for the Release variant on iOS.

Adds the --identity ${identity} argument during Bundle command execution.

defoldKit.bundle.android.keystore

Path to the *.keystore file for Android.

Adds the --keystore ${keystore} argument during Bundle command execution.

defoldKit.bundle.android.keystorePass

Path to the *.keystore.pass.txt file for Android.

Adds the --keystore-pass ${keystorePass} argument during Bundle command execution.

defoldKit.bundle.android.keystoreAlias

Name of the alias from the keystore for Android.

Adds the --keystore-alias ${keystoreAlias} argument during Bundle command execution.

defoldKit.defoldEditor.commandTimeout

Timeout in seconds for Defold Editor HTTP commands.

defoldKit.defoldEditor.hotReloadOnChange

(Experimental)

Automatically sends the hot-reload command to the running Defold Editor when resource files change in the workspace.

This requires the project to be open in Defold Editor and a hot reload target to be available. If Defold Editor or the target is not available, the extension skips the automatic hot reload quietly.

Compatibility

It's possible to uncheck all the options during Defold Kit setup and still be able to sync annotations, bundle and deploy the game.

To use your own annotations solution you can skip the Annotations Syncing step or run the Clean API Annotations command.

Due to the flexibility of Defold Kit, it can be used in combination with the Defold Buddy extension, which adds additional sugars and features.

Logs

• The extension outputs logs to the Default Kit output channel.
• A locally running game with a debugger outputs logs to the debug console.
• A locally running game without debugger outputs logs to the Defold Engine terminal instance.
• Defold Editor streams to the Defold Editor: Console terminal.

Troubleshooting

Defold Kit doesn't see installed extensions and prompts me to install them again.

Make sure that these extensions are activated. Defold Kit cannot distinguish a deactivated extension from a missing extension due to the lack of the corresponding Visual Studio Code API.

The game launched, but the breakpoints don't work.

Make sure that you started the debugger on the game side.

Undefined global spine, imgui, iap and similar warnings for native extensions.

Many native extensions lack Lua annotations and have only *.script_api files (#36). Lua Language Server works only with Lua annotations so you have two options:

1. Make PR to the native extension's repository to add the Lua annotations.

2. Or just add spine or other native extension's namespace to the ignore list in the file .vscode/settings.json:

"Lua.diagnostics.globals": [
  ...,
  "spine"
],

Build in VS Code is fine, but Defold Editor fails with the message module 'debugger.debugger' not found.

This can happen if you call a method on the requested module in a single line. Watch defold/defold/7963 for updates.

-- ✅ Correct way to require in Defold
local debugger = require('debugger.debugger')
debugger.start()

-- 🚫 Wrong way, will fail in Defold Editor
require('debugger.debugger').start()

Limitations

Change breakpoints at runtime

Breakpoints can be set before launch and changed on pauses only. But there is a workaround, you can bind some input key to call debugger.requestBreak() and execution will pause on this line.

Watch tomblind/local-lua-debugger-vscode/#32 and local-lua-debugger-vscode/pull/67 for updates.

Debug on mobile devices

Local Lua Debugger is a local debugger. So you can't debug the game on the device by this way.