Symlinking your code framework in Unity3D

July 10, 2014 devblog, Firefly Framework, Unity no comments

When building games or applications in Unity3D, you could stumble over the fact that you probably will be using a (or more) code framework(s) to boost your development productivity. I can say that, at ignisvr.com, we do and our framework is called the “Firefly Framework”.

A common problem when using a framework with Unity3D, is the fact that you will quickly end up with lots of copies of your framework in all your Unity3D projects and extending or improving your framework can become quite a puzzle.


Unity quotes.

Assets/Firefly-Framework is a symbolic link. Using symlinks in Unity projects may cause your project to become corrupted if you create multiple references to the same asset, use recursive symlinks or use symlinks to share assets between projects used with different versions of Unity. Make sure you know what you are doing.

It is true … when using symbolic links you indeed need to make sure that you know what you are doing.

Circular references, also when we are coding, are indeed showstoppers! However .. any sane developer should be able to avoid those when his or her brain is making the right connections.

The wonderful Unity3D meta files that identify the uniqueness of your source files and other assets will mess things up when they are structurally changed across different Unity versions so that needs to be avoided as well.

I do not have had the pleasure to check all kinds of assets while working with my symbolic linked framework, but … at this point¬† in time, putting your C# framework code into a symbolic linked folder seems to work like a charm!

How to set it up …

The instructions below are for windows. I use windows 8 – 64bit.

  • Install a link shell extensions module.


    Windows has native symbolic link support on NTFS since NT4 and Windows 2000, but never implemented good explorer support for it. The tool above adds functionality to the window explorer to create symbolic links in windows folders.

  • Manage your framework project in a GIT or a dedicated Unity3D project.

    You only need to manage your project on one specific place. This can be a checked-out GIT or other Code Repository system, or some Unity3D project that will be your framework’s base. In our situation we use BitBucket ( free code repositories – 5 users ) for our online code repository and the Unity3D AssetServer ontop of that to store each project online and work collaboratively with multiple people.

  • Replace the framework code in your projects with a symbolic link

    This way every project will be looking at the exact same framework code and all framework improvements that you implement will be done in your framework’s base projects. The meta files will identify your assets and source files so integration with your GIT and assets server will run smoothly. Your framework’s code WILL be stored (as a copy) in each project’s asset server repository automatically.

Some important side notes
  • Finalizing a project.

    When finalizing a project, make sure you remove the symbolic link and place a copy of the current framework into your project’s folder at the same spot. This way, when you would access your old projects at a later time, your code won’t break because of future changes/extensions of the framework.

  • GIT is leading.

    When using a setup with GIT, Asset Server and multiple developers, make sure you always update your local framework to the latest GIT version, before comitting your code to the Unity Asset Server. The Asset Server project should reflect the latest stable GIT state.

  • Branches/Forks ??!!

    I did not use/make any branch scenarios, but I can imagine that, when you use this kind of scenario, you will have to give each branch its own symbolic link and you probably will have to change the symbolink link in the specific project before switching in GIT. Can be tricky I imagine!! So be careful there…

About the author

Alround development specialist with programming roots going back to the early 80's on a ZX-81, went for commodore 64 and Amiga and ended up after a lots of programming adventures coding C# in Unity3D. ( among lots of other things... )

Join the discussion

Your email address will not be published. Required fields are marked *