Unity 3D & C#

Unity3D is a powerful suite of tools (Project IDE, Code IDE, run-time) for game development.

As always, RivelloMultimediaConsulting.com/unity/ will be the central location for deep articles and tutorials, Facebook.com/RivelloMultimediaConsulting (like us!) will engage the growing RMC+Unity community, and for the latest opinions and cool links follow me at Twitter.com/srivello.

There is incredible momentum in the Unity3D product and its community. I recently posted “The Best C# Code Naming Conventions” and “Unity Best Practices”.  I came across one best-practice that requires a bit of setup, so here it is; using symlinks for game development.

Unity’s Weaknesses

The Unity Editor IDE does not facilitate collaboration between developers nor collaboration between projects.

• 1.Want to use version control? Git? SVN? You can, but it is not easy. While certainly possible I suspect these strategies are purposefully kept difficult to encourage developers to purchase the Unity Collaboration & Unity Asset Server packaged features which are available for sale on the official Unity Asset Store.
• 2. Want to share your code between projects (local or remote)? You can, and it is easy with custom packages (here is how), but it is not great. You are sharing a COPY of your code. Update your code and you have to re-export and re-import it everywhere. Difficult! I suspect its difficult for the same reason as above.

I’m happily surprised how great Unity Indie (free license) is. I really am. Yet, I’m still disappointed at these shortcomings.

Fortunately there are some free workarounds.

Workaround 1. Version Control

You can indeed use any version control to collaborate with other developers (local and remote). Its a bit tricky to setup (here is how, and here is some GIT advice). Enjoy!

Workaround 2. Symlinks

On Window (here1, here2), MacOSX (here), and Linux (here) you can create symlinks. In computing, a symbolic link (also symlink or soft link) is a special type of file that contains a reference to another file or directory. A symlink is SIMILAR to a shortcut (Windows) or alias (Mac). You click the symlink in Finder (Mac) or Windows Explorer (Windows) and it opens the original file. You’ve probably used them often. The added benefit of symlinks is that applications (most) cannot tell the difference between a symlink and the original file or folder. It is this difference we will exploit here.

Here are the instructions for using Symlinks with Unity on MacOSX to share code between three unity projects. The setup would be similar on Windows/Linux. Give it a try on your platform and post below with any suggestions!

Demo

Create Your Code Library

1. Open the Unity Editor IDE
2. File -> New Project… -> “/Users/srivello/Desktop/MyUnityLibrary”
3. Assets -> Create -> Folder -> “MyUnityLibraryScripts”. This folder (and any subfolders) will be the location of 100% of the code you want to share. Let’s add one file to share.
4. Assets -> Create -> C# Script -> “MyUnityLibraryScript” with the contents shown below.
5. Drag “MyUnityLibraryScript” into “MyUnityLibraryScripts” within the Project window.
6. File -> Save Project
7. File -> Save Scene As… -> “MyUnityLibraryScene”

[actionscript3]<br />//SAMPLE CONTENTS FOR THE CLASS.<br />//ANY VALID CODE IS A GOOD TEST<br />public class MyUnityLibraryScript<br />{<br />//Test<br />public string sampleVariable = "Hello World";<br />}<br />[/actionscript3]

Create Your Game 1 Project

1. Open the Unity Editor IDE
2. File -> New Project… -> “/Users/srivello/Desktop/MyUnityGame1”
3. Assets -> Create -> Folder -> “MyUnityLibraryScripts” with the contents shown below.
4. File -> Save Project
5. File -> Save Scene As… -> “MyUnityGame1”

Create Your Game 2 Project

• Repeat the same steps for ‘MyUnityGame2’.

And now here are a few solutions to ‘share’ the code between the projects. Ideally A would work in all cases on all operating systems. I’m still working on that.

A. Create Symlink

UPDATE: A) The following fails on mac. Mac does not allow ‘hard links of folders’ which Unity wants. Mac can do soft links but the Unity Editor IDE does not recognize ‘soft links of folders’. Anyone have the following 3 lines working on PC? Share the lines as a comment below. Anyone have a workaround for MAC?

1. Open the native MacOSX application ‘Terminal.app’
2. Type “ln -s /Users/srivello/Desktop/MyUnityLibrary/Assets/MyUnityLibraryScripts/ /Users/srivello/Desktop/MyUnityGame1/Assets/MyUnityLibraryScripts” (without the quotes). This creates a symlink from the EXISTING folder in MyUnityLibrary to the NEW (symlink) folder in MyUnityGame1. Use absolute paths as I show here.
3. Type “ln -s /Users/srivello/Desktop/MyUnityLibrary/Assets/MyUnityLibraryScripts/ /Users/srivello/Desktop/MyUnityGame2/Assets/MyUnityLibraryScripts” (without the quotes).

