This repository is a template for creating Unity packages. Unity packages are useful for creating separate features that can be easily imported into any other Unity project to reuse them. These packages can be automatically managed with the inbuilt Unity Package Manager, allowing developers to switch between different versions of the same package at any time. Packages can also define optional samples and their own dependencies that should be automatically downloaded alongside them. This template contains a complete Unity project, which can be used to develop and test the package, and then publish the inner package with three simple git commands.
Assets: all assets used for the development of the package are placed hereAssets should adhere to the normal unity folder structure (Scene, Resources, Materials etc.), assets placed here can be used to develop and test the package without having the test assets be included in the published package
/UnityPackage: all assets that should be part of the published package are placed underneath this directory
/Editor: all editor scripts such as custom editors or settings are placed here
/Runtime: all runtime scripts are placed here
/Samples~: optional samples of the package are placed here
Only assets underneath the Assets/UnityPackage will be part of the published package. Assets that are only used for developing and testing the package should therefore be outside the UnityPackage folder. The Editor and Runtime directories inside the UnityPackage directory should contain assembly definitions to make sure the contained assets are only included in the corresponding platform. The Editor assembly definition, if the package should even use a Editor directory, should also have a one-directional GUID reference to the runtime assembly definition.
The root directory of the repository should contain a LICENSE and a README.md file to allow Github to index them easily. Alongside the package.json the UnityPackage directory should contain a LICENSE.md, README.md and CHANGELOG.md file, which are linked to in the package.json and can be from viewed inside the Unity Package Manager UI.
For more information see Unity Package Layout.
Samples are optional features and assets that can be downloaded alongside the package from the Unity Package Manager. Samples can be used to provide example scenes, explanations, tests etc. for the users. Samples must be placed underneath the Samples~ folder inside the package and be defined in the package.json. To prevent Samples from being imported automatically alongside the rest of the package, the Samples folder must contain a character at the end of the folder name. This hides the folder from Unity, and allows users to selectively import samples from the Package Manager UI. Because the must be added back to the samples folder, hiding the folder from Unity, it can be annoying to develop the samples in the provided template project. It is therefore recommended to have two separate branches (ex.: develop and main). All changes should first be made on develop and then be merged to the main branch, where the package can be published. On the develop branch the Samples directory should not contain the character. Once a new sample is added to the project, a new commit should be made, where the character is added to the folder name ONLY on the main branch. This enables you to develop the sample on the develop branch and have the ~ automatically be added everytime you merge your changes to the main branch.
Samples should have the following folder structure:
Samples~
/SAMPLE_NAMEnormal Unity folder structure
For more information see Unity Samples.
When using the template to create a new Unity package project, make sure to first adjust the Unity project version. Then update the Edit > Project Settings > Player CompanyName, Product Name and Version. Also update the UnityPackage/package.json values, like name (ex.: de.htw-berlin.centis.project-name), display name, version, URLs, author and samples. The version number in the Player settings and package.json should adhere to the SemVer format.
To publish the package it is recommended to make all changes on the develop branch, then merge the changes to the main branch and publish the package from there. Before publishing make sure to update the version number in the Edit > Project Settings > Player settings and the UnityPackage/package.json. Also make sure that if any samples are present, they have a ~ character at the end of the Samples directory name. Once the main branch and version is updated, the package can be published from the Git Bash tool. Using the commands:
git subtree split --prefix=Assets/UnityPackage --branch upm
git tag VERSION upm
git push origin upm --tags
the local package version can be published under a new tag on the Unity Package Manager (upm) branch. When using the commands make sure to replace the VERSION with the SemVer version number for the package. All files underneath the UnityPackage directory are then published with the Git tag on the upm branch. After publishing the branch, no commits must be made to the upm branch. To update the package, simply change the version number and run the commands with the new version again. The published tags and package version can be viewed on Github in the Release > Tag section.
To import the package into a new Unity project paste the package URL in the Window > Package Manager > + > Add package from git URL... field. The package URL is the HTTPS URL (ex.: https://github.com/FKI-HTW/UnityPackageTemplate.git) with a #upm for the most recently published version or #VERSION_TAG at the end. The complete URL for a specific version of a package could look something like this: https://github.com/FKI-HTW/UnityPackageTemplate.git#1.2.3.
If you are developing a package, you can also import the package from Github into a Unity project without creating a new tag or package branch, by directly specifiying the desired package directory in the URL. This can be done by using the path specificer ?path=at the end of the URL (ex.: ?path=/subfolder2/subfolder3). This can also be combined with a tag or branch revision specifier (ex.: https://github.com/FKI-HTW/UnityPackageTemplate.git?path=/subfolder2/subfolder3#1.0.0). For more information see URL Specifier.