projeny project

http://casualient.com/5Xo

The purpose of Projeny is to allow your Unity3D project to easily scale in size without heavily impacting development time.

Projeny allows you to:

Share any Unity assets (code, scenes, prefabs, etc.) across multiple different Unity projects without copy and pasting
Instantly switch between platforms
Easily upgrade or downgrade installed asset store packages
Optimize compile time of your project by getting Unity to only recompile the code that changes most often
Split up your project into discrete packages, so that you can manage the dependencies between each, instead of having one giant Unity project of inter-related files
Declare dependencies between packages, so that you always get the packages that you need without needing to hunt down missing libraries or broken links
Generate a more intelligent Visual Studio solution than the Unity default, using package dependencies to create csproj dependencies
See below for details on how Projeny achieves all these features.

This project is open source. If you're interested in helping, great! There's still a number of features we'd like to support eventually (in particular we need help with supporting OSX).

NOTE: Projeny requires Unity3D 5.3.1 or higher, since it makes use of the -buildTarget command line switch is only fixed in 5.3.1

Table Of Contents

Installation
Overview
Advantages of Using Projeny
Shared files between projects
Package Organization and Asset Store integration
Near instant platform switching
Compile time optimization
Platform specific package folders
Dependency Management of Packages
More intelligent Visual Studio Solution generation
Usage Details
Managing Asset Store Assets / Releases
Using Multiple Package Folders
Sharing Project Settings
Gotchas With Directory Links
Frequently Asked Questions
How do I create a new package?
How do I create a new project?
How do I start an entirely new set of Projeny-based project from scratch?
How do I import Unity's Standard Assets?
Configuration Files
Projeny.yaml reference
ProjenyProject.yaml reference
ProjenyPackage.yaml reference
Custom Release Sources
Command Line Reference
Appendix
A. "Gotchas" with using external assemblies:
Release Notes
License
Installation

You can either run Projeny directly from source (requires python) or simply download the latest binary. Note that Projeny is currently only supported on Windows (with an OSX version planned for future releases).

From Binary

Go to the releases section and download the latest ProjenyInstaller.exe
Note that after installation completes, you will need to add the [Install Directory]/Bin directory to your windows path.
From Source

Clone this repo to a place on your hard drive
Make sure python 3.x is installed and that you have also installed the following:
pyyaml (to install run pip install pyyaml)
python for windows extensions (download here for your version of python)
Open UnityPlugin/Projeny.sln in Visual Studio
Build in Release Mode
Add the Projeny/Source/bin folder to your windows path
Overview

Projeny works by composing your Unity3D projects entirely out of 'directory links' (aka windows junctions aka symbolic links).

This is best shown with an example. After installing Projeny, download the sample project from the releases page and extract it to a new folder on your hard drive. The folder structure should appear like this:

Projeny.yaml
UnityPackages
AllMovers
CommonShapeMover
CubeMover
SphereMover
UnityProjects
ProjenyProject.yaml
AllMovers
ProjenyProject.yaml
ProjectSettings
CubeMover
ProjenyProject.yaml
ProjectSettings
SphereMover
ProjenyProject.yaml
ProjectSettings
Each folder in the UnityProjects directory represents an actual Unity3D project. Note that they each have the familiar ProjectSettings directory but they do not yet have an Assets directory. This is because these projects have not been initialized yet by Projeny. You'll also notice a file named Projeny.yaml at the root of the folder structure. This is a simple text file that is used to specify configuration settings for Projeny.

To initialize these Unity projects we must run Projeny from the command line. Open up command prompt or powershell and navigate to the root directory (the same directory where you will find Projeny.yaml). Then execute prj --init. If the prj command is not found, check that it has been added to your windows PATH variable, as mentioned in the install instructions. All this command does is initialize some of the the directory links for these projects.

If we look at our project folders again, we see that a bunch of new folders appear to have been added. Let's look at the CubeMover project in particular:

UnityProjects
CubeMover
ProjectSettings
CubeMover-Windows
Assets
CubeMover
Plugins
CommonShapeMover
Projeny
ProjectSettings
The CubeMover-Windows folder is new, and now has the familiar Assets directory. It also contains a bunch of folders within it such as CubeMover, CommonShapeMover, etc.

To actually run our project, open the CubeMover-Windows folder in Unity and then open the scene at CubeMover/CubeMain. After running it you should see the cube move around while changing colors.

So where did all these files come from? The answer is 'directory links' (aka windows junctions aka symbolic links). All of these new folders are not really folders in themselves but instead they are simply links to existing folders somewhere else.

In fact, if you're using source control, the entire CubeMover-Windows directory should be excluded from it (by using a .gitignore file, a .svnignore, .p4ignore, or whatever ignore method applies to the source control you're using). If you're using subversion or git, this will happen automatically when you initialize your project (otherwise, you will have to make sure to add the ignore files yourself).

