Using Sublime Text as a script editor

From Unify Community Wiki
Jump to: navigation, search

Sublime Text is a popular cross-platform text and source code editor. It is extendable and its community has contributed numerous packages (plugins/extensions/addons) for Sublime Text.

Contents

Basic setup

  1. Sublime Text can be found at its official website. Download and install.
    • Mac users should refer to step 4 before proceeding to step 2.
  2. In Unity, change your External Script Editor to Sublime Text:
    • Edit > Preferences > General or
    • Edit > Preferences > External Tools.
  3. Unity should now open Sublime Text whenever you double-click a script (or any text file).
  4. To make Sublime Text jump to the line that causes an error/warning:
    • Windows: You should set the External Script Editor Args field to: "$(File)":$(Line), so that Sublime Text jumps to the line where the error, warning or notice occurs, when they are double clicked upon.
    • Mac OS X: If the previous External Script Editor Args is not available in your version of Unity, there is a workaround using a shell script, save this to a file, make it executable (if required) and set that file as the script editor in Unity (Linux users running the Windows version using Wine may also do this):
#!/bin/sh
 
# Change '/opt/sublime_text/sublime_text' to the path to your executable of Sublime Text.
 
# Sublime Text 2:
# "/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl" $1:$2:$3
 
# Sublime Text 3:
"/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" $1:$2:$3
 
echo "Opening '$1' on line '$2' column '$3' with Sublime Text"
exit 0

Project feature setup

Creating a project file has some advantages:

  • Context - specify your script folder(s) for easy search & navigation between your files
  • Settings - filter out irrelevant files (e.g., .meta files)

To create a project, use File > Open Folder... to open your Unity project folder (parent of the Assets folder). Then, create a My Awesome Game.sublime-project file in your Unity project folder with Project > Save Project As....

Now edit that .sublime-project file with Project > Edit Project. For example, the following edit will include only the Assets/Scripts folder and exclude .meta and .dll binary files:

{
	"folders":
	[
		{
			"path": "Assets/Scripts",
			"file_exclude_patterns":
			[
				"*.dll",
				"*.meta"
			]
		}
	]
}

Package Control

Package Control is a Sublime Text package that allows for easy package management to find and install other packages. Follow the installation instructions on their site.

To access the Package Control functions:

  • Preferences > Package Control menu (ST3), or
  • Open the Command Palette
    • By one of:
      • Tools > Command Palette menu
      • Mac: Command+Shift+P shortcut
      • Windows/Linux Ctrl+Shift+P shortcut
    • Then start typing in "Package Control" (without the quotes).

Syntax highlighting

Unity C# and JavaScript syntax highlighting

Install the C# package (if not installed already) and the Unity3D Syntax Highlighting package, either by using Package Control or by cloning the package using Git from Github.

Once installed you can select View > Syntax > Unity3D and then either Unity C# or Unity JavaScript. You may also want to select View > Syntax > Open all with current extension as... so that Sublime Text will always use Unity syntax highlighting when viewing C# or JavaScript Files.

Other C# syntax highlighting compatibility

Note that using Unity C# with Open all with current extension as..., Sublime Text will not differentiate between Unity C# files and non-Unity C# files (both use the .cs extension). One way to avoid this is to install the ApplySyntax package and add the following to its settings:

"syntaxes": [
...
{
	// Unity 3D C# format detection.
	"name": "Unity3D/UnityC#",
	"match": "all",
	"rules": [
		{"file_name": ".*\\.cs$"},
		{"contains": "using UnityEngine;\n"}
	]
}
...
]

