Setting up Visual Studio for Unity

From Unify Community Wiki
(Difference between revisions)
Jump to: navigation, search
(Using Visual C# Express As the code editor)
(Add-On for Convenient Adding of Unity Scripts)
Line 17: Line 17:
  
 
NOTE: Now that Unity has Visual Studio integration (it can create a solution file of its own), this part is no longer recommended and is only kept for "historical reasons" (someone might still find it useful). Instead of using this, since Unity 2.6, you can simply use menu: Assets/Sync Visual Studio project (works both on Mac and PC).
 
NOTE: Now that Unity has Visual Studio integration (it can create a solution file of its own), this part is no longer recommended and is only kept for "historical reasons" (someone might still find it useful). Instead of using this, since Unity 2.6, you can simply use menu: Assets/Sync Visual Studio project (works both on Mac and PC).
 +
 +
'''WARNING''': I believe the ''Note'' above is not clear about its scope. As far as I can tell, ''everything'' past this paragraph, down to the line saying: "''Congratulations – now you can code C# for Unity''" is obsolete. In other words, once you have done the step: ''Assets/Sync Visual Studio'' - you're done. Unity will have created a .csproj file in your project directory. If you click on that, it will open Visual C#, and you will have all your scripts available, with all the desired features, Intellisense, tooltip help, etc. If I knew how, I'd move it to another page. Anyone else care to? Anyway, begin obsolete text.
 +
 +
----
 +
  
 
Download and install
 
Download and install

Revision as of 22:02, 9 March 2010

Author(s):
Jashan Chittesh
This includes contributions from the Unity forums by benblo and Lka (collected from various threads in the Unity forums)

Contents

Setting up the Environment

Basic VMWare (or Parallels) and Visual Studio installation

Set up a VMWare Image with Windows XP and Visual Studio 2005 or 2008 (any edition from Express to Team System should do fine). You can probably also use Windows Vista or Windows 2003 Server. You can find the Express Edition for free at: www.microsoft.com/express/vcsharp/

This article assumes that you are already familiar with Visual Studio. If not, it's probably a good idea to do some Visual Studio tutorials first, before continuing (they should be available in the Visual Studio documentation).

I'm using VMWare, but others are using Parallels, so that should also work just fine.

Add-On for Convenient Adding of Unity Scripts

NOTE: Now that Unity has Visual Studio integration (it can create a solution file of its own), this part is no longer recommended and is only kept for "historical reasons" (someone might still find it useful). Instead of using this, since Unity 2.6, you can simply use menu: Assets/Sync Visual Studio project (works both on Mac and PC).

WARNING: I believe the Note above is not clear about its scope. As far as I can tell, everything past this paragraph, down to the line saying: "Congratulations – now you can code C# for Unity" is obsolete. In other words, once you have done the step: Assets/Sync Visual Studio - you're done. Unity will have created a .csproj file in your project directory. If you click on that, it will open Visual C#, and you will have all your scripts available, with all the desired features, Intellisense, tooltip help, etc. If I knew how, I'd move it to another page. Anyone else care to? Anyway, begin obsolete text.



Download and install this very practical addon

What you can use this for is conveniently add all scripts from a folder in one single "go".

Note: When you want to use this under Visual Studio 2008, you have to make sure that in your "My Documents" (or "Eigene Dateien") folder, in the "Visual Studio 2008" folder, there’s an "Addins" folder that contains the two files AddDirectoryContent.AddIn and AddDirectoryContent.dll. In AddDirectoryContent.AddIn, make sure that 8.0 is set to 9.0:

<Extensibility xmlns="http://schemas.microsoft.com/AutomationExtensibility">
	<HostApplication>
		<Name>Microsoft Visual Studio</Name>
		<Version>9.0</Version>
	</HostApplication>
[…]

Thanks to benblo for this tip, see also: http://forum.unity3d.com/viewtopic.php?t=7062#50996

According to psynopticM, this may not work under Visual Studio 2008 Express: http://forum.unity3d.com/viewtopic.php?p=74325#74288

Mapping the Unity Project to be Accessible from Windows

If you haven’t done so already, set up your Unity projects in a folder that is accessible to your Windows XP VMWare Installation. Personally, I’m using Documents/Games in my home-folder and have mapped my home-folder to drive I: on Windows XP via a network share. Under Games/projectname I have my projects. So I can access my Unity projects on Windows XP via I:/Documents/Games/projectname.

The Reference to UnityEngine.dll and UnityEditor.dll

Copy UnityEngine.dll and UnityEditor.dll to your Games-folder. To do that, open the console on Mac OS, and do something like (depending on your folder-structure):

cp /Applications/Unity/Unity.app/Contents/Frameworks/UnityEngine.dll /Users/yourusername/Documents/Games/
cp /Applications/Unity/Unity.app/Contents/Frameworks/UnityEditor.dll /Users/yourusername/Documents/Games/

(or, just locate Unity in your Applications folder, right-click: "show contents", then browse to Frameworks, and copy UnityEngine.dll and UnityEditor.dll wherever you like.)

Documentation for UnityEngine.dll and UnityEditor.dll

Wanna have this?

VS inline doc.png

Just drop these two files in the same folder where you put the DLLs (Unity 2.1 version).

Note: After Unity 2.6 and the built-in Visual Studio integration, you'll want to drop the files in your "Unity\Editor\Data\lib" folder. If you had an existing Visual Studio project, you will need to drop and re-add the UnityEditor.dll and UnityEngine.dll references (from the lib folder just listed) before the documentation will show up.

Note: In Unity 2.6, you need to make a copy of "UnityEngine.xml" and name it "UnityEngine-Debug.xml". Place in same folder.

You'll get inline documentation for all documented classes, methods and enumerations, both for UnityEngine and UnityEditor namespaces.

For some methods you'll even have parameter documentation. Basically, the newer the method, the more likely it is to have parameter docs... UT really is doing their homework so don't hesitate to nag them (by filing "documentation" bug reports) to keep improving the docs, they are a huge asset to the strength of Unity!

Creating a Local Project for Visual Studio

Create a project on your local C: drive (to avoid security exceptions you may not wish to use a network drive).

In that project, create a folder lib and put the UnityEngine.dll into that folder. Add this as a reference.

Right-click "References" in the project explorer, select "Add reference", "Browse", browse to where you put the DLLs, add them (you can select both at once). XML documentation will automatically follow. For later projects you can use the "Recent" tab instead.

Tips

  • Always leave the DLLs + XML docs in the same folder, this way when a new Unity release comes up, all you'll have to do is overwrite them and all your projects will stay up to date. If you don't want that, create a folder for each DLL version, or even create project-specific copies.
  • At this point, it might be a good idea to export your project to a template, so for later projects you can directly create a Unity project with everything referenced. I would post my own template but I doubt it would cross over to a different machine.


I’m using a Windows application so I could do basic debugging by creating some buttons to start actions (thanks to Lka for a tip how to do this, see: http://forum.unity3d.com/viewtopic.php?t=7062#50779 ).

Folder Setup in Unity Project

In your Unity project, create your own Asset folder if you don’t have it, yet (I’m using Working Assets). Under that folder create a folder specifically for your C#-Unity-Scripts (I call it Scripts). Add a C# script there in Unity.

In your VS.NET 2005 or 2008 project, add a folder Projects/projectname. Select folder projectname and use Tools / Add Directory Content (this is what you downloaded and installed the plugin for in step 2).

Congratulations – now you can code C# for Unity in VS.NET 2005 / 2008. With Intellisense... and inline docs!

Important note about file renaming

If you need to rename a behaviour (non-behaviour scripts don't matter), make sure to do it in Unity! If you rename it in VS, Unity will consider it a new file, and all references to it (components) will be lost.

Then in VS, exclude the script, display all files in the solution explorer, include the new renamed script, and finally rename the class in the editor (and enjoy some sweet refactoring :). It's a tad tedious, but once you get the habit it's not that bad.

Note that if you forget and rename in VS, all is not lost. Just find the components in Unity, you'll see all their properties are still there but the script reference (it will say "Missing Mono Behaviour"). Just drop the renamed script in the script box, and yay, you didn't lose any property!

Version Control

UT's Asset Server

The best solution to version control for Unity is probably UT's Asset Server. I'm using this now and thus I have dropped Subversion, but for reference for people who would prefer to use Subversion:

Subversion

If you want version control, you may want to try Subversion: http://subversion.tigris.org/

It’s very convenient to use on Windows with TortoiseSVN: http://tortoisesvn.tigris.org/

One important note: In the setup I’m using, I don’t version control the actual VS.NET project. There’s not really much worthwhile version controlling in there, anyways. Instead, I directly put the script files from my assets folder under version control. I have those on a share mapped to a drive. Don’t get confused when TortoiseSVN doesn’t automatically, create the relevant icon overlays, you need to change the settings for that to work correctly: Right click on some item in the explorer to get the context menu, go to TortoiseSVN/Settings. In there, under Look and Feel, you find Icon Overlays, and there, under Drive Types, you’ll find Network Drives is not checked. Check it, and the world is wonderful again ;-)

There is also a Subversion-plugin for Visual Studio.NET 2005, but personally, I didn’t really like it. If you still want to give it a try: http://ankhsvn.tigris.org/.

If you want a great SVN plugin for VS.NET you should use VisualSVN[1]. It is not free, but pretty cheap and it works like a charm.

I would not recommend using Subversion for version controlling the binary assets - I'd only use it for scripts and textfiles. Some people (see this posting for an example) have reported trouble someone along the way when version controlling Unity projects (including the binary assets) with Subversion, so you have been warned ;-)

Subversion, another take

This is drawn mostly from experiences with using Unity and SVN at the Global Game Jam 2009.

As said above, scripts textfiles and also assetfiles work well with Unity. You can also version scenes and prefabs, but since they are binary and cannot be merged - you will have to take care when a conflict arises. Typically this will mean that you have to update, make the changes you want again and then commit. Makes a good case for commiting often!

The worst part to use SVN for is the Library folder. The cache should definately be ignored, and most of the other stuff - including metadata - changes so often that you always get conflicts. What we did was to ignore the library folder completely. This has the unfortunate effect that references to scrips/prefabs/assets for things in the scenes and prefabs does not get saved. Simple properties do - just not references. This lead to tedious work of recreating what others have set up in your local copy. We remedied that by having one machine that was the master machine. On that machine we integrated everything, build the game and made sure it ran. When this was over we shut down Unity. Zipped the library folder and put that in SVN. Others could then update to get the zip and all changes, shut down Unity, remove the library folder and unpack the new one. Then they would be up and running. Somewhat tedious, but it worked for us.

Some nice Add-Ons to Consider

One click Unity & Visual Studio integration (Mac)

Check out Lucas Meijer's blog post which also has a very nice Unity package which makes integrating Unity with Visual Studio even easier: http://lucasmeijer.com/posts/one-click-unity-visual-studio-integration/

One click Unity & Visual Studio integration (Windows)

Go to Lucas Meijer's blog post and download his Unity package: http://lucasmeijer.com/posts/one-click-unity-visual-studio-integration/

Windows is not able to create symbolic links in the same way as OSX so Meijer's script needs to be modified a little:

<csharp> ProcessStartInfo t = new System.Diagnostics.ProcessStartInfo("c:\\WINDOWS\\junction.exe", "VisualStudio/AssetsLink Assets"); </csharp>

Now you can re-export the package for future use in other Unity projects. (Verified on Vista, should work the same for Windows XP)

Consolas Fontpack

Consider getting the Consolas Fontpack which looks much better than Courier.

Don’t forget to switch on ClearType – it’s not on by default. See instructions here: English German

Microsoft Visual Studio 2005 IDE Enhancements

You might also want to install:

Microsoft Visual Studio 2005 IDE Enhancements

InternetExplorer Developer Toolbar

If you’re also developing ASP.NET content, you may consider downloading and installing:

Internet Explorer Developer Toolbar

UML Modelling with UModel

If you’re developing complex applications, you may consider using UML to not model the various levels of the application in a more abstract manner than just code. I found Altova Umodel a very nice tool because it supports round-trip engineering and can be smoothly integrated into Visual Studio .NET 2005 and 2008.

Altova UModel

VERY IMPORTANT: Use UModel only with version control (or make frequent backup copies of the relevant UModel project files). I almost lost a few hours of work because I rearranged the folder structure inside of Unity on time, and another time because somehow I opened VS.NET 2008 while my network connection from the VMWare to my Mac somehow was broken. The result was that UModel did not find any classes anymore and automatically removed all the classes from all the diagrams. Fortunately, I made a copy of the UModel project file before saving this disaster. So make sure you check in the UModel project file after you’ve worked on it, so when UModel does weird things, you don’t lose your precious time...

Note: This never happened to me again, so I'm not saying UModel is buggy or something, but it's just wise to be a bit cautious with software ;-)

Using Visual C# Express As the code editor

If you are using Windows and are editing C# scripts in Visual Studio or C# Express, the new "Assets->Sync VisualStudio Project" option is nice. However, using Visual C# Express edition, you are limited in that you cannot double-click on a script or warning/error in Unity and have it open in Visual C# Express. Here is a workaround for that limitation:
1) Download ClassExec and extract to a folder of your choosing.
2) Create a batch file and put the following line :

"<path>\classexec.exe" %1 --class .cs

3) In Unity, under Edit->Preferences->External Script Editor, select the batch file you created above.
4) In Unity, after using 'Assets->Sync VisualStudio Project' and opening the solution in Visual C# Express, double clicking a script or a warning/error in the console will cause it to open in the same instance of Visual C# Express, allowing you to enjoy easy integration between the two IDEs.

Personal tools
Namespaces

Variants
Actions
Navigation
Extras
Toolbox