Unity Packages

Why?

I have components that I like to reuse in various projects. One common way to get shared code in is to use submodules. Those suck. Another is to create a Unity project that will become a package that will be loaded via Unity's UPM system.

Turning Unity Project into a Package

There are two things required for a Unity project to work as a package:

• You need to ASMDEF file that includes all script files.
• You need to add a package.json to the Assets folder that looks like this

{
  "name": "com.your_organization.project",
  "displayName": "Project Name",
  "version": "0.0.1",
  "unity": "2019.4",
  "description": "Our new Unity package",
  "timestamp": 1659132295633,
  "timestamp_readable": "Fri, 29 Jul 2022 22:04:55 GMT",
  "dependencies": {
  }
}

Adding Custom Package To Unity

Inside the Unity project directory, there is sub directory "Packages". There you will find manifest.json which controls what packages Unity will load for this project. Most of these packages are hosted by Unity and are standard, and Unity knows where to find them. When it comes to custom packages, we will need to specify their location.

Open manifest.json and you will notice that it contains a list of packages and their versions.

{
  "dependencies": {
    "com.unity.ai.navigation": "1.1.5",
    "com.unity.cinemachine": "2.10.1",
    "com.unity.collab-proxy": "2.3.1",
    "com.unity.ext.nunit": "1.0.6",
    "com.unity.ide.rider": "3.0.28",
    "com.unity.ide.visualstudio": "2.0.22"
    ...
  }
}

First way we can do this is by pointing to a local Unity project. You just need to provide a relative path to the package. You can point to a Unity project on disk by providing a relative path like this:

{
  "dependencies": {
    "com.yourcompany.yourpackage": "file:../YourPackage/Assets",
    "com.unity.ai.navigation": "1.1.5",
    "com.unity.cinemachine": "2.10.1",
    "com.unity.collab-proxy": "2.3.1",
    "com.unity.ext.nunit": "1.0.6",
    "com.unity.ide.rider": "3.0.28",
    "com.unity.ide.visualstudio": "2.0.22"
    ...
  }
}

Unity can also treat GitHub repositories as a source for a package as long as they are configured correctly and correct URL is provided.

{
  "dependencies": {
    "com.yourcompany.yourpackage": "https://github.example.com/user/repo.git",
    "com.unity.ai.navigation": "1.1.5",
    "com.unity.cinemachine": "2.10.1",
    "com.unity.collab-proxy": "2.3.1",
    "com.unity.ext.nunit": "1.0.6",
    "com.unity.ide.rider": "3.0.28",
    "com.unity.ide.visualstudio": "2.0.22"
    ...
  }
}

You can find more info on how to set this up here: https://docs.unity3d.com/Manual/upm-ui-giturl.html.

Private Repositories

Since these packages are accessed via git, Unity has to be able to access them. You can make your package repository public, but that is not always an option. In this case, you might need to configure your computer to be able to access these git repositories, so for example you should be able to clone your repository via command line.

{
  "dependencies": {
    "com.yourcompany.yourpackage": "git+ssh://git@github.com/user/repo.git",
    ...
}

You can also specify git tags, branches, paths. This makes it possible to have multiple Unity package project in a single repository and they can be versioned independently of each other. This is probably an overkill for most projects out there. For a situation where we have a single project per repository, your URL would look like this:

{
  "dependencies": {
    "com.yourcompany.yourpackage": "git+ssh://git@github.com/user/repo.git?path=/YourPackage/Assets#v1.0.1",
    ...
}

Where you have a repository with a Unity project called YourPackage. There was a version 1.0.1 released and tagged with v1.0.1. Path should point to the location of the package.json inside the project.

Links

• Unity Package Manager: https://docs.unity3d.com/Manual/Packages.html