Aseprite Debugger for Visual Studio Code

Aseprite Debugger VSC is an Visual Studio Code extension, which enables debugging of Aseprite scripts and extensions.

• Features
  • Breakpoints
  • Variable Inspection
  • Logging
  • Error Detection
  • Script And Extension Support
• Setup Extension
  • Install Extension
  • Install Lua Language Support
  • Specify Aseprite Location
  • Specify Executable Architecture (optional)
• Setup VSCode Workspace for Debugging
• Source Location
• Commands
• Limitations
  • Editing Source Files Whilst Debugging
  • Aseprite Control
  • Extension Name
  • Lua Globals
  • Non Error Errors
  • Windows Only
• Built With
• Links
• License

Features

Breakpoints

Set breakpoints, step through code and view stack trace.

Variable Inspection

Inspect values of variables, including Aseprite objects.

Logging

View logs in VSCode Debug Console, instead of the Aseprite Console window.

Error Detection

Detect lua errors, and provide a full stacktrace of the problematic code.

Script And Extension Support

Debug either scripts or extensions.

Setup Extension

the Aseprite Debugger VSC extension require some setup after an initial install, please perform the below steps to ensure it will work properly.

Install Extension

The extension can be installed either via. the Visual Studio Marketplace, or by directly installing the .vsix file from the latest release, using the 'Extensions: Install From VSIX...' command.

Install Lua Language Support

This extension requires an vscode extension to provide language support for lua, like Lua by sumneko.

Make sure this extension, or a similar one, is installed before proceeding.

Specify Aseprite Location

Go to the Aseprite Debugger extension settings, and change the 'Aseprite Exe' property to a path pointing to an aseprite executable file.

If installed through steam, its location can be determined by finding aseprite in your library, right clicking it and pressing the Manage > Browse local files item.

Alternatively, the located aseprite executable can be added to path, and then the default value will work out of the box.

Specify Executable Architecture (optional)

This step is not neccessarry for the majority of users, since the default value is likely to be correct for the majority of aseprite installs.

Go to the Aseprite Debugger extension settings, and change the 'Aseprite Arch' property to the architecture of the aseprite executable pointed to by 'Aseprite Path'.

The architecture can be determined by going to 'Help' > 'About' in aseprite, and examining the version number. The last section will specify the architecture, (ex. Aseprite v1.3-x64 means architecture is x64)

Setup VSCode Workspace for Debugging

To set up a Visual Studio Code workspace for Aseprite Debugging, follow the below steps.

• go to the 'Run and Debug' menu in the activity bar, and press 'create a launch.json file'.
• Select the 'Aseprite' debugger.
• Select 'script' or 'extension' depending on your project type.
• Select the location of the lua source files, this will be a file or a folder depending on the project type. If the extension project type was selected, the source folder must contain a valid package.json.

Debugging the workspace will now run Aseprite with the debugger attached, and the script or extension intalled in Aseprite.

The first time the debugger is run, Aseprite will prompt the user for script permissions, make sure to select 'Give full trust to this script' for the 'Aseprite Debugger' script when this pops up.

Source Location

Lua source files do not have to exists in the aseprite scripts or extensions folder for the debugger to work, as all source files are automatically copied and removed on debug session starts and ends. This prevents the aseprite scripts and extensions folder being cluttered with .vscode and launch.json files, produced by a vscode workspace.

Commands

To retreive the latest stacktrace from the debugger, the command 'Aseprite Debugger: Show Latest Stacktrace' can be used. This will pause the debug session and show the stacktrace. The debug session will terminate when continued, after this command has been used.

This command is primarily useful for getting the stacktrace of an error not caught by the debugger, see Non Error Errors.

Limitations

Editing Source Files Whilst Debugging

If a source file is modified whilst debugging, the changes will not be reflected until the debug session has been restarted, as the source files are installed only on debug session starts.

Aseprite Control

The Aseprite application will freeze preventing any user interaction, when the debugger is paused. This is caused by the debugger needing to block the currently running lua script, which in turn blocks the entire Aseprite application process.

Extension Name

The debugged extension must not start with '!', as it would no longer be guaranteed for the debugger to be loaded as the first extension.

Lua Globals

The debugger lives inside the ASEDEB global namespace, so this value should not be modified in any scripts or extensions running in Aseprite. Additionally, the debugger overrides the global 'print' and 'error' functions, so these should not be reassigned, without calling the original print and error functions inside the reassigned functions.

Non Error Errors

The debugger is not able to catch an error, if it was not caused by a call to 'error'. If an error is hit, and it is not caught by the debugger, you can use the 'Aseprite Debugger: Show Latest Stacktrace' as a workaround for getting the stacktrace of the error, provided no other scripts have run after the error was thrown.

Windows Only

The debugger currently only works on windows, as aseprite is not able to load shared libraries on macos or linux, which is required for the debugger to work.

Built With

• Aserite Debugger
• See package.json for node modules.

Links

Github

Visual Studio Marketplace

License

See LICENSE