Release Unity Package

Since Unity 2019 it is possible to use the package manager to install packages into Unity projects. With it, it is possible to add functionality (code & assets) from a repository directly into Unity and update it if necessary.

At Immersive Arts Space we create a lot of software that is reusable in many projects. The software itself is usually developed in an already existing project or a demo project. This tutorial goes step by step through the process of releasing just a part of a project as NPM package to our private repository.

Prepare Package

Usually new software is developed in an actual project to directly test it and adjust on the fly. As soon as it is ready to be shared, the code has to be restructured in a specific manner to be used as Unity package. The package layout usually contains a Runtime folder with all the code and assets, as well as a package.json file that contains meta info about the package.

In this example we are going to publish the SRT package, which contains tools to add a SRT subtitle file to a Unity video player. The current structure evolved by creating the software, so it is not structured as a package yet:

  • Assets
    • SRT
      • Editor
        • SrtImporter.cs
      • Subtitle.cs
      • SubtitleDocument.cs
      • SubtitlePlayer.cs

To create a valid Unity package, we are going to add a Runtime folder in the root folder of SRT and move all code into it. All the Editor scripts are moved into the Editor folder (where they already are). As a second step we have to tell the compiler how to treat the source code files. This is done with an assembly definition (asmdef) per subfolder, containing the following information:

Assets/SRT/Runtime/SRT.Runtime.asmdef

{
  "name": "SRT.Runtime",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": []
}

Assets/SRT/Editor/SRT.Editor.asmdef

{
  "name": "SRT.Editor",
  "references": [],
  "includePlatforms": ["Editor"],
  "excludePlatforms": []
}

If you have dependencies to other packages, include the into the references list ("references": ["OscJack.Runtime"]).

To add more meta data information about the project, we also have to add a package manifest (package.json), which contains a name, description and version:

{
  "author": "Immersive Arts Space",
  "name": "ch.iaspace.srt",
  "displayName": "SRT Subtitle",
  "description": "Add SRT subtitles to a video player.",
  "version": "0.1.0",
  "unity": "2019.3",
  "keywords": [ "unity", "video", "subtitle", "srt", "text" ],
  "relatedPackages": {},
  "dependencies": {}
}

It is important to use “ch.iaspace.” as a prefix for your package. It is called a package scope and is used later to discover all IASpace projects.

The structure should now look like this:

  • Assets
    • SRT
      • Editor
        • SrtImporter.cs
        • SRT.Editor.asmdef
      • Runtime
        • Subtitle.cs
        • SubtitleDocument.cs
        • SubtitlePlayer.cs
        • SRT.Runtime.asmdef
      • package.json

If you want to add an extended description to the package, use a readme.md file in the root folder of the project.

Publish to IASpace NPM

It is possible to publish this package now to NPM. We at IASpace use our own internal NPM system based on Verdaccio to have more control over the packages and their accessibility.

First you have to login (username & password are in the password list) into the private repository and then you can publish the package:

npm login --registry http://telemersion.zhdk.ch:4422/
npm publish --registry http://telemersion.zhdk.ch:4422/

Now your package should be available on the verdaccio NPM: http://telemersion.zhdk.ch:4422/-/web/detail/ch.iaspace.srt

Add Package to Unity

To add a published package to Unity, you have to add a scoped registry to the Packages/manifest.json file of your Unity project and the dependency.

{
  "scopedRegistries": [
    {
      "name": "IASpace",
      "url": "http://telemersion.zhdk.ch:4422/",
      "scopes": [ "ch.iaspace" ]
    }
  ],
  "dependencies": {
    "ch.iaspace.srt": "0.1.0",
  }
}

It would also be possible to directly use the Unity package manager, if the scoped repository is already added:

Last updated bymartin froehlich