Skip to content

Unity package management

To distribute Unity assets to the main Unity game project, the asset projects should structure the content for GitHub packages.

Setup Unity Asset package

There are two different types of packages [1]: * Embedded package * Local package

These instructions will go through setting up an embedded package, as it (looks like it) enforces a more decoupled and structured asset distribution.

This could be an incorrect assumption. But as stated in [1], local packages does not care about the placement of the package folder, and the setup during package development could differ from the usage of the package. With this in mind, please go for an embedded package.

Create the package folder

The package content needs to be placed in a specific package folder following the Unity package structure [2]. The folder need to be placed in the Package folder of the Unity asset project:

Packages/com.wis.<your-package-name>.

While not mandatory, the naming standard for unity packages seems to be com.<company/project/repo etc>.<package-name>. That means that the terrain generation (qmap) for wis would be com.wis.qmap. This ensures package names are globally unique.

Create a package.json for your package in your package folder

The information of the package like current version number, name, dependencies etc. are placed in a package.json. Add it in the newly created package folder, and update it according to the package manifest [3].

GitHub specifics

Some of the values in the package.json need some special attention because of GitHub.

repository

The repository parameter defines where the content of the package are defined, namely which repository, and where within the repository the root folder of the package is located. So here we define:

  "repository": {
    "type": "git",
    "url": "git://github.com/devlopstudios/wis.git",
    "directory": "<path/to/the/package/folder/in/repo>"
  },
publishConfig

This defines in which registry the package should be registered. As discussed, to keep the code and its package as close as possible, the registry is GitHub. So to define the correct registry, the following publishConfig parameter is defined as follows:

  "publishConfig": {
    "registry": "https://npm.pkg.github.com/@devlopstudios"
  },

This tells npm that it should be pushing to the GitHub registry, and the owner of the packages is @devlopstudios

Publish the package

The process of publishing the package requires authentication to the registry and then publishing the content.

Authenticate using .npmrc

To publish the package, you need to authenticate towards the repository. The preferred way is to create a .npmrc file that contains credentials to the GitHub repository.

Create the .npmrc file in the package root. The whole content of the .npmrc file is

registry=https://npm.pkg.github.com/devlopstudios 
_authToken=<personal-github-token-with-publish-rights>

To create a personal GitHub token, see here [4]. Ensure the token has at least the rights to write:packages.

TODO: Make a better solution that does not involve storing the service token in the repository.

Publish

npm publish

Install custom package

When a package is published it can be added to a Unity project. To be able to access custom packages from GitHub, the GitHub registry has to be registered in Unity. GitHub also requires authentication whenever fetching a package. When all is setup, add the package by name through the Unity package manager.

Register GitHub register

To be able to access the GitHub registry, it has to be registered in Unity. It can be done through Unity UI, but easiest is just adding the following in the Packages/manifest.json:

"scopedRegistries": [ { "name": "Wis", "url": "https://npm.pkg.github.com/@devlopstudios", "scopes": [ "com.wis" ] } ], This includes the GitHub registry when searching for packages.

Authenticate using .upmconfig.toml

Unity has to authenticate towards the GitHub registry whenever fetching the custom packages. Unity does this using a .upmconfig.toml. The details of its creation is listed here: [5]

Mainly, these are the required steps:

  • Install npm [6]
  • Login to the GitHub registry using
    npm login --scope=@devlopstudios --registry=https://npm.pkg.github.com
    Supply the GitHub credentials username and GitHub personal token [4] The token from Authenticate using .npmrc
  • This generates a .npmrc file in %USER%/.npmrc. It should look something like //npm.pkg.github.com/:_authToken=ghp_<token> @devlopstudios:registry=https://npm.pkg.github.com/
  • Create (if it does not already exist) the file %USER%/.upmconfig.toml. Here we place the information Unity uses to authenticate towards GitHub when fetching packages. Add the following lines to the file: [npmAuth."https://npm.pkg.github.com/@devlopstudios"] token="<personal-github-token>" email="<your-email>" alwaysAuth=true

Install the custom package to the project

Now all is prepared for the project to install the custom package. This is done through Unity using the Unity package manager.

Enter Unity and open up the Package manager. Select Add package by name...

Then type the name of the package as you defined it in "name"in the Create a package.json for you package in you package folder. For example, the terrain generator is named com.wis.qmap. Add that package by simply typing com.wis.qmap in the name field, and it should be added.

After it has been installed, the package is available in Packages/com.wis.qmap/

Last update: 2023-07-21

Comments