Tutorial: How to develop a package for UnityPackageManager

In Unity 2018.3, the Unity Package Manager (UPM) supports Git.
https://forum.unity.com/threads/git-support-on-package-manager.573673/

This update allows us to quickly install packages on code hosting services such as GitHub.
Alright, let's create a package for UnityPackageManager.

In this tutorial, we develop a package "RotateMe" that contains components that rotate objects.
I will not explain remote repository creation and Git installation.


TL;DR

  • Develop as you always do
  • Add asmdef file
  • Add package.json and documents
  • Execute "git subtree split" command and tag


Branch strategy

In this tutorial, I develop a package using two branches.
If necessary, add branches (eg. develop branch) as you like.

  • master branch: Package development is done in this branch.
  • upm branch: A branch for installing packages with UPM. Don't commit directly to this branch. Don't create this branch manually.


Directory structure

A common directory structure of a package for UPM is as follows:


However, as many Unity project repositories are, we will want "Assets" directory to be in the root.

Don't worry, in this tutorial we will develop a package using a common directory structure.
As you always do, you can develop a package.


Develop a package

Alright, let's develop on "master" branch.
Again, in this tutorial, we develop a component that rotates the object.
Save the following script in "Assets/RotateMe/Scripts/RotateMe.cs".

using UnityEngine;
public class RotateMe : MonoBehaviour
{
   public float angularVelocity = 10;
   void Update ()
   {
       var rot = Quaternion.AngleAxis (angularVelocity * Time.deltaTime, Vector3.up);
       transform.localRotation = rot * transform.localRotation;
   }

Also, Don't forget to add a demo scene.
A demo scene is a "workable" manual.
Users learn easily how to use it with a demo.


Add an asmdef file

If you are developing a package containing scripts, you should add an asmdef file.
https://docs.unity3d.com/2018.3/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html

When you create an asmdef file, scripts under that directory are compiled into separate assemblies.

The advantages of the asmdef file are as follows.

  • Compile time is shortened
  • Use "internal" access modifier instead of "public" access modifier, to make it inaccessible from outside a assembly
  • Allow unsafe code
  • .dll files can be referred to by a specific assembly only

If you enable "Test Assembly", the assembly is not included in the player build.


Add necessary documents

A package for UPM requires package.json as used in npm.
Save the following json in "Assets/RotateMe/package.json".

{
"name": "com.coffee.rotate-me",
"displayName": "Rotate Me",
"description": "Rotate the object!",
"version": "1.0.0",
"unity": "2018.3",
"license": "MIT",
"dependencies": {
 }
}

For details, see https://docs.npmjs.com/files/package.json.

README.md, CHANGELOG.md, LICENSE.md are optional documents, but they give useful information of the package to user.
Write these documents in "Assets/RotateMe" directory.


Development is completed

In the previous steps, the development of "RotateMe" package is completed.
Finally, "master" branch now looks like the following:

(If you don't consider UPM, export it as unitypackage and release it.)


Release the package for UPM

In order to release packages for UPM, we have to make directory structure for UPM.
Execute the "git subtree split" command as follows:

git subtree split --prefix=Assets/RotateMe --branch upm

This command put the "Assets/RotateMe" directory in "upm" branch.
Importantly, no other repository is necessary.

Next, add a tag to this branch and push to remote.
I recommend using semver for the tag name.

git tag 1.0.0 upm
git push origin upm --tags

Congrats!
The package "RotateMe" has been released!

Finally, the branch graph now looks like the following:



Install the package using UPM

Now, let's install the package "RotateMe" into another project using UPM.
Find "Packages/manifest.json" in another project and edit it to look like this:

{
 "dependencies": {
     "com.coffee.rotate-me": "https://github.com/mob-sakai/RotateMe.git#1.0.0",
     ...
 },
}

Or, use UpmGitExtension to install the package.


Continue to develop packages

Do the same to continue to develop the package.

  • Develop on "master" branch and update version in package.json
  • Execute "git subtree split"
  • Add tag and push

How easy it is!
You can release existing repositories for UPM using the same way.


Conclusion

In several steps, your project can be released for UPM.
How good is it if all Unity projects on GitHub support UPM?
Now, let's make your project to be supported UPM!

The repository of the package I made this time is here.
Please use it freely.
https://github.com/mob-sakai/RotateMe 


Please support me on Patreon, if you are interested. :)

Tier Benefits
Recent Posts