com.playdarium.unity.package-tools
v2.0.7
Published
Tool for create unity packages
Downloads
14
Readme
Package Tool
Installing
Using the native Unity Package Manager introduced in 2017.2, you can add this library as a package by modifying your
manifest.json
file found at /ProjectName/Packages/manifest.json
to include it as a dependency. See the example below
on how to reference it.
Install via OpenUPM
The package is available on the npmjs registry.
Add registry scope
{
"dependencies": {
...
},
"scopedRegistries": [
{
"name": "Playdarium",
"url": "https://registry.npmjs.org",
"scopes": [
"com.playdarium.unity"
]
}
]
}
Add package in PackageManager
Open Window -> Package Manager
choose Packages: My Regestries
and install package
Install via GIT URL
"com.playdarium.unity.package-tools": "https://gitlab.com/pd-packages/package-tool.git#upm"
Setting up your first package
Creating your first package is a simple process that can be made more complex because information available about Unity Package manager is inconsistent right now. This is largely due to it not being widely and officially supported for end-users of Unity yet, but starting with 2019.1 will gain more official support.
The first step is to create a PackageManifestConfig
asset that we can use to define the properties and contents of our
package. This can be done by right-clicking in the Project
window and
selecting Create -> JCMG -> Package Tools -> Package
Manifest Config
. This will create an asset named PackageManifestConfig
in that folder.
A PackageManifestConfig
is broken up into two sections:
- Package Json: This section contains fields relating to properties of the
package.json
file that we will need to have in our package root folder. It describes the minimum Unity version that it is compatible with and the version of the package itself Semantic versioning, a description of the package, and any dependencies it has on other packages. This last part I have the least information about, but is supposed to gain more widespread support in 2019.1. - Package Content and Export: This section focuses on defining the folders/files that make up the content (including
code and assets) that make up the package itself and a location that the content will be published to when clicking on
the button labeled
Export Package Source
.
For convenience sake, I have added file and folder pickers as buttons to the right of these fields that make it easier to add relative file/folder paths from the Assets folder for package source and export location.
There are also options for excluding specific files and/or folders from the package source that might otherwise be included. This can be useful for example, if there are unit tests or example content located within your package source path that you would not want to include directly or indirectly. Folders and files can be excluded by adding them to the ExcludePaths list.
Recently I have found myself manually creating a VersionConstants
static class containing versioning information about
the package itself. This can be useful for displaying to a user or checking for updates outside of the native Unity
PackageManager window.. Since updating this file by hand can be error-prone or easy to forget, this can now be
configured on a PackageManifestConfig
and generated using a new action Generate VersionConstants.cs
on the config's
inspector.
Example VersionConstants.cs used in JCMG.PackageTools
namespace JCMG.PackageTools.Editor
{
/// <summary>
/// Version info for this library.
/// </summary>
internal static class VersionConstants
{
/// <summary>
/// The semantic version
/// </summary>
public const string VERSION = "1.3.0";
/// <summary>
/// The branch of GIT this package was published from.
/// </summary>
public const string GIT_BRANCH = "develop";
/// <summary>
/// The current GIT commit hash this package was published on.
/// </summary>
public const string GIT_COMMIT = "57aec574ed19746de42ffa5032358562fb041ebf";
/// <summary>
/// The UTC human-readable date this package was published at.
/// </summary>
public const string PUBLISH_DATE = "Friday, May 1, 2020";
/// <summary>
/// The UTC time this package was published at.
/// </summary>
public const string PUBLISH_TIME = "05/01/2020 08:26:31";
}
}
The contents of this file can be configured based on the use of a text template. A default one is provided
at JCMG\PackageTools\Scripts\Editor\Templates\VersionConstants.txt
and a custom template can be used instead by
providing it's meta GUID on the PackageManifestConfig
versionTemplateGuid
field. There is an example of this in the
development project
Example Template
namespace JCMG.PackageTools.Editor
{
/// <summary>
/// Version info for this library.
/// </summary>
internal static class VersionConstants
{
/// <summary>
/// The semantic version
/// </summary>
public const string VERSION = "${version}";
/// <summary>
/// The branch of GIT this package was published from.
/// </summary>
public const string GIT_BRANCH = "${git_branch}";
/// <summary>
/// The current GIT commit hash this package was published on.
/// </summary>
public const string GIT_COMMIT = "${git_commit}";
/// <summary>
/// The UTC human-readable date this package was published at.
/// </summary>
public const string PUBLISH_DATE = "${publish_date}";
/// <summary>
/// The UTC time this package was published at.
/// </summary>
public const string PUBLISH_TIME = "${publish_utc_time}";
}
}
Generating packages from command-line
It can be desirable at times to generate legacy Unity packages and/or package source from the command-line so that they can be created and distributed as part of a continuous integration (CI) process. For example, you may want to trigger a process every time the repository is updated and source files changed so that a new package is created and made available to users. This can be done by launching the Unity Editor from the command line and supplying the appropriate arguments.
Example Command-Line Call
"D:\Program Files\2019.4.11f1\Editor\Unity.exe" -quit -batchmode -executeMethod JCMG.PackageTools.Editor.PackageToolsCI.Generate version=1.0.1 GenerateVersionConstants=true
In this case, the -executeMethod JCMG.PackageTools.Editor.PackageToolsCI.Generate
is the CLI argument that will
trigger the PackageTools CI process to execute. By default, this will find all PackageManifestConfig
instances in the
project and if they have an appropriate output path will generate the legacy Unity package and/or package source.
Progress will be output to the Unity Editor player log.
Arguments
ID
An optional ID
CLI argument (case-insensitive) that can be supplied with one or more ID
values to limit the package
generation to a subset of PackageManifestConfig
instances in the project if so desired. These ID
values should
correspond to the ID
displayed on the PackageManifestConfig
inspector for that instance. If not supplied, all
Example ID Argument Usage (for three ID values passed)
id=cb87cda2-0bfa-44dc-b583-ae61ff81efcb,e1725f4a-f9f3-42c0-ac15-756f017c90ed,6a406891-59d5-430a-815d-c252deae5d5b
Version
An optional Version
CLI argument (case-insensitive) can be supplied which will both override and set the value of the
package version used on the PackageManifestConfig
packageVersion
field. This can be useful where the semantic
package version value should be coming from an external source to the Unity project.
GenerateVersionConstants
An optional GenerateVersionConstants
CLI argument (case-insensitive) can be supplied which will force
the VersionConstants
file to be written out prior to generating the package (if a path is specified for it on
the PackageManifestConfig
). This can be useful where this file is created as a result of a CI build and has it's
version number set by the version
argument.