B. Use Rsync

• You can download this free Mac App and it works great. (https://www.macupdate.com/app/mac/20983/arrsync) But you have to manually click ‘sync’ whenever you want to refresh the folder across your projects. Not bad. Anyone have a better workaround?

Summary

So what have we done here? Now both MyUnityGame1 project and MyUnityGame2 project have access to the code from MyUnityLibrary. Currently we have just one class in there. ANY of the 3 projects can be opened and you can edit/add new files. They all share a reference to the original MyUnityLibraryScripts folder. No need to COPY scripts! Great. No need to Export packages or Import packages! Great.

Gotchas!

The above workflow solves much of the confusion and problems reported by the community. However there are still some issues with my technique. Here are a few of the issues;

• Symlinks + Unity ON MAC don’t work together!!! Here is the full story – http://forum.unity3d.com/threads/104374-Using-links-%28Sym-amp-Hard%29-to-create-a-common-folder-for-all-Unity-Projects
  
• Prefabs – There are issues with prefabs via symlinks. Link URL?
• BuildOptions.SymlinkLibraries – This Unity Editor IDE setting (more info) is completely unrelated to my technique above. Don’t be confused.
• GIT Submodules – This technique may replace the need for symlinks. I have not tried it yet.
• Feature Request – The community is passionately requesting Unity Technologies to allow ‘soft links’ to be recognized by Unity Editor IDE

What Do YOU Think?

Have a comment? Please post below. This is a hot topic and I’ll respond promptly over the next month.

In this post, I show the Microsoft coding conventions of C#. These are recommended by, but not required by, Unity Technologies for Unity’s C#. I compare those to my own RMC coding conventions (Rivello Multimedia Consulting).

It should be noted that the implementation of C# in Unity is based on Mono. Mono is a software platform designed to allow developers to easily create cross-platform applications. Sponsored by Xamarin, Mono is an open source implementation of Microsoft’s .NET Framework based on the ECMA standards for C# and the Common Language Runtime. As far as I can tell, Unity’s C# is the same as .NET’s C# in its approach to coding conventions.

Read the full, updated article at SamuelAsherRivello.com/coding-standards-csharp/

Unity 3D & C#

Unity3D is a powerful suite of tools (Project IDE, Code IDE, run-time) for game development.

As always, RivelloMultimediaConsulting.com/unity/ will be the central location for deep articles and tutorials, Facebook.com/RivelloMultimediaConsulting (like us!) will engage the growing RMC+Unity community, and for the latest opinions and cool links follow me at Twitter.com/srivello.

There is incredible momentum in the Unity3D product and its community.I recently posted “The Best C# Code Naming Conventions” and wanted to expand the discussion on best practices in this post below.

NOTE: I’m still working on this post, but wanted to get feedback on just the parts below. Drop a comment below.

Best Practices

Folder Organization

I created a custom menu option to create default folders.

I add these folders to a new project (or existing) when it is first created. I put 3rd party packages into the ‘Community Assets’. The ‘Standard Assets’ folder is of course where Unity puts its own packages. I then rename the ‘[Project Name]’ folder to match my current project. Any suggestions?

What Do YOU Think?

Have a comment? Please post below. This is a hot topic and I’ll respond promptly over the next month.

Unity3D & C# Training

There are MANY best practices included in my free, HD Video training series on “Unity3D & C#“. Check it out!

PROJECT-REQUIREMENTS

In software development, the focus is to offer value to the end users; to include features for their eyes. These are the functional-requirements of the project. But of course there is much ‘under-the-hood’ that the end user never sees. This includes content management systems (CMS) that administer the data, servers that provide that data, and developer tools and architectures to help organize the code-base. We call these ‘under-the-hood’ needs ‘non-functional’ requirements.

This quick primer answers “What non-functional requirements are necessary?”.

NON-FUNCTIONAL REQUIREMENTS

In each project, in addition to serving the end users goals, we must serve the needs of the development team; creating a realistic workflow for all team members, allowing for an extensible architecture for current and future functional-requirement features.

My point in writing this article was to get to a list of what non-functional requirements I setup in my apps or game needs. If you are already doing all this, great. MANY mistaken teams are doing NONE of these. Here is the list I use;

My Recommended Non-Functional Requirements

• Coding & Documentation Standards: Create a plan for coding standards and commenting practices. The plan should include a ‘bible’ written record of (what to do), the process and workflow to write the code as well as peer-review for compliance, and the buy-in from management to place priority (i.e. time in the calendar). Here are examples of my AS3 Standards and (in-progress) C# Coding Standards and recommended best practices e.g. Unity default folder structure. Consistency, pragmatism, and adoption are fundamentals here. Implementing such a plan is EXPENSIVE, so be sure everyone is on board. The benefits to readability, maintainability, and scalability are well-worth the effort.
  
• Configuration File – Upon project start-up, load an externalized set of name/value pairs (typically XML). This allows for developers (and others) to tweak values and reduces the need-for / frequency-of project recompilation. A huge side-benefits is that this ‘light and playful’ environment encourages experimentation.
• Localization – Even for English-only project, centralize (put all together) and externalize (separate from code – typically in XML) all display text. This allows for easier edits and translation to other languages if/when needed.
• Architecture – Sure, smart developers can create their own architectures, but smarter developers choose an off-the-shelf, 3rd-party architecture. Pave the cow-path, point your developers to 3rd party documentation and forums for help, and hire new staff (with experience in that architecture) more easily. If your team is not using ‘any’ architecture, that is probably a huge mistake. There are many available and are often specialized for each platform and project type (i.e. Flash Platform for Game project type)
• Restart Functionality – The app or game should have a restart button. This may be a functional-requirement. If so, great. If not, do it anyway. By requiring your team to implement restart (and garbage collection) your project will probably be far more efficiently written. This is an expensive feature to implement, but if done at the beginning it is very manageable.
• Zero-Memory-Leak Policy – The app or game may be ‘too simple to warrant optimization’. Regardless, do it anyway. Once you have the ‘Restart Functionality’ added, run a memory profiler tool on your project and ensure that with each restart the RAM usage properly reduces to zero (or whatever benchmark you set).  This is an expensive feature to implement, but if done at the beginning it is very manageable.

Game-specific Non-Functional Requirements

• The list above, plus…
• Pause Functionality – A fundamental test of good gaming architecture is ‘can it pause at any time?’. Even if ‘pause’ is not offered to the user, this requirement is helpful.
• Time-based animation – Your game algorithms should be infallible regardless of a faster-than-expected or slower-than-expected frame-rate.

CHAMPIONING DEVELOPERS’ RIGHTS

Depending on your team structure, you may have your software team developing the product ‘for’ the business team. Treating each department within your company as ‘clients’ helps to decouple the responsibilities and make hand-off of project tasks more clear and distinct. However each team, naturally defends their own interests, often at the expense of others. Within this setup, I’ve seen countless times that the dev-team must fight for the time to create non-functional requirements in addition to the functional requirements, where-as the business team’s focus is solely on the functional requirements. The business mind is concerned with ‘add a new button that does X or Y’ and to them that sounds simple. The Dev-team knows there is indeed a quick and dirty way to add that feature but also a more manageable, scalable, well-architected solution. It is a typical time vs quality discussion. Except the business team may not understand why spending more time (and money) is valuable when they don’t see more value in the end product.

Addressing developer’s needs helps to reduce burnout of your team. Happy developers are productive developers. Unproductive developers leave your team. Also an objective development leader can add ‘just enough’ non-functional requirements to respect the long-term plans of the project. Obviously a project with a long development cycle (days until launch) and long shelf-life (days between launch and unlaunch) benefits most from good non-functional requirements.

Arguing for the additional time needed to ‘do things right’ is a common struggle as dev teams champion their rights. Depending on the project, I can be on either side of this discussion. Generally I try to create an environment that makes the developers comfortable yet gets the job done. To facilitate that, I recommend separating time-estimations for functional-requirements from non-functional. One methodology is to take the total time estimate for the project or milestone’s functional requirements (including buffers for unknowns) and then calculate 20% additional. I offer developers that 20% to use as they see fit.

For example the business team can offer to the developers; “Ok, we all agree that our next milestone will take 400 man-hours; so you (developers) will get 480 and can allocate the 80 hours to improve code quality (beyond our minimum standards) and build-out the architecture (beyond today’s immediate needs).” Over-architecture and over-planning are dangerous, so giving free-reign to developers to ‘make it perfect’ is not cost effective, nor does it really improve the project or product. If developers feel they are hitting some (80% perhaps?) level of comfort with their code-base, that is a good balance. This is my personal opinion based on years of experience on hundreds of small to mid-size software projects.