Solar2D Editor

Solar2D Editor (rebranded Corona Editor) is the official Solar2D plugin for Sublime Text. Designed to make building apps even easier by adding functionality to Sublime Text to improve developer productivity.

Sublime Text Version

Sublime Text 3 is required to use Solar2D Editor.

Installation Instructions

1. Install the Sublime Text Package Control plugin if you don't already have it using Tools > Command Palette... > Install Package Control
2. When that's installed, in Sublime Text choose: Tools > Command Palette... > Package Control: Install Package
3. Find Corona Editor by typing in the search field, click on it to install it
4. Restart Sublime Text to see the new features

If you want to help test the latest development version of Solar2D Editor you can configure Package Control to grab it instead of the official release version by following these steps:

1. In Sublime Text choose: Tools > Command Palette... > Package Control: Remove Package and uninstall any installed version of Corona Editor
2. Choose: Tools > Command Palette... > Package Control: Add Repository
3. Enter https://github.com/coronalabs/CoronaSDK-SublimeText
4. Choose: Tools > Command Palette... > Package Control: Install Package
5. Find CoronaSDK-SublimeText (or, on some machines, Corona Editor - Daily Build) by typing in the search field, click on it to install it
6. Restart Sublime Text or reopen any .lua files to see the new features

Alternatively, if you are comfortable doing manual installs of Sublime Text plugins and want to run the latest development version, you can download the plugin from https://github.com/coronalabs/CoronaSDK-SublimeText/archive/master.zip

If you install the tip from Github please report any issues using the Issues page on Github: https://github.com/coronalabs/CoronaSDK-SublimeText/issues

Using the Plugin

After restarting Sublime Text you'll have several new features available in the Solar2D Editor menu and in the context menu when editing Solar2D .lua files. Most of the features of the plugin rely on the current Syntax setting so when editing files you should use View > Syntax > Lua (Solar2D) command to set the correct syntax for the file. You will probably also want to change Sublime Text's default for .lua files by choosing View > Syntax > Open all with current extension as... > Lua (Solar2D) when you have a .lua file open in the editor.

If the syntax option is set correctly you'll see it displayed in the bottom righthand corner of the Sublime Text window.

There are several Sublime Text User Preferences that can be set to fine tune the behavior of the plugin. You can find information on setting User Preferences here http://www.sublimetext.com/docs/3/settings.html.

Debugger

Debugger allows code to be single stepped, variables to be examined and breakpoints to be set. You can run the debugger using the Solar2D Editor menu from any file in the project and it will automatically find main.lua. Right click on a code line in the editor and choose Toggle Breakpoint to turn a breakpoint on or off. Select the name of a variable and choose Inspect Variable from the context menu to see its value.

The following keys also control the Debugger:

A simpler alternative to the Build command in Sublime Text is the Run Project command in the Solar2D Editor menu (or Super+F10). It doesn't have all the bells and whistles of the build system but it is quick and easy. It is also better at finding your project's main.lua if you aren't using Sublime Text's projects. Super+B (usually bound to the Build command) is now bound to the Run Project command for Solar2D Lua files.

On macOS, if you install Solar2D in /Applications without changing the default name, it will use the highest numbered (most recent) build to run the project (to change this behavior, see corona_sdk_simulator_path below).

Preferences

• corona_sdk_simulator_path (default: system dependent)

  Set this to the path of your Solar2D Simulator if it's not installed in the default location for your operating system (remember to double the backslashes in Windows paths). You can also set this in the build.settings file of individual projects to customize the version of the Solar2D Simulator that is used for each project (note that the Lua syntax for the build.settings file is different to the JSON syntax of the Sublime Text preference files in that the name of the preference is not quoted in Lua).

• corona_sdk_simulator_show_console (default: false)

  Set this to true to have the Solar2D Simulator Console be shown when running a project with Super+F10 (or Super+B).

Current Gotchas

• If you Run the project and it doesn't hit a breakpoint, you'll have to stop and restart to regain control (in particular, setting a breakpoint on a line of code you know is being executed wont stop the program).
• Single stepping through "internal locations" is tedious.
• There's an implicit breakpoint set on the first line of main.lua so to hit your own first breakpoint you need to run once to start the debugger and stop on the first line then run again to continue until you hit your own breakpoint.
• If you create rows and columns in using Sublime Text's View > Layout command in the current tab, the debugger wont create its own panes and its functionality will be reduced.

Completion

Completion works for all API calls and constants (correctly handling periods in the name). Fuzzy matching is optionally done to increase the chances of finding the item you are looking for. Completion relies on the current Syntax setting so when creating new files you should use View > Syntax > Lua (Solar2D) command to set the correct syntax for the new file. You will probably also want to change Sublime Text's default for .lua files by choosing View > Syntax > Open all with current extension as... > Lua (Solar2D) when you have a .lua file open in the editor.

Preferences

• corona_sdk_completion (default: True)

  If you don't like Solar2D Editor's completion you can turn it off entirely using this preference.

• corona_sdk_use_fuzzy_completion (default: True)

  Turn off "fuzzy completion" and just complete based on the characters typed so far as a prefix.

• corona_sdk_complete_periods (default: True)

  Solar2D Editor turns off the special meaning of periods as "word separators" in Sublime Text to make Solar2D completions work better. If you like to use cursor movement keys like "Alt+Arrow" to move to the periods in function calls you might want to turn this off. The most obvious effect of turning it off is that when you type a period all the completions disappear until you type another character.

• corona_sdk_use_docset (default: public)

  Choose which completion set you want to use. Can be one of public (the default), legacy(deprecated) or daily(deprecated).

• corona_completions_strip_white_space (default: False)

  Set to true if you want items to be completed with minimal whitespace included.

Current Gotchas

• The order of items in the completions popup seems a little odd but is due to Sublime Text's "fuzzy" matching

• Some of the completions may have minor errors with nested optional parameters due to the way they are automatically generated.

Documentation Lookup

Documentation can be called up by placing the cursor on an API call (or selecting it) and either hitting F1 or choosing Solar2D Docs from the context menu. Lua keywords will be looked up in the Lua documentation. If the context of something isn't recognized, a search of the Solar2D documentation will be initiated.

Current Gotchas

• Note that right clicking on an item wont move the cursor there so you can't right click on a term that's not at the insertion point and then pick Solar2D Docs from the context menu as it's the position of the text cursor that determines what's looked up (left click on the item first)

Snippets

A selection of commonly used code fragments and templates is available via the Solar2D Editor > Snippets menu. Selecting an item from a submenu will insert its code at the current insertion point in the file.

A default set of snippets is created in the Sublime Text support folder Packages/User/Corona Editor/Snippets. You can create your own folders and files to add to the default set. Files should either be Sublime Text .sublime-snippet files or plain text files. The contents of plain text files are just inserted when chosen unless they exactly match a completion entry in which case the completion is looked up and they work like a normal completion (you can tab between the arguments) which provides a way to make menus of hard to remember API calls.

Build System

The Run Project command in the Solar2D Editor menu (or Super+B or Super+F10) is a simpler alternative to the Build command in Sublime Text (see above for more information).

Syntax Highlighting

Syntax highlighting of Lua with Solar2D calls is done (choose View > Syntax > Lua (Solar2D) to enable this). You will probably also want to change Sublime Text's default for .lua files by choosing View > Syntax > Open all with current extension as... > Lua (Solar2D) when you have a .lua file open in the editor.

Miscellaneous

• A shortcut to the Sublime Text Goto Anything... function list has been added to the context menu as Function Navigator.... This lists the functions defined in the current file and choosing one takes you to that definition.
• The Solar2D Editor menu has a Show/Hide Build Panel command to toggle the visibility of the Build Results panel (which displays the output of the Simulator). Note that hiding the panel clears its contents.

Reporting Issues

You can find discussion about Solar2D Editor on the forums.

If some aspect of the plugin doesn't behave as expected be sure to include any console output when reporting the problem. You can view the console using View > Show Console and copy and paste the information displayed there.

Known Issues

• Syntax highlighting is incorrect for function definitions that look like:

local back=simplebutton.create("Back",function() menumanager.openMenu("main") end)

Platform Specific Advice

Mac

You may want to set the Use all F1, F2, etc. keys as standard function keys option in System Preferences > Keyboard to make using F10 and F11 easier for the debugger. Alternatively you may want to reassign the keys used to drive the debugger; information on how to this can be found at http://www.sublimetext.com/docs/key-bindings

Thanks

Many thanks to the Solar2D users who have provided feedback and suggestions to make Solar2D Editor even better. Particular thanks to personalnadir, develephant, givemeyourgits and landoncope for their contributions and help.