We do this because the contents of the CubeMover-Windows folder does not itself contain any real content. It simply contains temporary files generated by Unity (such as the Library folder) and directory links to other directories that actually do contain content.

The directories containing the actual content can be found in the UnityPackages directory. This is where you will find the CubeMover and CommonShapeMover folders that we see linked to underneath the assets directory.

But how does Projeny know which packages to use for the CubeMover project? For this it reads from a configuration text file, which can be found at CubeMover/ProjenyProject.yaml. Details on this file are covered in another section below. This file can be changed by hand, but most of the time however you can use Projeny's built-in Unity plugin to manipulate this file instead. You can try this by opening the CubeMover project in Unity, then clicking the menu item Projeny -> Package Manager.... This window will be be explained in more detail in the following sections.

Advantages of Using Projeny

Ok so why are we doing this? Why go to the trouble of creating this seemingly complex directory structure of for every project? What's wrong with the standard way that Unity is designed?

We do this because it has many advantages over standard Unity development:

1 - Shared files between projects

By using directory links, you can have multiple Unity projects all using the same package folders, without needing to copy and paste each package per project. You can change a file such as a prefab or a C# file, and that change will be applied to all other projects that are using it as well

Previously, the best way to share code between different Unity projects was to put the code into a DLL and then output that DLL to all the Unity Projects that you want to use it in. This works ok but has a number of gotchas that make this approach difficult to do correctly.

Want to re-use some common utility code/prefabs in several different games? Just have multiple Unity projects for each game all using the same utility packages directly.

Want to just test one part of your game without needing to fire up the entire project? Just create another Unity project and reference only the parts of the game you want to test.

To see this in action, do the following: (Note: this assumes you have already run prj --init as described above)

Open Unity then open the project at UnityProjects/SphereMover/SphereMover-Windows
Open another copy of Unity then open the project at UnityProjects/CubeMover/CubeMover-Windows
Open the scene named SphereMain in the first Unity and the scene CubeMain in the second Unity
If you run them you should see the shapes move and change colors
The script used here to move both the Sphere and the Cube is the same, and can be found in the shared package CommonShapeMover.
As a further example, open up the Unity project at UnityProjects/AllMovers/AllMovers-Windows
Run the scene AllMovers
You should see both the cube and sphere in the same scene
This works because these three projects all have some shared packages. Note that this allows sharing code as well prefabs (ie. the cube and the sphere prefabs), scenes, etc.
2 - Package Organization and Asset Store Integration

Projeny allows you to much more easily manage many different Unity packages that you've created yourself, but also those packages that you've installed through the asset store.

You can build up a big collection of packages that you've purchased through the asset store and added to your UnityPackages directory, and then easily include or exclude those by simply selecting or not selecting them for each project. Projeny can also be used to easily upgrade/downgrade installed asset store packages all through a simple interface within Unity. See this section for more details on managing asset store packages through Projeny.

3 - Near instant platform switching

You might be wondering why the projects that you've been dealing with are all marked with the suffix '-Windows'. Or why there are multiple ProjectSettings folders that appear after you run the --init command as described above (One underneath CubeMover and another underneath CubeMover-Windows)

The reason for this is to allow Projeny to create entirely separate Unity project directories for each platform. This allows us to jump instantly from one platform to another without needing to wait for Unity to process all the assets.

In the examples above, we have only initialized the windows Unity project CubeMover-Windows but we can also create CubeMover-iOS, CubeMover-Android, etc. by opening these platforms for this project.

When that occurs, Projeny will create a directory link to the main ProjectSettings directory so that we can have all these different platform-specific projects use the same Unity project settings.

To see this in action, open up the CubeMover project in Unity then select the menu item Projeny -> Change Platform -> iOS. The first time you do this will take longer since Unity has to process the files but any subsequent times should be nearly instant, since it should be no different from simply opening another project.

4 - Compile time optimization

Unity compiles your project in multiple passes. The first pass compiles all C# files that are in the Plugins/ directory and the second pass compiles all other C# files. If Unity does not detect any changes in the Plugins/ directory then Unity will skip this first pass and only execute the second pass. (Note: This is a bit of a simplification - see here for full details)

We can take advantage of this by always putting all stable packages (such as those obtained through asset store) into the Plugins folder and putting the packages that we change frequently directly underneath the Assets folder.

And because we are using directory links, and the entire CubeMover-Windows folder is ignored by source control, changing the location of these directory links is trivial. You can modify this directory structure multiple times per day based on what you're working on, by simply using changing a few things in the Projeny Package Manager window.

To see this in action, open up the AllMovers-Windows project.

By default, the assets folder should appear as follows:

AllMovers
CommonShapeMover
CubeMover
Plugins
Projeny
SphereMover
If we are only working within the AllMovers project, there is no reason we need to be recompiling CommonShapeMover, CubeMover, and SphereMover projects every time a script changes. So these projects can be moved to be underneath the Plugins folder.

To do this, open up the package manager by clicking on the menu item Projeny -> Package Manager.... You should see something like this: