Unity Package Template

<img width="100%" alt="Stats" src="https://user-images.githubusercontent.com/9135028/198754538-4dd93fc6-7eb2-42ae-8ac6-d7361c39e6ef.gif"/>

Unity Editor supports NPM packages. It is way more flexible solution in comparison with classic Plugin that Unity is using for years. NPM package supports versioning and dependencies. You may update / downgrade any package very easily. Also, Unity Editor has UPM (Unity Package Manager) that makes the process even simpler.

This template repository is designed to be easily updated into a real Unity package. Please follow the instruction bellow, it will help you to go through the entire process of package creation, distribution and installing.

Steps to make your package

1️⃣ Click the button to create new repository on GitHub using this template.

2️⃣ Clone your new repository and open it in Unity Editor

3️⃣ Rename Package

Your package should have unique identifier. It is called a name of the package. It support only limited symbols. There is a sample of the package name.

com.github.your_name.package

• 👉 Instead of the word package use a word or couple of words that explains the main purpose of the package.
• 👉 The name should be unique in the world.

Option 1: Use script to rename package (recommended)

For MacOS

For Windows

cd Commands
.\package_rename.bat Username PackageName

Option 2: Manual package rename

Follow the instruction - manual package rename

3️⃣ Customize Assets/root/package.json

• 👉 Update name

  Sample: com.github.your_name.package Instead of the word package use a word or couple of words that explains the main purpose of the package. The name should be unique in the world.

• 👉 Update unity to setup minimum supported Unity version

• 👉 Update

  • displayName - visible name of the package,
  • version - the version of the package (1.0.0),
  • description - short description of the package,
  • author - author of the package and url to the author (could be GitHub profile),
  • keywords - array of keywords that describes the package.

4️⃣ Do you need Tests?

<details> <summary><b>❌ NO</b></summary>

• 👉 Delete Assets/root/Tests folder
• 👉 Delete .github/workflows folder

</details>

<details> <summary><b>✅ YES</b></summary>

• 👉 Make sure you executed package-rename script from the step #2. If not, please follow manual package rename instructions

• 👉 Add GitHub Secrets

  At the GitHub repository, go to "Settings", then "Secrets and Variables", then "Actions", then click on "New repository secret"

  1. Add UNITY_EMAIL - email of your Unity ID's account
  2. Add UNITY_PASSWORD - password of your Unity ID's account
  3. Add UNITY_LICENSE - license content. Could be taken from Unity_lic.ulf file. Just open it in any text editor and copy the entire content
     1. Windows: The Unity_lic.ulf file is located at C:/ProgramData/Unity/Unity_lic.ulf
     2. MacOS: /Library/Application Support/Unity/Unity_lic.ulf
     3. Linux: ~/.local/share/unity3d/Unity/Unity_lic.ulf

</details>

4️⃣ Add files into Assets/root folder

Unity guidelines about organizing files into the package root directory

  <root>
  ├── package.json
  ├── README.md
  ├── CHANGELOG.md
  ├── LICENSE.md
  ├── Third Party Notices.md
  ├── Editor
  │   ├── [company-name].[package-name].Editor.asmdef
  │   └── EditorExample.cs
  ├── Runtime
  │   ├── [company-name].[package-name].asmdef
  │   └── RuntimeExample.cs
  ├── Tests
  │   ├── Editor
  │   │   ├── [company-name].[package-name].Editor.Tests.asmdef
  │   │   └── EditorExampleTest.cs
  │   └── Runtime
  │        ├── [company-name].[package-name].Tests.asmdef
  │        └── RuntimeExampleTest.cs
  ├── Samples~
  │        ├── SampleFolder1
  │        ├── SampleFolder2
  │        └── ...
  └── Documentation~
       └── [package-name].md

Final polishing

• Update the README.md file (this file) with information about your package.
• Copy the updated README.md to Assets/root as well.

⚠️ Everything outside of the root folder won't be added to your package. But still could be used for testing or showcasing your package at your repository.

5️⃣ Deploy to any registry you like

• Deploy to OpenUPM (recommended)
• Deploy using GitHub
• Deploy to npmjs.com

6️⃣ Install your package into Unity Project

When your package is distributed, you can install it into any Unity project.

Don't install into the same Unity project, please use another one.

• Install OpenUPM-CLI

• Open a command line at the root of Unity project (the folder which contains Assets)

• Execute the command (for OpenUPM hosted package)

  openupm add YOUR_PACKAGE_NAME
  

Final view in Unity Package Manager