Unity Package Manager

Unity is a platform that exists for a long time and is constantly evolving. However, working in it with several projects at the same time, you can still encounter difficulties in using common sources (.cs), libraries (.dll) and other assets (images, sounds, models, prefabs). In this article we will tell about our experience with the native solution of such a problem for Unity.

Methods of sharing common resources

There is more than one way to use shared resources for different projects, but each approach has its pros and cons.



1. Duplication - "hands" duplicate resources between projects.

')

Pros:

• Suitable for all kinds of resources.
• No problem with addictions.
• No problem with asset GUIDs.

Minuses:

• Giant repositories.
• No possibility of versioning.
• The difficulty of tracking changes in shared resources.
• The complexity of updating shared resources.

2. Git submodules - distribution of shared resources through external submodules.



Pros:

• You can work with the source.
• You can distribute assets.
• No problem with addictions.

Minuses:

• Git skill required.
• Git is not very friendly with binary files - you have to connect LFS.
• Access control for repositories.
• Difficulties with raising and lowering the version.
• There may be collisions of GUIDs and there is no unambiguous behavior on the part of Unity to resolve them.

3. NuGet - distribution of shared libraries through NuGet-packages.



Pros:

• Convenient work with projects that are independent of Unity.
• Convenient versioning and dependency resolution.

Minuses:

• Unity does not know how to work with out-of-the-box NuGet packages (on GitHub you can find the NuGet Package Manager for Unity, which fixes this, but there are nuances).
• Difficulties in the distribution of other types of assets.

4. Unity Package Manager - sharing of common resources through the native solution for Unity.



Pros:

• Native interface for working with packages.
• Protection against overwriting .meta files in packages with GUID conflicts.
• The possibility of versioning.
• The ability to distribute all types of resources for Unity.

Minuses:

• GUID conflicts may still occur.
• No documentation for implementation.

The latter method has more advantages than disadvantages. However, it is not very popular now because of the lack of documentation, and therefore we will focus on it in detail.

Unity Package Manager

Unity Package Manager (hereinafter UPM) is a package management tool. It was added to Unity 2018.1, and it was used only for packages that were developed by Unity Technologies. However, starting from version 2018.3, the ability to add custom packages has appeared.





Unity Package Manager Interface



Packages do not fall into the source of the project (directory Assets). They are in a separate directory %projectFolder%/Library/PackageCache and do not affect the project in any way, their only mention in the source code is in the packages/manifest.json file.





Packages in the project file system

Package Sources

UPM can use several package sources:



1. File system.



Pros:

• Speed ​​of implementation.
• Does not require third-party tools.

Minuses:

• The complexity of versioning.
• A common file system access is required for all who work with the project.

2. Git repository.



Pros:

• All you need is a git repository.

Minuses:

• You cannot switch between versions through the UPM window.
• Does not work with all Git repositories.

3. npm repository.



Pros:

• Fully supports UPM functionality and is used to distribute official Unity packages.

Minuses:

• Currently ignores all string versions of packages except “-preview”.

Below we look at the implementation of UPM + npm. This bundle is convenient because it allows you to work with any kind of resources and manage package versions, and also fully supports the native UPM interface.



Verdaccio can be used as an npm repository. There is detailed documentation for it, and to launch it you will need just a couple of commands.

Setting up the environment

First you need to install node.js.

Build Package

To create a package, you must place the file package.json , which will describe it, in the directory with the contents of this package. You need to do the following:

1. Go to the project directory that you want to make a package.
2. Run the npm init command and enter the necessary values ​​during the dialog. For name, specify the name in the reverse domain format, for example, com.plarium.somepackage .
3. To conveniently display the package name, add the displayName property to package.json and fill it.
4. Since npm is js-oriented, there are no main properties and scripts in the file that Unity does not use. It is better to remove them in order not to litter the package description. The file should look something like this:
   
   
   
   

    { "name": "com.plarium.somepackage", "displayName": "Some Package", "version": "1.0.0", "description": "Some Package Description", "keywords": [ "Unity", "UPM" ], "author": "AUTHOR", "license": "UNLICENSED" } 

   
   
   
5. Open Unity and generate a .meta file for package.json (Unity does not see assets without .meta files, packages for Unity are opened only for reading).

Sending package

To send a package, execute the following command: npm publish --registry * * .

Installing and updating packages through the Unity Package Manager

To add a package to a Unity project, you need:

1. Include package source information in the manifest.json file. To do this, you need to add the scopedRegistries property and specify the scopes and the source address by which specific scopes will be searched.
   
   
   
   

    "scopedRegistries": [ { "name": "Main", "url": "   ", "scopes": [ "com.plarium" ] } ] 

2. Go to Unity and open the Package Manager window (working with custom packages is no different from working with built-in packages).
3. Select All Packages.
4. Find the right package and add it.

Working with sources and debugging

For the source to connect to the project, you must create an Assembly Definition for the package.



Using packages does not limit debugging capabilities. However, when working with packages in Unity, you cannot go to the IDE by clicking on an error in the console if an error occurred in the package. This is due to the fact that Unity does not see the scripts as separate files, because when using Assembly Definition they are collected in the library and connected to the project. When working with source code from the project, a click to the IDE is available.



Script in the project with the connected package:





The script from the package with a working breakpoint:

Urgent fix packs

Unity packages added to the project are open for reading only, but they can be edited in the package cache. For this you need:

1. Go to package in package cache.
   
   
   
   
   
   
   
   
2. Make the necessary changes.
3. Update version in package.json file.
4. Send the package npm publish --registry * * .
5. Update version of the package to the corrected via the UPM interface.

Package Import Conflicts

When importing packages, the following GUID conflicts may occur:

1. Package - package. If, when importing a package, it turns out that already added packages contain assets with the same GUID, assets with matching GUIDs from the imported package will not be added to the project.
2. Package - the project. If when importing a package it turns out that there are assets in the project with matching GUIDs, then the assets from the package will not be added to the project. However, assets dependent on them will begin to use assets from the project.

Transfer assets from project to package

If you transfer an asset from a project to a package with Unity open, its functionality will be preserved, and links in dependent Assets will begin to use an asset from the package.



Important : when copying an asset from a project to a package, a “Package - project” conflict will occur, as described in the section above.

Possible solutions to conflicts

1. Reassigning GUIDs by their own algorithms when importing all assets to eliminate collisions.
2. Add all assets to one project and then divide them into packages.
3. Creating a database containing the GUIDs of all assets, and carrying out validation when sending packages.

Conclusion

UPM is a new solution for sharing shared resources on Unity, which can be a worthy alternative to existing methods. The recommendations described in the article emerged on the basis of real cases. We hope they will be useful to you.