(The "Unity3D" package might still lay compressed within Sublime Text's "Installed Packages" folder, which contains "UnityC#.tmLanguage" file that ApplySyntax will be looking for within non-existant "Packages/Unity3D" folder)

Boo syntax highlighting

Install one of:

Unity Shader syntax highlighting

Install one of:

Code completions

For simple, predefined completions, install one or more of:

The above completions, however, are less than satisfying because they do not work across dot notation. Please read the other options below for ST2 and ST3 before deciding what to do.

Advanced C# completions for Sublime Text 2

Instead of—or in addition to—the above Unity-specific completions, you can also install the following package for dynamically reading .dll files for completion data:

Do not install the CompleteSharp version available through Package Control. The one on Package Control is the original one by "quarnster" but the version by "ewilde" (linked above) includes an already-compiled "CompleteSharp.exe" which makes it easier overall to install.

You can install CompleteSharp via Git as described on its Github page, or you can download the Zip files and reassemble the sub-projects into their respective folders:

  • Note that these links are to the latest master version of each project and each contains newer code than what just a Git clone of the top project will get you:
Sublime Text 3 note: If you are trying to get CompleteSharp to work in ST3, you will need the latest code from each sub-project listed above (the latest are already linked for you above). A better option for ST3, however, is described in the next section.

To find your Packages folder to install to, go to Preferences > Browse Packages....

After CompleteSharp is installed, edit either your user settings or your project settings to add in the Unity assemblies and other libraries your project uses. To edit CompleteSharp settings:

  • If using Sublime Text project feature: Project > Edit Project
  • If not using Sublime Text project feature: Preferences > Settings - User

The code below represents a typical minimal setup. More .dll files can be added if using packages that include them. Make sure, however, that all these files still exist in your project and your version of Unity. This list is outdated regarding the ScriptAssemblies folder. CompleteSharp may not work at all until the list of .dll files is entered without error.

... represents other possible content between JSON elements.

Replace <path-to-Unity-folder> with the path to your Unity folder (double slashed like the rest) such as C:\\Program Files\\Unity\\Editor\\Data.

{
	...
	"folders":
	[
		...
	],  //<- comma required
	...
	"settings":
	{
		...

		// Uncomment the next line for OS X/Linux, if "mono" does not launch Mono in the Terminal.
		//"completesharp_mono_path": "/Applications/Unity/MonoDevelop.app/Contents/MacOS/bin/MonoDevelop",

		// Possible default directory paths for Unity:
		// Windows: C:\Program Files\Unity\Editor\Data\
		// Windows 64-bit: C:\Program Files (x86)\Unity\Editor\Data\
		// Mac OS X: /Applications/Unity/Unity.app/Contents/Frameworks/

		"completesharp_assemblies": [
			"<path-to-Unity-folder>\\Managed\\UnityEngine.dll",
			"<path-to-Unity-folder>\\Managed\\UnityEditor.dll",
			"<path-to-Unity-folder>\\Mono\\lib\\mono\\unity\\UnityScript.dll",
			"<path-to-Unity-folder>\\Mono\\lib\\mono\\unity\\System.Core.dll",
			"<path-to-Unity-folder>\\Mono\\lib\\mono\\unity\\System.dll",
			"<path-to-Unity-folder>\\Managed\\nunit.framework.dll",
			"<path-to-Unity-folder>\\Mono\\lib\\mono\\unity\\mscorlib.dll",
			"${project_path:Library}\\ScriptAssemblies\\Assembly-CSharp.dll",
			"${project_path:Library}\\ScriptAssemblies\\Assembly-CSharp-Editor.dll",
			"${project_path:Library}\\ScriptAssemblies\\Assembly-UnityScript-Editor.dll",
			"${project_path:Library}\\ScriptAssemblies\\Assembly-CSharp-firstpass.dll"
		],
		"completioncommon_inhibit_sublime_completions": true,
		"completioncommon_shorten_names": true

		...
	}
	...
}

After saving these settings, this should automatically reload CompleteSharp's python scripts and have its autocompletion ready. To see any errors, open the console by using Ctrl+` (tilde key).

Advanced C# completions for Sublime Text 3

In ST3, you can replace all of the above completion packages (Unity Completions and CompleteSharp, etc.) with a far better tool that will give Sublime Text capabilities similar to MonoDevelop or Visual Studio—including dynamic interpretation of .cs source files for code completion (but most notably missing are the API documentation excerpts next to the autocomplete hints):

Go to the OmniSharp web page (linked above) and follow their instructions for installing it for Sublime Text. (Currently, this requires two packages available via Package Control, and other settings.)

  • The listed requirement for the Mono Development Kit does not appear to be required (perhaps because Unity is installed).

Restart ST3 for the OmniSharp local server to start running correctly.

Note that if you are using the Project feature of Sublime Text (strongly recommended), you must add the location of your Unity project .sln file to the .sublime-project file (Project > Edit Project):

{
	"folders":
	[
		{
			"follow_symlinks": true,
			"path": "Assets/Scripts",
			"file_exclude_patterns":
			[
				"*.dll",
				"*.meta"
			]
		}
	],
	"solution_file": "./My Awesome Game.sln",
}

OmniSharp adds several commands to the context menu in Sublime Text. Note, however, that when clicking through a bunch of these commands in a row, the OmniSharp server can stop functioning (as of v1.9.6). Thus, be careful and on the lookout for things that may stop the server. Restarting ST3 should restart the server.

Other packages of interest

Community Support

See "Using Unity with Sublime Text" forum thread

Personal tools
Namespaces

Variants
Actions
Navigation
Extras
Toolbox