UPM Package Development

Unity Package Manager (UPM) brings the joy of package management to the Unity editor. Let’s evaluate UPM as a package management solution.

Overview

Pros

  • Supports private/internal package feeds
  • Supports modern authentication features
    • Per-user authentication
    • Personal access tokens can be assigned with read only permissions
  • Manage packages right from the Unity Editor
    • Per-project configuration
    • Add scoped registries
    • Install packages by name (instead of remembering long git URLs)
    • Update out-dated packages
    • Enforce package dependencies

Cons

  • Users must authenticate with scoped registries (even if the packages are public)
  • Unity may report erros every time it fetches from a GitHub scoped registry. These errors are typically trivial, but they can clutter the console.

Prerequisites

  • GitHub Account
  • NodeJS (Optional if you want to publish packages from your own machine)

Setup

  1. Develop your Unity package.

  2. Edit package manifest (package.json).

    1. Add publishConfig (Documentation).
    2. Add repository (Documentation).
"publishConfig":
{
    "registry": "https://npm.pkg.github.com/@AndtechGames"
},
"repository":
{
    "type": "git",
    "url": "git://github.com/AndtechGames/andtech.git"
}
  1. Login with NPM.

Run the following from a terminal:

$ npm login --registry https://npm.pkg.github.com

Follow the instructions to complete the login.

  1. Publish the package.
$ npm publish <PATH_TO_PACKAGE>

Usage

  1. Configure UPM authentication.
    • Create a user .upmconfig.toml file.
    • Add an entry for each package feed this machine will use.

For example:

[npmAuth."https://npm.pkg.github.com/@AndtechGames"]
token = "<PERSONAL_ACCESS_TOKEN>"
alwaysAuth = true

Generate a new personal accesss token (PAT) with at least the read:packages scope.

  1. Add the scoped registry to your Unity package.
    • Edit > Project Settings > Package Manager > Scoped Registries
    • Add a new scoped registry using the interface.

For example:

NameAndtech Games
URLhttps://npm.pkg.github.com/@AndtechGames
Scopecom.andtech
  1. Add Unity packages throught the Package Manager window.
    • Window > Package Manager > Add package from git URL…
    • Type the name of the package (ex. “com.andtech.core”)

Structure

<root>
  ├── package.json
  ├── README.md
  ├── CHANGELOG.md
  ├── LICENSE.md
  ├── Editor
  │   ├── [YouCompanyName].[YourPackageName].Editor.asmdef
  │   └── EditorExample.cs
  ├── Runtime
  │   ├── [YouCompanyName].[YourPackageName].asmdef
  │   └── RuntimeExample.cs
  ├── Tests
  │   ├── Editor
  │   │   ├── [YouCompanyName].[YourPackageName].Editor.Tests.asmdef
  │   │   └── EditorExampleTest.cs
  │   └── Runtime
  │        ├── [YouCompanyName].[YourPackageName].Tests.asmdef
  │        └── RuntimeExampleTest.cs
  └── Documentation~
       └── [YourPackageName].md

Trivia

  • UPM packages installed through a scoped registry will be cached here: %LocalAppData%\Unity\cache.

Note: if a package is found in the cache, Unity will skip authentication with the scoped registry.

  • As of Unity 2020.3, Unity Package Manager may report errors while communicating with GitHub package registries. You may ignore these errors.

References


412 Words

2021-03-26 22:53 +0000