Setting up Visual Studio for Unity
This includes contributions from the Unity forums by benblo and Lka (collected from various threads in the Unity forums)
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?
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.
- 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).
End of obsolete text.
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!
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:
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. 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:
- Download Junction from http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
- Extract junction.exe from the zip archive and move it to your Windows installation folder, normally C:\Windows.
- Import the package and change line 17 in CreateVisualStudioSolution.cs to
<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)
Consider getting the Consolas Fontpack which looks much better than Courier.
Microsoft Visual Studio 2005 IDE Enhancements
You might also want to install:
InternetExplorer Developer Toolbar
If you’re also developing ASP.NET content, you may consider downloading and installing:
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.
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.